API 契约 Breaking Changes：字段变化检查方法

一、问题概述：先声明比较的是响应契约

对响应对象而言，删除客户端已使用的字段、改变字段类型，以及把原来保证出现的字段改成可缺失，通常是兼容性风险。新增可选字段通常较安全，但向已有枚举增加服务端可能返回的新值，也可能让只处理旧集合的客户端失败。请求参数的方向不同，不能照搬本篇规则。

二、最小复现：一份样例的值变化不等于契约变化

下面 status 的具体值从 active 变为 paused 不是单纯的值 diff：若客户端只接受 active | disabled，新增的返回值需要被标记为潜在 breaking。相反，订单金额从 10 变为 12 只是同一 number 契约下的普通数据变化。

const before = { id: "string", status: ["active", "disabled"] };
const after = { id: "string", status: ["active", "disabled", "paused"] };

// Compare declared field constraints, not two live orders with different amounts.

三、根因：JSON Diff 不包含消费者的兼容性方向

结构化 JSON diff 可以指出新增、删除和替换，却不知道某字段是请求还是响应，也不知道客户端是否穷尽处理枚举。契约检查必须附加方向和规则。本文的规则将 required: true 理解为服务端保证返回该字段，将 enum 理解为服务端可能返回的字符串集合；其他协议可以选择不同策略，但必须写清楚。

四、推荐方案：用显式、可审阅的响应快照

将每个响应字段描述为 type、required 和可选 enum，用版本控制保存基线，再比较新快照。不要用未定义的 compareJsonSchemas 占位符冒充实现。复杂的 OpenAPI、oneOf、数值范围和嵌套对象应交给经过选型的 schema 工具；即使使用工具，也应保留当前服务的 breaking 规则。

五、完整代码：比较扁平响应对象的风险变化

以下 TypeScript 运行于浏览器或 Node.js，范围刻意限制为扁平响应字段。它报告删除、类型变化、required 保证减弱和新增可能返回的枚举值；不是完整 OpenAPI validator。

type ScalarType = "string" | "number" | "boolean" | "null";
type ResponseField = { type: ScalarType; required: boolean; enum?: readonly string[] };
type ResponseShape = Record<string, ResponseField>;
type Finding = { field: string; kind: "removed" | "type" | "required" | "enum"; message: string };

function findResponseBreakingChanges(before: ResponseShape, after: ResponseShape): Finding[] {
  const findings: Finding[] = [];
  for (const [name, oldField] of Object.entries(before)) {
    const newField = after[name];
    if (!newField) { findings.push({ field: name, kind: "removed", message: "field is no longer returned" }); continue; }
    if (oldField.type !== newField.type) findings.push({ field: name, kind: "type", message: oldField.type + " changed to " + newField.type });
    if (oldField.required && !newField.required) findings.push({ field: name, kind: "required", message: "field is no longer guaranteed" });
    if (oldField.enum && newField.enum) {
      for (const value of newField.enum) {
        if (!oldField.enum.includes(value)) findings.push({ field: name, kind: "enum", message: "new response enum value: " + value });
      }
    }
  }
  return findings;
}

console.log(findResponseBreakingChanges(
  { id: { type: "string", required: true }, status: { type: "string", required: true, enum: ["active", "disabled"] } },
  { id: { type: "string", required: true }, status: { type: "string", required: true, enum: ["active", "disabled", "paused"] } },
));

六、常见错误方案

把所有新增字段拦截会阻碍兼容扩展；对响应对象，新增可选字段通常不需要阻断。只比对样例值会把正常业务数据变化误报为 breaking。只看字段存在而不看类型、required 或枚举又会漏掉客户端反序列化和分支处理的风险。把请求和响应用同一方向规则判断尤其危险。

七、边界条件：嵌套、nullable 与版本策略

嵌套对象需要把路径展开或递归比较；数组还需定义元素契约。nullable、字段缺失和空字符串是不同状态，应在 shape 中分别表达。枚举值新增是否 breaking 也取决于客户端是否穷尽匹配；若客户端约定默认分支，可将该规则降为警告。版本号、废弃期和迁移窗口是发布策略，不会由 JSON diff 自动推导。

八、如何验证发布前检查

为删除字段、string→number、required→optional、新增可选字段、新增 response enum 值和普通数值变化各写一个快照测试。断言前四类按规则产生预期 finding，同时确认新增可选字段和普通数据变化不被同一规则误报。再把基线与候选快照保存到代码审查中，让接口所有者确认分类。

九、FAQ

问：响应新增字段一定安全吗？答：通常对宽容客户端较安全，但客户端若拒绝未知字段，仍需协调。

问：为什么枚举新增可能 breaking？答：客户端可能使用穷尽 switch 并把未知值视为错误。

问：这个函数能替代 OpenAPI 工具吗？答：不能；它演示可审阅的规则，复杂 schema 需要更完整的解析与验证。

十、总结

Breaking change 检查的核心不是把所有 JSON 差异标红，而是明确消费者方向。对响应对象，应重点检查字段删除、类型变化、返回保证减弱和新的枚举输出。使用可审阅快照与针对性测试，并把复杂 schema 交给合适的工具。