用AI检查API兼容性，不能只比较两份字段名称。先确定需要继续工作的旧调用方，再对照请求约定、响应结构和默认行为，把每项变化对应到具体消费者与回归样例。删除字段、改变类型很明显；字段仍在但含义变了，同样可能让旧界面出错。
把旧契约、新契约和一份实际调用代码放在同一个项目目录，可以用墨刀AI客户端结合本地文件整理接口变更。先要求列出差异及来源位置，再让它解释影响，避免只有一段“建议保持兼容”的空泛结论。
先说明要兼容谁，再比较字段
同一个团队同时发布前后端，与对外提供接口、无法控制调用方升级时间，兼容要求不同。先登记消费端、当前版本、使用的接口与字段，以及能否同步升级。不能只因为开发环境里最新前端能工作，就认定所有使用者都已兼容。
Google AIP-180区分源码、传输和语义层面的兼容，并提醒新增字段也可能受旧行为约束。本文重点检查JSON响应和消费者行为；具体结论仍须落到本项目的调用方式，不能把一份指南当成所有接口的自动裁决器。
准备材料时保留两版接口定义、服务端相关改动、典型请求响应和调用方代码。契约与实现冲突时，不要让AI任选一份作为真相；把冲突记录为需要确认的项目，并注明哪个消费者会受到影响。
用一个工单接口看清重命名的后果
假设工单详情原来返回id、status和字符串priority。新版本想把状态改名为state，并把优先级改为数字。新响应本身可以是有效JSON，但旧客户端还在读取status并处理字符串，就会失败。
下面的Python小例模拟一个旧消费者。保存为api-compatibility.py，运行python api-compatibility.py。它只演示三份响应如何影响同一个消费者，没有启动或调用真实业务服务。
import json
old = {"id": "T-1", "status": "open", "priority": "normal"}
breaking = {"id": "T-1", "state": "open", "priority": 2}
compatible = {
"id": "T-1", "status": "open", "state": "open",
"priority": "normal", "priorityLevel": 2
}
def old_client(item):
label = {"open": "待处理", "closed": "已关闭"}[item["status"]]
return item["id"], label, item["priority"].upper()
print("old:", old_client(old))
try:
old_client(breaking)
except (KeyError, AttributeError) as error:
print("breaking:", type(error).__name__, str(error))
else:
raise AssertionError("本例预期旧调用方无法使用破坏性响应")
assert old_client(compatible) == old_client(old)
print("compatible:", old_client(compatible))
# 保留status却改了priority的类型，也不能通过。
wrong_type = dict(old, priority=2)
try:
old_client(wrong_type)
except AttributeError:
print("wrong_type: AttributeError")
else:
raise AssertionError("本例应识别消费者依赖的字符串类型")
本例在Python 3.12.14运行：旧响应与兼容响应均得到同一个工单展示结果；重命名后的响应触发KeyError；只改优先级类型也触发AttributeError。这证明两个具体依赖受到影响，不代表其余消费者都已经验证。
兼容响应保留旧字段，并增加新的名称和数字值，是一种过渡方案。但别名必须来自同一份业务值，否则status与state可能相互矛盾。何时移除旧字段，需要结合接口版本、调用方迁移与明确的停止支持安排决定。
把结构变化和行为变化分两轮检查
| 变化 | 为什么需要检查 | 应查看的证据 |
|---|---|---|
| 删除或重命名响应字段 | 旧代码按原名称读取 | 访问该字段的组件、SDK和测试 |
| 字符串改数字、允许空值 | 格式化与分支判断可能失效 | 类型声明、反序列化和显示逻辑 |
| 请求新增必填项 | 旧客户端不会发送新参数 | 历史请求与校验规则 |
| 新增响应枚举值 | 旧客户端可能只处理已知选项 | 分支兜底、映射表与错误处理 |
| 默认排序或分页范围变化 | 字段没变，结果含义却变了 | 未传参数的请求及消费方式 |
不要把“新增”一律判成安全。有些客户端严格拒绝额外字段，有些代码把未知状态当成异常；相反，对未知字段宽容的客户端可能无需修改。判断应写成“对哪个消费者、在什么条件下有风险”，而不是脱离上下文的红绿灯。
行为检查还要看单位、时区、空值含义与默认范围。金额从元改为分但字段仍叫amount，类型检查可能全部通过，业务却会错。能解析，不等于仍在表达同一件事。
给AI一份明确的审查任务
比较contracts/old与contracts/new，并读取clients目录里实际调用这组接口的代码。逐项输出：变化、文件与字段位置、依赖它的消费者、风险触发条件、建议验证样例。把结构差异和行为差异分开。找不到调用依据的事项列为待确认，不把推测写成已发生故障。先生成审查报告，不改接口实现。
一个可用结果可以是：status→state影响工单状态标签，旧消费者读取item["status"]；需要验证旧响应、新响应和同时保留两个字段的过渡响应。报告里若只有“重命名可能有风险”，还没有完成从差异到具体影响的连接。
如果接口文档本身还没与源码对齐，应先完成从代码整理可联调的API文档。用两份不准确的契约做精细比较，只会把原有错误排得更整齐。
发布前保留一组旧消费者回归样例
选取仍受支持的旧请求与响应读取方式，覆盖正常、空数据、错误、未知枚举和默认参数。对本例至少保留状态读取、优先级格式化和新增状态的兜底路径；接口涉及分页时，还应核对旧调用方是否能得到原来期望的完整结果。
最终交付不只有一张风险表，还应有已验证样例、剩余消费者名单和迁移安排。接口兼容性是双方行为的约定；AI适合帮助找线索、整理差异和补充验证，但不能凭一个“兼容”标签替代实际调用关系。
