契约先行在做什么
契约先行（API First）要求先写接口契约（OpenAPI、Protobuf、AsyncAPI 等），再由前后端与上下游按契约并行开发。契约在这里是一份可执行的规范：它能生成文档、服务端桩代码、客户端 SDK 与 mock，也能进入流水线做兼容性检查。它的收益不只是“少联调”，更在于把接口变更变成可评审、可分析的工程事件。
基本信息
| 顺序 | 需求 → 契约评审 → 并行实现 → 契约测试回归 |
|---|---|
| 价值 | 减少联调返工，变更影响可分析 |
| 工具 | 规范仓库、评审、mock 服务、契约测试 |
| 落地要求 | 契约文件与代码同仓评审，纳入版本管理与变更审查 |
典型使用场景
- 前后端并行开发：前端基于 mock 与生成的 SDK 先行开发
- 多端接入：Web、移动端与第三方共用同一份规范
- 内部服务协作：上下游按契约约定错误码与分页语义
- 对外开放平台：规范即文档，配合 SDK 生成降低接入成本
- 变更管理：破坏性变更通过契约对比自动识别并阻断
实施步骤
- 契约入版本库：OpenAPI/Proto 文件与代码同仓评审
- 评审要点：资源命名、分页、错误结构、幂等与并发控制
- mock 先行：前端与调用方基于契约 mock 并行开发
- 契约测试：提供方流水线执行消费方契约，阻断不兼容变更
- 变更记录：破坏性变更同步升级指引与迁移窗口
契约片段（OpenAPI 风格）
契约片段（OpenAPI 风格）
paths:
/v1/orders/{id}:
get:
parameters:
- name: id
in: path
required: true
schema: { type: string }
responses:
'200': { description: 订单详情 }
'404': { description: 订单不存在 }
# 错误结构、分页参数与幂等头在规范里统一定义一次，各接口复用契约评审要点
| 方面 | 要确认什么 |
|---|---|
| 资源与命名 | 路径与字段命名一致，复数与层级风格统一 |
| 分页与过滤 | 分页方式、默认与上限、排序与过滤的白名单范围 |
| 错误结构 | 错误码、错误体字段与语义在各接口间保持一致 |
| 幂等与并发 | 哪些接口需要幂等键，冲突时返回什么状态码 |
| 兼容性 | 本次变更属于兼容还是破坏性，迁移窗口如何安排 |
契约先行不等于设计完成才开工：小步提交规范文件，允许实现早期反馈修正。把契约评审变成阻塞式关口反而会拖慢交付。
契约与实现分离后容易漂移：必须有契约测试在流水线里校验实现与规范一致，否则文档会逐渐变成“理想状态说明”。