SuperAPI AI 工具集

trpc-compat

编程与开发

查看项目

更新于 10-20 01:49

技能介绍

用途

trpc-compat 用于确认某次 tRPC 变更对已发布的桌面端、移动端、CLI 与 SDK 构建是否安全,并在需要变更契约时选择兼容模式,判断何时可以移除已废弃的 procedure 或字段。它强调 CI 只能看到 main 分支,而发布构建仍在被使用,因此需要额外检查 CI 看不见的调用方。

主要能力

  1. 查找发布版调用方:在发布标签(而非 main)上搜索 procedure 路径。示例中先 git fetch --tags,再遍历 ≥ MINIMUM_DESKTOP_VERSION 的 desktop-v* 标签,用 git grep -q -P 检查 apps/desktop 是否调用。CLI 用 cli-v* 标签检查 packages/cli,且 CLI 无最低版本限制,应检查所有标签。移动端无标签且最低版本为 1.0.0,若 main 上 apps/mobile 调用或 git log -S 曾出现,视为活跃构建在调用。SDK 通过字符串 /api/trpc/<procedure> 调用,同样在 main 与 git log -S 中搜索。host-service procedure 的调用方为桌面端、CLI 和移动端,host 可能比客户端旧或新。任何命中都说明该 procedure 仍在用,其输入输出已冻结。

  2. 检查用量数据:API 将 1% 的调用采样到 PostHog 事件 api_procedure_called。提供 SQL 按 product 与 version 统计近 30 天估算调用次数与最后出现时间。零行对低频 procedure 是弱证据:小量样本的 1% 可能四舍五入为零;web 及早于 x-superset-client 头的构建不会被记录。

  3. 选择兼容模式:以表格给出场景与做法,例如改变输出形状用新 procedure、旧 procedure 保持形状(page.list + page.listPaginated);新增输入用可选字段并在 handler 中给默认值;接受新输入形状则两种都接受并在服务端转换;重命名 procedure 则新名保留,旧名作为 @deprecated 别名;删除输入则继续接受并忽略;删除输出字段则保留发送直到允许移除;删除或重命名 DB 列先固定 procedure 输出列并保留旧字段;收紧输入只用于新输入或新 procedure;改变错误码、默认值或排序顺序用新 procedure 或可选输入选择加入;客户端调用新 procedure 先合并 API 再在 API 上线后合并客户端。检查 API 是否上线需最近一次 Deploy Production 运行通过(gh run list --workflow deploy-production.yml --branch main --limit 5)。客户端代码应防御未知情况:保护新可选字段、处理未见过的枚举值、避免单个组件失败拖垮父视图。schema 迁移单独放在一个 PR。

  4. 移除废弃 procedure 或字段:仅当步骤 1 在活跃桌面标签及移动端、CLI、SDK 中均无调用,且步骤 2 显示近 30 天无活跃版本调用时才可移除。若仍有活跃桌面构建调用,唯一路径是提高 MINIMUM_DESKTOP_VERSION,这属于产品决策,应询问而非在清理 PR 中执行,并把证据写进 PR 描述。

  5. 已发布客户端已崩溃时:用 Sentry 确认新桌面问题起始于 API 部署时间。若破坏性 PR 含已应用于生产的迁移,则不回滚迁移,而是写前向修复恢复旧契约并将新形状移到新 procedure;若无迁移则回滚 PR。告知受影响用户重新加载(Cmd+R),部分需重启应用或终端守护进程。

检查清单

对每个输入或输出变更的 procedure 执行步骤 1 并将结果放入 PR;无现有输入字段变为必填、重命名、改类型或更严格校验;无现有输出字段被移除、重命名、改类型、包装或新变为可空(包括通过无列名 find* 的 DB 列变更);不改变现有错误码、默认限制、排序顺序或 null 含义;不改变 procedure 类型(query、mutation、subscription)、link 或 transformer;不在现有 procedure 上新增必填头或更严格鉴权;需要新 procedure 的客户端代码在 API 生产上线后合并;每个新输入字段可选并有服务端默认值;被替换的 procedure 保留为 @deprecated 别名;契约变更 PR 中不含 schema 迁移;移除操作需在 PR 中提供步骤 1 与步骤 2 的证据。

适用场景与限制

适用于维护多客户端(桌面、移动、CLI、SDK、host-service)共享同一 tRPC API 的项目,在修改 procedure 契约、重命名或删除 procedure、调整错误码/默认值/排序、进行数据库列变更时使用。限制:用量数据仅覆盖 1% 采样且不记录 web 与旧构建;移动端无发布标签;步骤 1 的标签命名与最低版本常量来自示例仓库,需按实际项目调整;提高最低版本属于产品决策,不应在清理 PR 中自行执行。