编程开发 编辑复核
API 契约设计与兼容性检查
从调用方、字段语义、错误处理和版本策略检查接口改动，减少前后端联调与发布回归。
PROMPT WORKBENCH
复制后替换变量
保留结构，先填真实信息，再把结果交给模型运行。
你是一名 API 设计评审工程师。请基于需求、现有接口和调用方，给出增量兼容的接口契约。
输出：资源和动作定义；请求字段表（类型、必填、默认值、校验、隐私级别）；响应字段表（语义、是否可空、兼容策略）；成功、客户端错误、权限、限流和服务端错误示例；幂等、分页、排序、缓存和版本策略；调用方清单、测试用例、灰度和回滚方案。
不要发明数据库字段或权限；没有提供的契约标记为待确认。已有字段默认不可删除或改变含义。
需求：{{requirement}}
现有接口：{{existing_api}}
调用方：{{consumers}}
非功能要求：{{non_functional}}HOW TO USE
使用说明
- 先从真实代码或 OpenAPI 文件读取旧契约，再让模型提出增量方案。
- 将示例 payload 复制到契约测试和客户端测试，避免文档与实现漂移。
WHEN IT FITS
适用判断
适合这些情况
- 接口已经在用，要改动时需要评估会不会破坏调用方。
- 你能提供当前的接口定义和调用方清单。
- 需要判断某个改动算不算破坏性变更。
换个做法更好
- 接口还在设计阶段：用《API 契约设计与边界》。
- 接口只有你一个调用方且完全可控：直接改，兼容性不是问题。
- 你拿不到调用方信息：兼容性判断需要知道谁在用什么字段。
FAILURE MODES
常见翻车与修正
- 把「新增可选字段」判定为破坏性变更。
判定标准需要明确。在输入里写清你的兼容性定义（比如是否允许新增字段、字段顺序是否敏感），让判定有依据。
- 只看字段结构，忽略了行为变化。
状态码含义、错误格式、默认值、排序规则的变化同样会破坏调用方。要求逐项检查这些非结构性契约。
- 给出的迁移方案要求所有调用方同时升级。
现实中做不到。要求给出可以并行运行新旧版本的过渡方案和下线时间线。
ACCEPTANCE
怎么判断输出合格
- 兼容性判定依据你给的标准，不是模型自己的假设。
- 检查覆盖了状态码、错误格式、默认值等行为契约。
- 迁移方案允许新旧并存，不要求同步升级。
- 每个破坏性变更都标了影响的调用方。
SAFETY BOUNDARY
使用边界
- 模型不知道你有哪些线上调用方，「不影响现有调用」的判断必须由你查实际调用日志确认。
- 内部接口定义和字段含义属于系统细节，对外分享前确认没有暴露业务逻辑和数据结构。