契约优先的 API 设计工作流

概述

实现先行会让接口形状在代码中沉淀，消费方只能事后适配并承担破坏性变更。契约优先把形状与行为的商定提前到编码之前，并让客户端、桩与文档都由契约生成，从而消除文档与实现漂移，再由 CI 拦截破坏性变更。

关键步骤

1. 编写含请求、响应、错误与示例的契约。
2. 与消费方评审并在实现前迭代。
3. 由契约生成桩、客户端与文档。
4. 在 CI 中对契约做破坏性变更检查。

验证

• 契约可无错通过校验。
• 生成的桩可编译。
• 文档与契约一致。
• 变更契约时破坏性检查运行。

决策点

对外集成多时宜契约优先，内部原型可代码优先再生成；破坏性检查应拦截删除与重编号，允许附加式变更。

适用范围

本条目围绕「契约优先的 API 设计工作流」给出可复制的步骤、验证方式与常见问题，适合需要按此流程落地的工程团队。执行时请结合自身上下文调整命令与阈值，并在变更前后留存证据，便于后续复核与回滚。

建议在正式环境落地前先在预发或隔离环境演练一遍，把关键观测指标与负责人一并记录，确保出现异常时能快速定位并恢复。

openapi: 3.1.0
info: { title: Orders API, version: 1.3.0 }
paths:
  /orders:
    post:
      responses:
        "201": { description: Created }
        "422": { description: Validation failed }