上线前的 API 契约检查清单

快速结论

检查字段语义、错误码、兼容窗口、重试行为、幂等键、监控字段和弃用说明。缺其中任意一项，都可能在联调阶段变成反复返工。

你应该先看什么

• 字段语义是否稳定且有默认行为说明。
• 错误码是否可分类、可监控、可重试。
• 兼容窗口、版本策略和弃用计划是否提前声明。

可直接复用的示例

发布前检查
- 新字段是否可选
- 删除字段是否有弃用窗口
- 429/5xx 是否提供重试指引
- 幂等写接口是否声明 idempotency key

破坏性变更分类

并非所有契约变更都同等危险。有些可以安全发布而无需版本边界；有些会立即破坏消费者。区分这两者对发布计划、消费者通知和回滚策略至关重要。

• 安全（累加型）：新增可选响应字段、新增可选请求参数、新增消费者可忽略的枚举值、新增端点。
• 需要版本边界：重命名已有字段、将可选字段改为必填、删除已返回字段、在不重命名的情况下更改已有字段的语义含义。
• 立即破坏：删除已有端点、更改必填字段类型、更改认证方案、修改错误信封结构。
• 静默破坏：更改默认排序顺序、更改分页游标格式、更改金额字段的数值精度、更改日期时间字段的时区假设。

"静默破坏"类最危险，因为它通过了所有现有测试。将日期时间字段从 UTC 改为本地时区在内部看似微小，却会破坏所有存储或展示该值的消费者。此类变更需要协调发布并通知消费者，而不仅仅是版本号升级。

消费者驱动的契约测试

生产者侧的契约测试验证你的 API 是否符合自己的 OpenAPI 规格——这是必要条件，但不充分。消费者驱动的契约测试更进一步：每个消费者发布它实际使用的 API 内容——读取的字段、处理的状态码、解析的错误结构——生产者在每次构建中运行该消费者的期望集。

• Pact 等工具允许消费者将期望定义为契约文件，由生产者在 CI 中验证。
• 消费者契约能捕获真正的破坏性变更——那些不出现在规格中的变更，因为消费者行为从未被文档化。
• 新消费者接入时，应在生产者构建功能之前发布契约，而非之后。
• 消费者契约测试失败应阻止生产者发布，而非仅产生警告。

消费者驱动测试对内部微服务 API 尤为重要——"所有消费者都是我们团队的人"这一理由常被用来跳过契约形式化。内部团队变动快，以对其他团队不可见的方式改变行为，直到在测试环境或生产中出现故障。

版本化决策清单

版本化 API 端点的决定通常是被动的——在破坏性变更已经发布之后才作出。这份清单让版本化决策在变更编写前明确，而非在消费者事故发生后。

# 版本化决策门控

变更是否仅为累加型？
  是 → 无需版本号变更；在变更日志中记录新字段

变更是否修改了已有字段行为？
  是 → 需要版本边界；弃用旧行为并附迁移时间表

所有消费者是否需要同时迁移？
  是 → 协调发布并提供迁移指南；不立即移除旧行为
  否 → 在迁移窗口期并行支持新旧行为

旧行为是否会被移除？
  是 → 设置移除日期；通知消费者；向旧端点添加弃用响应头
  否 → 无限期维护；文档化支持承诺

新版本发布后是否可回滚？
  是 → 记录回滚流程和数据兼容性影响
  否 → 视为不可逆迁移；发布前需明确审批

上线后如何确认契约没有漂移

API 契约不是发布前签一次字就结束。上线后至少要观察一个真实流量窗口，确认响应字段、错误码、延迟、重试行为和消费者日志都与规格一致。尤其是新增字段、枚举值和分页行为，最容易在生产数据出现后暴露未写清的语义。

• 用监控按端点和错误码查看异常，而不是只看总体 5xx。
• 抽样检查真实响应是否仍符合 OpenAPI 或 Markdown 规格里的示例。
• 如果消费者需要临时适配，先更新契约，再记录后续迁移计划。

如果上线后发现契约和实际行为不同，不要只修代码或只修文档。应先判断哪一方是团队认可的目标行为，再同步更新测试、示例和发布说明。

对于跨团队接口，最好把这个复查安排在发布后一个固定窗口内完成，例如 24 小时或一个完整业务日，而不是等消费者主动报错。

复查结果应作为下一次契约评审的输入。

落地建议

在下一次 API 发布前，把这份清单过一遍。重点关注"删字段有没有弃用窗口"和"幂等接口有没有声明 key"——这两项是最常在联调时才被发现的缺口。