← 中文资源

简体中文版本

合并前评审 API 契约变更

对比 OpenAPI 文档,把变更分类为破坏性或兼容,收集消费者影响,并要求破坏性变更提供迁移计划。

阅读英文原文

让差异成为评审产物

API 变更应在合并前可见。生成提议契约与基线分支的差异,并附到拉取请求。评审者能看到被删除的字段或新增的必填参数,而不是在客户端事故中发现。

oasdiff breaking base.yaml head.yaml

命令只是示例;任何能分类破坏性变更的差异工具都行。关键是分类显式且可执行。

站在消费者角度分类

新增可选字段通常兼容,但拒绝未知字段的严格客户端仍可能坏掉。删除字段、新增必填字段、改变类型或改变错误行为都是破坏性的。要检查策略和已知消费者,而不是只依赖 schema。

门禁破坏性变更

破坏性变更缺少批准和迁移计划时让 CI 失败。要求每个受影响消费者的负责人确认。公布弃用日期和替代方案。日落之后移除旧行为并更新契约。

验证契约

预期结果:破坏性变更被门禁阻止,除非附带批准的迁移计划;兼容变更通过并更新文档。用故意删除字段的测试拉取请求确认 CI 失败。