API 契约治理：用兼容性规则避免前后端互相等待

接口文档如果只在发布后生成，就无法阻止破坏性改动。契约治理的目标是把请求、响应、错误、权限和兼容策略放进版本库，在合并前就给出反馈。

契约包含什么

OpenAPI 描述路径、参数、状态码、分页、鉴权和字段约束；JSON Schema 约束嵌套对象、枚举和格式。错误响应也要有稳定 code、message 和 details，前端才能区分用户输入、权限和系统故障。

兼容性要自动检查

对已有客户端，新增可选字段通常兼容；删除字段、缩小枚举、改变类型和修改含义通常不兼容。CI 对比当前契约和上一个生产版本，命中破坏性规则就阻断，并要求变更说明和迁移计划。

契约测试覆盖真实边界

消费者提供关键请求和响应样例，提供方在 CI 验证状态码、字段类型、分页边界和错误语义。测试数据不包含生产隐私，失败信息指出具体路径。对异步事件也维护 schema registry 和兼容策略。

版本和下线

优先向后兼容，必要时使用 v2 或媒体类型版本。弃用要公布时间、替代字段和调用方清单，线上按 client_id 统计使用量；达到零调用后再删除，并保留回滚窗口。

契约治理最终减少的不是文档工作，而是联调等待、紧急回滚和“改一个字段牵连十个服务”的沟通成本。

参考资料：OpenAPI Specification。