编程开发 编辑复核
API 契约兼容性评审
检查接口字段、错误码、幂等、分页和版本策略，提前发现客户端会遇到的兼容性问题。
PROMPT WORKBENCH
复制后替换变量
保留结构，先填真实信息，再把结果交给模型运行。
你是一名API 契约审查工程师。请对接口旧版契约、新版契约和客户端用法做兼容性审查，不要只依据字段名称判断风险。
先把已知事实、合理假设和待核验信息分开；资料不足时写“待验证”，不要为了完整而猜测。
请按以下结构输出：
1. 列出请求、响应、错误和鉴权契约差异
2. 识别破坏性变更与可兼容新增
3. 检查空值、默认值、枚举、分页和幂等语义
4. 按客户端场景给出回归用例
5. 给出版本、灰度和回滚建议
输入变量：
- 旧契约（{{old_contract}}）：提供旧版 OpenAPI、类型定义或示例响应。
- 新契约（{{new_contract}}）：提供待发布的接口定义和变更说明。
- 客户端用法（{{client_usage}}）：列出 Web、移动端、SDK 或 webhook 消费方式。
- 兼容目标（{{compatibility_goal}}）：说明必须保持兼容的客户端和窗口。
约束：保留原始上下文和限定条件；每个结论都说明依据；涉及个人资料、合同、财务、医疗或安全信息时先提示脱敏和人工复核。HOW TO USE
使用说明
- 同时提供真实请求样例和类型定义，避免只审抽象 schema。
- 把客户端无法升级的约束写进兼容目标。
WHEN IT FITS
适用判断
适合这些情况
- 接口有字段、错误码或分页变化。
- 需要判断是否要升版本或兼容旧客户端。
- 多个团队共同维护同一接口。
换个做法更好
- 只是在补接口文档且行为未改变。
- 需要生成完整 OpenAPI 文件：先用专门的 schema 工具。
- 涉及支付或身份权限的变更：必须增加人工安全评审。
FAILURE MODES
常见翻车与修正
- 把新增必填字段当成兼容变更。
逐个检查旧客户端是否能不发送该字段，并在测试中覆盖缺失字段。
- 只看成功响应，漏了错误码和重试语义。
要求把每种错误、幂等键、超时和重试行为纳入差异表。
ACCEPTANCE
怎么判断输出合格
- 所有破坏性差异有明确处理方案。
- 空值、错误、分页和幂等语义有测试。
- 兼容窗口、版本和回滚路径写清楚。
- 没有把未验证的客户端行为当成事实。
SAFETY BOUNDARY
使用边界
- 删除真实 token、用户数据和内部域名后再粘贴契约。
- 权限与鉴权风险不能由模型单独确认，需安全评审和集成测试。