接口合同与 SDK 维护

约 1138 字大约 4 分钟

2026-10-16

平台维护者负责合同的产生与发布，独立应用按固定版本消费。修改平台 .api/.proto 与在应用中调用 SDK 是两种不同工作。

合同来源与生成链

服务 .api / .proto
    → 对应服务 build.sh
    → Go 接口 / pb / Swagger
    → 平台前端生成客户端
    → 固定 SaaS 提交导出 ur-kit
    → SDK 标签与应用版本更新

生成工具版本以仓库脚本为准，平台使用联犀定制 goctl；不要把应用新建 RPC 的官方 goctl 安装命令用于平台代码生成。

# 从平台主仓根目录运行，仅选择本次修改的服务。
bash backend/core/service/apisvr/build.sh
cd apps/web
pnpm --filter @vben/api codegen --model core-api

--model 使用 backend/.swagger/ 中实际文件名去掉 .json 的部分。未改变对应合同不要重生成其他模块。需要 OpenAPI 生成工具的 Java 运行时先在开发机准备。

主仓 open-api/sync.sh 另包含 Apifox 同步与自动提交能力。需要使用该流程时先看参数和授权，不能把带发布副作用的同步命令当作普通本地生成命令运行。

Swagger 是服务合同生成物，用于接口查看、前端客户端和公开 HTTP SDK 生成。权威输入仍是所属服务 .api，不能直接改 Swagger 来修接口，也不能手工改生成的 TypeScript 模型来掩盖类型错误。

服务 build.sh 不一定负责所有聚合/发布步骤。先读所属脚本输出及主仓同步流程，确认本次修改真正进入客户端生成使用的文件；不要对着旧聚合 JSON 生成后宣称已更新。

接口查看可用本地生成文件导入 API 工具，或从顶部“接口文档”进入已发布接口。线上工具内容可能滞后于本地分支，调试当前变更时以本次提交生成结果为准。

核对两个请求样例：一个正常业务请求、一个认证/权限/参数错误。尤其检查长整数 JSON、空数组/空对象、时间单位、上传 multipart、回调和 WebSocket，不以 Swagger 能打开替代合同验证。

先提交并固定平台合同来源，再在平台主仓根目录执行：

saas_sha="$(git rev-parse HEAD)"
bash shell/sync-ur-kit-contracts.sh --kit '<ur-kit-checkout>' --sha "$saas_sha"

同步入口导出合同、Go pb 与相关快照，保护已有未提交修改。重复同步确认无漂移；Java、Node、Go 按本次改动验证实际编译、认证和请求结果。公共 Go SDK 不得依赖私有平台服务端包。

合同、生成客户端、共享 Web 快照变化时审核消费者版本锁，不能只改标签文本。SDK 与共享包完成验证后再发布版本，独立应用自行明确升级的版本和镜像。

apilegacy 兼容网关仍需保留。特别核对数字/字符串 ID、嵌套大整数、空值、错误码、时间单位、认证头、上传回调和 WebSocket；AllInOne 编译通过不能代替旧端验证。

通常先提供兼容的平台能力，再发布 SDK/共享包，之后升级应用与镜像，最后切换入口。删除或改变合同语义前，完成相应适配和回滚验证。涉及数据变化通过代码内幂等迁移处理，不能仅附一份手工 SQL。

2026/10/16 19:46

查看所有更新日志