Corsair Bubble 插件实战指南通过 Data API 与 Workflow API 连接无代码应用数据【免费下载链接】corsairConnect your users to their apps项目地址: https://gitcode.com/GitHub_Trending/corsa/corsairBubble 是一款无代码应用构建平台它提供的 Data API 与 Workflow API 是外部系统读写其数据库、触发其业务流程的标准通道。corsair-dev/bubble是 Corsair 生态中的 Bubble 插件位于 packages/bubble将上述两组 API 封装为 10 个类型安全、带权限分级与错误重试策略的端点。阅读本文后你将掌握该插件的安装方式、完整端点清单、API Key 认证配置、Bubble 应用名与自定义域名解析规则以及 Data API 增删改查、批量创建与 Workflow API 调用的底层实现原理。插件概览与安装corsair-dev/bubble是 Corsair 的官方 Bubble 插件通过 package.json 声明其职责为 Bubble (Data API Workflow API) plugin for Corsair。它依赖corsair 0.1.0与zod ^4.1.13后者用于端点的输入输出 Schema 校验以 ESM 模块形式发布提供dist/index.js与类型声明dist/index.d.ts。安装命令项目使用 pnpm workspace 管理pnpm add corsair-dev/bubble安装后即可在应用代码中导入插件工厂函数bubble()并将其注册到 Corsair 中。该插件实现位于 packages/bubble/index.ts整体采用插件工厂 端点树 Schema 错误处理器的结构组织与仓库中其他插件如packages/bigml、packages/slack保持一致的架构风格。端点全景10 个操作与权限分级Bubble 插件的端点树定义在 packages/bubble/index.ts 的bubbleEndpointsNested中按thingsData API 数据记录、workflowsWorkflow API 工作流、meta元数据三个命名空间组织。下表完整列出插件暴露的操作、操作 ID、风险等级与说明操作操作 ID风险等级说明meta.getSwaggerbubble.api.meta.getSwaggerread获取已启用 Bubble API 的自动生成 Swagger 2.0 JSONthings.bulkCreatebubble.api.things.bulkCreatewrite一次请求创建最多 1,000 条记录逐条返回结果things.createbubble.api.things.createwrite使用给定字段值创建单条记录things.deletebubble.api.things.deletedestructive按唯一 ID 永久删除记录things.getbubble.api.things.getread按唯一 ID 获取单条记录things.listbubble.api.things.listread搜索并分页获取某数据类型的记录支持约束条件与排序things.replacebubble.api.things.replacewrite覆盖既有记录的全部可编辑字段省略的字段重置为默认值things.updatebubble.api.things.updatewrite修改既有记录的部分字段workflows.runbubble.api.workflows.runwrite使用请求体参数运行 API 工作流Workflow API POSTworkflows.runGetbubble.api.workflows.runGetwrite使用查询字符串参数运行 API 工作流Workflow API GET风险等级riskLevel直接服务于 Corsair 的权限系统read端点things.get、things.list、meta.getSwagger默认权限为openwrite端点为allowthings.delete被标记为destructive需要更高等级的授权。这一点在 packages/bubble/index.ts 的bubbleEndpointMeta与BubblePluginOptions.permissions注释中有明确说明。认证与连接配置API Key 认证插件使用 API Key 认证首次使用时 Corsair 会提示租户提供凭据。认证配置在 packages/bubble/index.ts 的bubbleAuthConfig中定义const defaultAuthType api_key as const satisfies AuthTypes; export const bubbleAuthConfig { api_key: { account: [appName] as const, }, } as const satisfies PluginAuthConfig;api_key持有的是 Bubble 管理员级 API Token即编辑器 Settings → API → Private key 中生成的私钥每次请求都以Authorization: Bearer token形式发送。appName是账号级account-level字段用于解析应用的 API 基础 URL。密钥的获取逻辑位于 packages/bubble/index.ts 的keyBuilder中如果插件选项显式传入了key优先使用否则调用ctx.keys.get_api_key()从账号密钥管理器中读取存储的密钥读取不到则抛出AuthMissingError(bubble, api_key)。值得注意的是packages/bubble/client.ts 中的tryGetStoredKey对账号没有 DEK数据加密密钥这一合法状态做了特殊处理——get_api_key()在这种情况下会抛异常而非返回 null插件会将其解析为未存储密钥而非中断请求只有解密失败、数据库错误等真实运维问题才会继续抛出。appName 与 baseUrl解析 API 基础地址Bubble 的 Data API 与 Workflow API 都挂在应用自己的子域名上/api/1.1前缀下。插件通过apiBase函数见 packages/bubble/client.ts解析请求的最终来源默认情况使用https://{appName}.bubbleapps.io。appName的解析优先级是插件选项options.appName优先否则回退到账号级存储的appName字段见 packages/bubble/endpoints/shared.ts 的resolveAppName自定义域名部署通过baseUrl完全覆盖基础 URL例如https://app.bubbleapps.io/version-test指向开发分支安全约束baseUrl必须以https://开头否则抛出 400 错误Bubble base URL must use HTTPS so the API token is never sent in plaintextappName必须是单个 DNS label字母、数字、连字符正则APP_NAME_PATTERN /^a-zA-Z0-9?$/在构造任何来源 URL 之前强制执行防止恶意构造的appName如xevil.example#把携带 Bearer Token 的请求重定向到其他主机SSRF 防护。插件选项bubble()工厂函数接受BubblePluginOptions完整字段如下类型定义见 packages/bubble/index.ts选项类型说明authTypeapi_key认证方式目前仅支持api_key默认即为此值keystringBubble 管理员 API Token编辑器 Settings → API → Private key以Authorization: Bearer token发送appNamestringBubble 应用名解析为https://{appName}.bubbleapps.io也可作为连接上的账号级字段存储baseUrlstring完全覆盖基础 URL用于自定义域名或开发分支如https://app.bubbleapps.io/version-testhooks生命周期钩子可选端点生命周期钩子errorHandlersCorsairErrorHandler可选自定义错误处理器与默认处理器合并permissionsPluginPermissionsConfig权限配置读端点默认open写端点allowthings.delete为destructive初始化示例import { bubble } from corsair-dev/bubble; const bubblePlugin bubble({ authType: api_key, appName: rentalunits, // 或依赖账号级字段请求时自动解析 // key 也可不传首次使用时 Corsair 会提示租户提供凭据 });Data APIThings 端点深度解析Data API 路径位于https://{appName}.bubbleapps.io/api/1.1/obj/...实现集中在 packages/bubble/endpoints/things.ts输入输出 Schema 定义在 packages/bubble/endpoints/types.ts。things.get按 ID 读取单条记录输入为typeName数据类型名与thingId记录唯一 ID请求GET /obj/{typename}/{uid}。返回的记录使用BubbleThingEntitySchema 校验见 packages/bubble/schema/database.ts核心字段包括_id记录唯一 ID读取与列表结果中始终存在Created By记录创建者官方示例为邮箱字符串可选Created DateISO-8601 创建时间戳API 1.1 下如2016-11-11T19:14:46.517Z可选Modified DateISO-8601 修改时间戳不可写Bubble 自动更新可选。Schema 使用.loose()允许自定义字段透传——Bubble 数据类型的自定义字段名可以包含空格如 Unit name这些字段不会因校验被丢弃。读取成功后插件还会把完整记录缓存到ctx.db.things见 packages/bubble/endpoints/persist.ts并通过logEventFromContext记录审计事件bubble.things.get。things.list搜索、约束与分页列表端点把 Bubble 的 Do a search for 步骤参数原样暴露为输入请求GET /obj/{typename}。输入字段Schema 见 packages/bubble/endpoints/types.ts字段类型说明typeNamestring数据类型名cursornumber≥0 整数首条记录的排位Bubble 的 cursor用于分页limitnumber1–50,000每页条数Data API GET 上限 50,000 条Enterprise 版 10,000,000 条constraintsBubbleConstraintSchema[]搜索约束数组序列化为 JSON 放入constraints查询参数sortFieldstring排序字段默认按创建日期descendingboolean降序排序Bubble 对文本字段排序通常要求设置此值excludeRemainingboolean跳过剩余记录计数大应用上节省容量additionalSortFields{ sortField, descending }[]附加排序字段同样 JSON 编码进查询串约束对象BubbleConstraintSchema与编辑器中的搜索条件一一对应key为字段名constraint_type取值如equals、greater than、text contains、is_empty等value为比较值is_empty/is_not_empty/empty/not empty时可省略geographic_search允许对象值。请求构造时constraints与additionalSortFields数组会被JSON.stringify编码进查询串undefined字段通过compact函数剔除见 packages/bubble/endpoints/shared.ts避免序列化出空查询键。响应使用BubbleListResponseSchemaresponse.cursor本页首条排位、response.count本页条数、response.remaining剩余条数exclude_remainingtrue时缺省、response.results记录数组。列表结果同样会批量写入ctx.db.things缓存。things.create 与 things.bulkCreate单条与批量创建things.createPOST /obj/{typename}请求体为fieldsJSON 对象。fields通过ThingFieldsSchema校验——必须是 JSON 对象且不允许undefined值undefined会被JSON.stringify丢弃导致字段缺失。响应为{status:success,id:...}.loose()允许额外字段。things.bulkCreatePOST /obj/{typename}/bulk一次创建最多 1,000 条Schema 强制min(1).max(1000)。Bubble 要求批量请求以text/plain发送、每行一个 JSON 对象因此插件将每条记录JSON.stringify后以换行符拼接见 packages/bubble/endpoints/things.ts。Bubble 可能部分成功部分失败响应按行解析为{status, id?, message?}数组逐条返回结果如{status:success,id:...}或{status:error,message:...}解析失败的行降级为{status:error, message:Could not parse response line}。最终输出{count, items}。批量创建允许更长的超时时间共享请求超时为 20 秒而BUBBLE_BULK_TIMEOUT_MS 260_000约 4.3 分钟——Bubble 官方允许批量创建运行长达 4 分钟插件据此放宽限制见 packages/bubble/client.ts。things.update、things.replace 与 things.deletethings.updatePATCH /obj/{typename}/{uid}仅修改传入的字段未涉及的字段保持原值。响应不含字段值因此插件会从缓存中驱逐该记录的旧快照evictEntity而不是信任部分重写后的脏数据。things.replacePUT /obj/{typename}/{uid}覆盖全部可编辑字段省略的字段会被重置为默认/空值——这是 PUT 的语义官方建议局部写入优先使用things.update。things.deleteDELETE /obj/{typename}/{uid}按 ID 永久删除风险等级为destructive同样会驱逐缓存快照并记录审计事件。things.update、things.replace、things.delete的输出类型均为void见 packages/bubble/endpoints/types.ts 的BubbleEndpointOutputs。记录镜像Schema 缓存插件声明了版本为1.0.0的数据库 Schema见 packages/bubble/schema/index.ts包含things实体。它是尽力而为best-effort的镜像只有经get/list取回的完整记录才会写入缓存create/bulkCreate只返回 ID不写缓存update/replace/delete会驱逐过期快照。这种只镜像已确认数据、不信任部分重写的策略保证了缓存数据不会失真。Workflow API运行 API 工作流Workflow API 路径位于https://{appName}.bubbleapps.io/api/1.1/wf/{workflowName}实现见 packages/bubble/endpoints/workflows.ts。workflows.runPOST /wf/{workflowName}参数以 JSON 放入请求体params为Recordstring, JSON 值可选。工作流名没有空格且同时就是 URL 端点因此会被encodeURIComponent编码后拼入路径。workflows.runGetGET /wf/{workflowName}参数放在查询字符串上仅支持 string/number/boolean 值GET 请求没有请求体。注意GET 工作流仍然是有副作用的不可当作幂等读操作重试。响应由工作流的 Return data from API 动作决定默认是{status:success}JSON 信封normalizeWorkflowResult会保证status字段存在缺省时补为success输出 Schema.loose()允许自定义返回数据透传。两个端点都会记录bubble.workflows.run/bubble.workflows.runGet审计事件。Meta 端点获取 Swagger 文档meta.getSwagger在编辑器 Settings → API 中启用 Swagger file 后可用返回自动生成的 Swagger 2.0 JSONGET /api/1.1/meta/之类路径输出类型为Recordstring, unknown。它属于read风险等级可用于运行时发现/校验 Bubble 数据类型的字段结构为 Agent 提供结构感知能力。错误处理与重试策略插件自带一套基于 HTTP 状态码分类的错误处理器见 packages/bubble/error-handlers.ts并与用户自定义处理器合并。底层网络错误统一包装为BubbleAPIError见 packages/bubble/client.ts它会从corsair/http的ApiError中复制 HTTP 状态、响应体与限流头retry-after等——Bubble 的 Data API 错误体形如{statusCode:..., body:{...}}Workflow API 形如{error_class:...}两者结构不同因此分类只依赖 HTTP 状态码body保持unknown。各错误类别的重试策略错误类别匹配条件重试策略RATE_LIMIT_ERROR429仅对幂等操作things.get/list/update/replace/delete、meta.getSwagger最多重试 5 次、指数退避创建类/工作流类绝不重放AUTH_ERROR401不重试PERMISSION_ERROR403不重试NOT_FOUND_ERROR404 或消息含 not found不重试SERVER_ERROR5xx仅对非不安全写操作最多重试 3 次、指数退避DEFAULT兜底不重试设计要点isIdempotent与isUnsafeWrite两个判定函数把可能已在服务端生效的写操作things.create、things.bulkCreate、workflows.run、workflows.runGet从所有重试路径中排除——5xx 时请求可能从未到达 Bubble也可能已被处理只是响应丢失重试第二种情况会重复执行业务。而传输层的BUBBLE_RATE_LIMIT_CONFIG将maxRetries设为 0429 的重试完全交给错误处理器决策从机制上保证 POST 创建与工作流永远不会被自动重放。Webhooks为什么不支持插件明确声明不支持 WebhooksREADME 中 No webhooks。原因在 packages/bubble/index.ts 的注释中讲得很清楚Bubble 的 Data API 与 Workflow API 是拉取式pull-based出站调用不存在可订阅的签名入站事件流因此bubbleWebhooksNested为空对象、pluginWebhookMatcher为undefined。如果需要监听 Bubble 数据变化应由应用侧通过定时轮询things.list或在工作流中主动推送来实现。测试与验证插件配套了完整的测试套件位于 packages/bubble包括client.test.ts客户端请求构造、appName 校验、baseUrl 强制 HTTPS 等逻辑的单元测试operations.test.ts各端点操作行为测试error-handlers.test.ts错误分类与重试策略测试验证 429/5xx 对幂等与非幂等操作的差异化处理integration.test.ts真实环境的集成测试通过pnpm test:live运行jest --testPathIgnorePatterns/node_modules/ --testPathPatternintegrationschema.test.tsSchema 校验测试。这些测试可直接运行pnpm test验证为哪些操作可安全重试、哪些绝不重放等关键行为提供了可执行依据。小结corsair-dev/bubble将 Bubble 的 Data API 与 Workflow API 收敛为一套类型安全、权限分级、重试策略完备的插件能力10 个端点覆盖记录级增删改查、1,000 条批量创建、约束搜索与 API 工作流触发API Key 认证配合appName/baseUrl双通道来源解析兼顾了标准子域名、自定义域名与开发分支三类部署形态在错误处理上通过幂等可重试、写操作不重放的严格边界规避了重复创建与重复执行工作流的风险。对希望为终端用户打通 Bubble 无代码应用数据的开发者而言这是接入 Corsair 生态最直接、最规范的方式。【免费下载链接】corsairConnect your users to their apps项目地址: https://gitcode.com/GitHub_Trending/corsa/corsair创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考