---
name: api-contract-review
description: API 契约审查（API contract OpenAPI compatibility idempotency）。检查接口是否能被真实调用、正确失败并兼容现有消费者。用于前后端要并行，先定接口。;API改版会不会破坏现有客户端？;接口重试和错误格式需要统一。
---

# API 契约审查

检查接口是否能被真实调用、正确失败并兼容现有消费者。

## 输入与开始方式

- `contract`：当前和候选OpenAPI/接口说明及版本。缺规范可从真实调用归纳草案。
- `consumers`：消费者、调用流程和兼容承诺。先识别已知消费者，未知项单列。
- `examples`：真实或合成请求响应、异常和权限场景。可先写可执行契约样例，标明合成。

缺少非关键资料时，先给明确假设下的草案或局部结果；资料补齐后只重验受影响部分。授权已覆盖的可逆工作继续，不重复确认。

## 执行

1. 读取当前接口和消费者，按用户动作定位实际调用链。
2. 校验字段、可空性、枚举、状态码、分页和安全方案，再检查语义缺口。
3. 比较旧新版本，标出请求新增必填、响应移除或权限语义变化。
4. 对幂等、未知结果和异步接口写具体请求响应序列。
5. 交修正清单与最小契约用例，独立消费者可据此并行。

按需要读 [专业方法](references/professional-method.md) 和 [完整案例](references/delivery-template.md)。

## 交付

- `interfaceMap`：接口与消费者映射。
- `compatibility`：兼容性变化。
- `behaviorCases`：行为案例。
- `recommendations`：最小修正建议。

## 检查结果

- 每关键动作有请求、响应、身份、错误和版本关系。
- 区分请求约束变严、响应字段变化和业务语义变化，给迁移窗口。
- 覆盖无权限、重复请求、分页边界、异步结果和错误恢复。
- 按真实消费者影响排序，先修阻断联调问题。

检查方法和证据要求在 [method.json](method.json)；参考 [作者正反例](evals/professional-cases.json) 识别实际错误。

## 需要额外处理的动作

线上写入和第三方调用按当前授权；契约分析、样例生成和本地测试继续。
