| 顺序 | 需求 → 契约评审 → 并行实现 → 契约测试回归 |
|---|---|
| 价值 | 减少联调返工，变更影响可分析 |
| 工具 | 规范仓库、评审、mock 服务、契约测试 |
- 契约入版本库：OpenAPI/Proto 文件与代码同仓评审
- 评审要点：资源命名、分页、错误结构、幂等与并发控制
- mock 先行：前端与调用方基于契约 mock 并行开发
- 契约测试：提供方流水线执行消费方契约，阻断不兼容变更
- 变更记录：破坏性变更同步升级指引与迁移窗口
契约先行不等于设计完成才开工：小步提交规范文件，允许实现早期反馈修正。
契约先行（API First）
先定义接口契约（OpenAPI/Proto/AsyncAPI）再实现，前后端与上下游按契约并行开发；契约评审纳入变更流程，错误语义在契约阶段确定。
易错点
- 契约只在文档平台维护，代码偏离后无人发现
- 契约评审流于形式，边界与错误语义仍靠口头约定
数据来源与参考
- 《Designing Web APIs》（Jin & Sahni）
- Google API 设计指南