契约路径

API 契约主题 Hub

面向 API 契约写作的实用路径，覆盖兼容性、重试、错误码、版本、Webhook 行为和发布安全。

打开模板浏览资源

最近更新：2026-05-06

从这里开始

状态码、重试建议、幂等、字段语义和错误 payload 都应该在实现前写进契约。

每个变化都要分类为安全、风险或破坏性，并在发布前写明消费者动作。

用量查询、迁移窗口、Sunset header 和客户通知应该是契约的一部分。

# API 契约评审块

Endpoint：
- Method / path：
- 消费方：

兼容性评审：
- 增量变化：
- 风险变化：
- 破坏性变化：

运行时行为：
- 重试策略：
- 幂等 key：
- 错误分类：

发布门禁：
- 消费者测试：
- 迁移说明：
- 回滚方案：

只要 API 变化可能改变消费者假设，就应该使用这个 Hub。结构变化只是风险的一部分，消费者还会依赖时序、重试行为、枚举含义、分页顺序、错误码、认证规则和没有写在文档里的副作用。契约评审要在 schema 发布前把这些假设摊开。

从 diff 开始，但不要止步于 diff。每个字段、状态码、事件和重试规则都要分类为安全、风险或破坏性变化。然后写清消费者需要采取什么动作。如果动作是“无需处理”，就说明为什么旧客户端仍然正确。说不清楚，就还不能发布。

强的 API 规格会把发布说明和运行时监控接起来。废弃说明没有用量查询是不完整的；Webhook 变化没有重放和幂等测试是不完整的；版本策略没有迁移窗口也是不完整的。消费者路径和提供方路径一样清楚，契约才算完成。

交接产物应包含契约 diff、消费者列表、迁移说明、测试证据和回滚决策。它应该放在 API spec 附近，而不是只躺在发布工单里。

一个很小的枚举变化就足够测试契约评审质量。提供方可能认为新增 status=archived 是安全的，因为旧客户端可以忽略。但生成客户端、switch 语句、分析任务和 Webhook 消费者未必能忽略。规格要写明已知消费者、未知枚举值处理方式，以及旧 SDK 是否需要在放量前发补丁。

发布责任人要附上按客户端版本统计当前流量的查询、schema diff 和回滚选择。如果回滚意味着用 feature flag 隐藏新枚举，就写清楚。如果回滚意味着回退契约并重放事件，也要写清楚。关键是不能等消费者开始失败后再猜。

新增 enum 在 OpenAPI 里看起来很小，但生成客户端经常把 enum 当成封闭集合。它应该被当成调用方行为评审，而不只是 schema 编辑。

评审项	问题	证据
调用方清单	哪些客户端解析 refund_status？	Web、移动端、合作方 webhook、分析任务
生成客户端风险	是否有 SDK 把 enum 视为封闭？	用包含 pending_review 的 fixture 编译旧 SDK
fallback 行为	未知值应该展示什么？	未知状态映射到 review_required UI 状态
迁移说明	发布前谁必须行动？	移动端团队在公开放量前更新 switch