---
name: api-compatibility-review
description: 对两版接口合同、DTO 或接口变更进行有方向的兼容性审查，输出受影响消费者、破坏条件、证据与迁移方案；适用于上线前评审，不是两份 JSON 示例的简单 Diff。
---

# 接口兼容性审查

以“旧客户端继续请求新服务端”为默认方向。用户要求其他升级方向时按其要求分析，并在报告开头写清。没有客户端或调用证据时可以判断合同风险，但不要声称已确认某客户端故障。

## 确定比较范围

记录旧/新合同版本、方法与路径、请求与响应媒体类型、鉴权、状态码及已知消费者。定位 OpenAPI `$ref`、DTO 和序列化配置的实际定义；引用到的公共 schema 需追到它使用的每个请求和响应位置。

只给两份响应样例时，报告“观测变化”，不能把出现过当必填，把没出现当删除，也不能从一次返回推断枚举全集。请求与响应的同名字段分开审查。OpenAPI 3.0 / 3.1 的 null 表达需按版本解释。

## 判定

阅读 [references/compatibility-rules.md](references/compatibility-rules.md)。先区分合同可确定的变化与依赖消费者的风险，再解释触发条件：哪一种以前有效的请求不再可用，或旧客户端以前不必处理的返回现在可能出现。

对每个重要变化提供：
- 旧定义与新定义的文件位置或 schema 路径。
- 最小反例请求/响应，不用无关大对象掩盖差异。
- 受影响消费者与证据；未知时明确写未知。
- 迁移方式和回归用例。区分临时兼容与最终合同，不建议静默强转金额或长期双义字段。

用源码确认消费者时，追到解析、条件分支和实际使用点；生成类型、页面展示和服务端 DTO 不是同一层。不要仅凭同名字段就认定调用关系。

## 交付

输出 `compatibility-report.md` 和 `regression-cases.md`，默认目录 `artifacts/api-compatibility/`：

- 摘要：比较方向、材料覆盖、已确认的合同破坏、条件风险、观测差异、未知项分别计数；不提供无依据百分制评分。
- 变化表：证据位置、方向、旧/新约束、最小反例、影响条件、建议与验证状态。
- 发布建议：哪些消费者需同步迁移，哪些可保留旧字段或版本接口过渡；给出退出兼容层的可验证条件。
- 覆盖边界：未解析引用、没有比较的接口、未读取的消费者或运行配置。

没有阻断问题只能说“在已审范围内未发现”，不能替代上线验收。默认只审查、生成报告与用例，不自动发布、改库或修改调用方。

## 验收

每个“破坏”都有方向和反例；新增字段、枚举扩展等条件风险不能一概判安全或一概阻断。样例不能冒充合同，报告不能把本地静态分析写成线上验证。

演示见 [examples/input.md](examples/input.md)、[examples/result.md](examples/result.md) 和 [examples/regression-cases.md](examples/regression-cases.md)。