1. 什么是语义化 JSON 对比？
传统按行比对的文本工具（如 git diff）会将 JSON 视作纯字符串。然而，根据 RFC 8259 规范，JSON 对象本质上是无序的键值映射（例如 {"a":1,"b":2} 与 {"b":2,"a":1} 在业务逻辑上完全等价）。
在对比跨环境 API 响应报文（例如预发环境 vs 生产环境）时，传统文本对比工具往往因后端微服务序列化顺序不同，产生大量假阳性（False Positive）误报。
2. JSON 对比的核心痛点
- 键名乱序：后端框架升级（如 Jackson、Fastjson 或 Go struct 序列化）常导致键名顺序变动。
- 数组乱序：对于无序集合类型的数组（如用户权限列表），微服务返回的项顺序可能随机变化。
- 破坏性变更 (Breaking Changes)：接口升级中若意外删除了既有字段，或修改了数据类型（如 number 变 null），会导致前端崩溃。
3. 递归 Key 字母序排序算法
进行语义化对比前，需通过递归算法对双侧 JSON 对象的 Key 进行规范化排序：
ts
export function normalizeAndSortJsonKeys(val: any): any {
if (val === null || typeof val !== "object") {
return val;
}
if (Array.isArray(val)) {
return val.map(normalizeAndSortJsonKeys);
}
const sortedKeys = Object.keys(val).sort();
const result: Record<string, any> = {};
for (const key of sortedKeys) {
result[key] = normalizeAndSortJsonKeys(val[key]);
}
return result;
}4. 数组对比策略：按索引顺序 vs 无序集合模式
- 按索引顺序 (Ordered Index)：逐项对比位置
i的元素，适用于对顺序敏感的分页列表或元组。 - 无序集合模式 (Unordered Set)：对比前对数组内元素进行 Hash 杂凑或排序，适用于标签列表、权限集合等。
5. 常见问题解答 (FAQ)
Q1: API 接口对比中的“破坏性变更 (Breaking Change)”指什么？
指基准版本中存在的键名在目标版本中被误删除，或者字段的数据类型发生了非兼容变更（如从 number 变为 null 或 string），这会导致依赖该字段的前端代码抛出 NPE 崩溃。
Q2: 如何在对比时忽略时间戳或 Request ID 等动态变化字段？
您可以使用本站 语义化 JSON 差异对比器 的 路径过滤 (Path Filter) 功能，输入如 name, settings 或过滤掉匹配 timestamp|requestId 的节点。
Q3: 对比结果可以导出为 Markdown 格式粘贴到 GitHub PR 吗？
可以！本站工具会自动生成格式规范的 Markdown 变更报告，一键点击“下载 Markdown 报告”即可导出。