API 规格模板

模板使用路径

1. 在实现 endpoint 之前复制契约章节。
2. 补齐请求、响应、错误、兼容性、幂等性和发布检查。
3. 附上一条成功示例和至少两条非 happy path 示例。
4. 行为评审稳定后，再把 schema 部分同步到 OpenAPI。

可评审 API 规格长什么样

模板只有写入真实决策、责任人和证据后才有价值。上方空模板用于搭结构；进入实现前，建议至少写到下面这种具体程度。

Endpoint: POST /refunds
调用方：客服后台
兼容性：响应增加字段

评审证据：
- 旧客户端忽略 refund_status
- 重复 idempotency key 返回同一个 refund_id
- 契约测试覆盖 ORDER_NOT_REFUNDABLE

如果复制后的模板仍然缺责任人、证据或回滚字段，就先不要进入实现。

这个模板主要防什么问题

• 字段语义变化未通知，导致调用方线上报错。
• 错误响应结构不统一，排障效率低。
• 写接口缺少幂等约束，重试引发重复数据。
• 兼容策略不清晰，版本升级不可控。

关键章节填写建议

• Request：字段类型、必填、默认值、约束要完整。
• Response：成功和错误都要给 schema + example。
• Compatibility：明确哪些变更可原地发布，哪些必须升版本。
• Test Checklist：至少覆盖正常、校验、权限、超时重试。

把这些在开发前讲清楚，通常比事后修复兼容问题成本更低。

高频反模式

• 同版本直接改字段名或删除字段。
• 不同接口返回不同错误结构。
• 列表排序规则靠“默认行为”而非文档约定。
• 重试策略只写在代码里，不写在契约里。

发布前检查

• Contract tests 覆盖成功和失败路径。
• 破坏性变更已版本化并公告。
• 监控能发现响应码和字段异常。
• 回滚后可保持旧调用方可用。

配套阅读：API 契约清单、Given/When/Then 模板。

弱契约和强契约对比

弱契约

“POST /payments 创建支付，失败时返回错误。”这句话没有说明幂等键、重复请求、支付处理中状态、错误码稳定性，也没有告诉客户端应该如何重试。

强契约

“POST /payments 必须携带 Idempotency-Key。同一键 24 小时内重复请求返回原始结果。支付处理中返回 202 和 processing 状态；卡拒付返回稳定错误码 PAYMENT_DECLINED。”

强契约能让前端、后端、测试和客服对同一个失败场景形成一致预期。

如何接入 OpenAPI 和测试流程

• 先用 Markdown 讨论行为，避免过早陷入 schema 细节。
• 行为稳定后再同步到 OpenAPI，用于生成客户端、mock 服务和公开文档。
• 把成功响应、校验失败、权限失败、超时重试和幂等重复请求纳入 contract tests。
• 发布前检查监控是否能按端点、状态码和错误码定位问题。

评审切片示例：退款接口第一版

接口第一版不一定要覆盖所有产品想象。对退款接口来说，先写清最危险的契约，比一次支持所有退款类型更重要。

第一版范围：
- POST /refunds 只支持全额退款
- 必须携带 Idempotency-Key
- 重复请求返回同一个 refund_id
- 支付渠道 pending 时返回 202 和 processing 状态
- 客服查询接口可看到 pending_provider_confirmation

暂不做：
- 部分退款
- 批量退款
- 自动退款原因分类

这个切片能让客户端、后端、QA 和客服围绕同一个状态机评审，而不是各自猜测失败路径。

落地时不要漏的三件事

• 消费者：列出会调用这个接口的 Web、移动端、后台任务、合作方或 AI agent。
• 兼容性：明确新增字段、删除字段、枚举扩展和错误码变化分别如何发布。
• 观测：上线后至少能按端点、状态码、错误码和 traceId 查到异常。

API 规格不是只给后端看的文档，它是所有调用方共同遵守的行为契约。评审结束时，调用方应该知道如何重试、如何处理新增状态、如何识别可恢复错误，以及哪类变更需要提前通知。否则契约还没有达到可集成状态。

如果接口会被 AI agent、脚本任务或第三方集成调用，还要把速率限制、幂等窗口和错误恢复策略写进契约。机器调用方不会阅读 Slack 讨论，只会依赖稳定字段和可预测状态。

交给调用方前要附上什么

在调用方开始实现前，最好附上一组成功请求、一个校验失败、一个权限失败，以及一个重试或重复请求示例。示例应使用生产中预期的 Header、状态码和响应字段，而不是只写“返回错误”。如果接口面向合作伙伴，还要写清限流、版本废弃和升级通知方式。

当调用方可以不再追问字段是否稳定、哪些错误可恢复、重复请求是否安全，就说明这份 API Spec 已经接近可交付状态。

常见问题

每个接口都要写完整模板吗？

外部调用、跨团队调用、状态变更和支付/权限相关接口应完整填写。内部临时接口可以简化，但仍要保留请求、响应、错误和测试清单。

错误码应该写到什么程度？

至少写清客户端需要区分处理的错误。日志里的内部错误可以更细，但暴露给调用方的错误结构应稳定、可文档化、可测试。

什么时候需要重新评审契约？

当字段语义、错误码、分页规则、认证方式、幂等窗口或重试建议发生变化时，应重新评审契约。即使响应 schema 没变，调用方依赖的行为改变也可能造成破坏性影响。

契约评审的重点是调用方能否稳定集成，而不只是接口能否返回 200。

如果调用方需要根据状态码或错误码执行不同业务动作，这些分支必须写进规格和测试。

否则错误处理会漂移到各个调用方自己的实现里。

实现前的评审责任

开始开发前，建议指定一名契约负责人和至少一名调用方评审者。契约负责人检查命名、版本、兼容性和发布时间；调用方评审者检查示例是否足够写出客户端实现，而不是只能依赖私下说明。

如果接口会暴露给合作伙伴、脚本任务或 AI agent，还要记录限流策略、重试窗口、权限边界和支持升级路径。这些内容不一定都属于 OpenAPI schema，但它们决定集成失败时是否可恢复。