JSON Diff 完全指南：先格式化再对比，揪出真实字段差异
联调时「两边看起来差不多却对不上」、配置中心导出与本地文件「只有缩进不同」、或灰度环境响应多了一个嵌套字段时，靠肉眼扫 JSON 既慢又容易漏。本指南说明结构级 Diff 的用法、为何必须先格式化、常见误报与可操作步骤，直接对接 WebUtils JSON 比较器。
核心一句话
先变成合法且可读的 JSON，再比「路径上的值」；不要拿两行压缩文本当字符串硬比。
空白、键顺序、无意义转义会造成文本 diff 满屏噪音，却对程序语义为零。结构对比关注的是：某路径是新增、删除还是值变更。下面按「比什么 → 步骤 → 误报 → 场景 → 选型」展开。
1. 你到底在对比什么
JSON Diff 至少有两层含义，混用会浪费时间。
| 层级 | 比较对象 | 典型噪音 | 适合 |
|---|---|---|---|
| 文本 diff | 字符/行 | 缩进、换行、键序、空格 | 看格式化风格、提交里的纯文本 |
| 结构 diff | 解析后的树与路径 | 通常忽略纯空白 | 接口字段、配置项、业务语义 |
| 语义/规范化 diff | 排序键、规范数字等 | 依赖规则是否声明 | 契约测试、快照测试 |
WebUtils JSON 比较器 面向日常联调：左右各贴一份 JSON，解析后标出 added / removed / changed（页面用颜色区分新增、删除、变更）。它回答的是「数据哪里不同」，不是「谁的缩进更漂亮」。
和 Git diff 的关系： Git 对 JSON 文件默认是文本 diff。键被重排或全部重新格式化时，Git 会显示大片变动，而结构 Diff 可能只有一两个字段。审查配置或 API 样例时，先结构 Diff 再决定要不要纠缠空白。
2. 为何「先格式化再对比」
三件独立的事常常被揉在一次粘贴里：
- 合法性： 非法 JSON 无法进入可靠的结构比较。
- 可读性： 人要能点开路径看上下文。
- 可比性： 两边应先处于可解析状态；需要时再统一美化。
推荐流水线：
原始文本 → 格式化/校验 →（可选）键排序或规范化 → Diff → 解读路径
在比较器内提供 「格式化」 按钮时，可先点它再 「开始比较」；若某一侧语法错误，应先到 JSON 格式化 修到可 parse，再回到 Diff。对已经压缩成一行的响应，格式化尤其关键，否则你很难把「变更」对应到业务字段名。
压缩后再比？ 一般不需要。压缩改变的是空白，结构 Diff 本就不该依赖空白。JSON 压缩 用于传输体积，不是 Diff 的前置条件。只有在你怀疑「工具误把空白当内容」或要做纯文本级对比时，才考虑先统一 minify——那已是另一类问题。
3. 操作步骤（对着工具）
- 打开 JSON 比较器。
- 左侧粘贴「基准」或「旧版」（例如：上一环境响应、文档中的示例、合并前配置）。
- 右侧粘贴「候选」或「新版」（当前响应、本地改过的文件、合并后结果）。
- 两侧都来自压缩接口时，点击 「格式化」（
formatBoth），确认都能展开。 - 点击 「开始比较」。
- 在结果区按图例阅读：
- 新增（added）：右侧有、左侧无的路径
- 删除（removed）：左侧有、右侧无
- 变更（changed）：同路径两边值不同
- 需要交换基准时用 「交换位置」，避免重新粘贴。
- 可用 「加载示例」 熟悉颜色与路径展示；正式数据用 「清空」 防止串台。
读结果时的习惯
- 先看 数量：是 1 个字段变了，还是整棵树被换根。
- 再看 路径前缀：
data.user下大面积变更，往往是嵌套对象整体替换，而不是十个无关字段。 - 对数组：注意实现是「按索引比」还是「尽力匹配」；同级数组乱序会表现为大量变更——见下一节。
- 对类型变化：
null→0、1→"1"应视为变更，即使业务「看起来能用」。
失败时：若提示无法解析，把报错侧整段拷到格式化工具，修好非法逗号/引号后再比。不要在半份 JSON 上解读 Diff 结果。
4. 误报与漏报从哪来
| 现象 | 原因 | 处理 |
|---|---|---|
| 满屏红绿但业务相同 | 在比文本，或键序/空白被当成内容 | 用结构 Diff；先格式化 |
| 数组「全变了」 | 按位置比较，元素顺序变了 | 确认业务是否关心顺序；必要时先按 id 排序再比 |
| 没报差异但线上有 bug | 比错了环境或贴成同一份 | 检查左右来源；用交换/清空重来 |
| 浮点末位不同 | 序列化精度、语言差异 | 业务层约定圆整或字符串化金额 |
| 时间字段总不同 | 每次请求生成新时间戳 | 对比前剔除或掩码易变字段 |
| 一侧非法仍「有结果」 | 未真正 parse | 以格式化校验为准 |
| Unicode 转义不同 | \u4e2d 与汉字是同一码点 |
结构相等则忽略文本写法 |
| 大整数末尾不同 | JS 精度 | ID 当字符串比 |
| 只有 key 大小写不同 | 路径大小写敏感 | 按真实解析器规则，不要假设不敏感 |
故意制造的对照：
左侧：
{"user":{"id":"1001","roles":["a","b"]},"ok":true}
右侧：
{"ok":true,"user":{"id":"1001","roles":["a","b","c"]}}
键顺序不同、多了 roles[2]。合格的结构 Diff 应主要报 roles 相关新增，而不是整对象删除再添加。若你看到的是「整文件重写」，说明在用不合适的文本对比方式。
5. 真实场景
场景 A：前后端联调「字段对不上」
前端说缺字段，后端说「响应里有」。把浏览器 Network 里实际 JSON 与接口文档示例分别贴左右，Diff 一次。常见结论：字段在嵌套里（data.profile.avatar vs 顶层 avatar）、或文档过期。再把预发与生产各抓一条，排除环境配置漂移。
场景 B：配置中心 vs 本地文件
从配置中心导出的 JSON 与仓库里的 config.json 对比。先两边格式化。若只有键排序不同，结构 Diff 应接近空；若出现权限开关、超时毫秒数变更，再决定是否发布。敏感值对比前掩码。
场景 C：重构接口的「兼容性体检」
旧版与新版 API 对同一请求各打一次。期望：业务字段兼容，允许新增字段。Diff 上应主要是 added，不应大量 removed/changed。若核心字段类型从数字变字符串，即使 UI「还能显示」，也要记入 breaking change。
场景 D：YAML 配置改完后的等价检查
用 JSON ↔ YAML 把改前改后的 YAML 都转到 JSON，再 Diff。这样可避开纯缩进引起的 YAML 文本噪音，专注数据。注意转换本身的类型坑（见 JSON-YAML 指南），Diff 报的类型变化有时来自转换而非你的业务提交。
6. 检查清单
- [ ] 左右来源标注清楚（环境、时间、请求 ID）
- [ ] 两侧均为合法 JSON（格式化无报错）
- [ ] 已格式化后再点比较
- [ ] 已知易变字段（时间戳、请求 id、签名）已剔除或忽略
- [ ] 数组是否允许乱序已有业务结论
- [ ] 大整数/金额已按字符串策略处理
- [ ] 结论写的是路径级变更，不是「两边不一样」一句话
- [ ] 含隐私的响应用完清空页面
8. 常见问题
为什么格式化后 Diff 更少了？
若你之前用的是文本对比，格式化会改变换行从而「看起来」差异变多或变少，结果不稳定。结构 Diff 在合法前提下应主要对数据敏感。若格式化后结构 Diff 结果变了，说明至少有一侧格式化前并未正确解析，或你看的不是同一工具结果。
键顺序不同算不算差异？
对绝大多数 JSON 对象，规范不保证键序，程序也按键名访问。结构 Diff 通常视同序对象为相等。若你的下游荒谬地依赖键序，那是下游问题，应在文档里单列，而不是要求所有 Diff 工具按文本序报警。
数组顺序变了为什么一片红？
常见实现按索引对齐。[a,b] 与 [b,a] 会显示位置 0、1 都变了。若元素有稳定 id，先按 id 排序再贴进比较器，或只抽取 id 集合比较。不要假设所有 Diff 都会自动「集合语义」比较数组。
可以把两个文件拖进 Git 代替这个工具吗？
可以看文本，但格式化重排、键序、一行变多行时噪音大。结构工具更适合 API 与配置语义。两者互补：发布审查用结构 Diff，仓库历史仍用 Git。
比较结果能否当自动化断言？
页面适合人工快速确认。回归测试应把同样的结构比较放进 CI（契约测试、快照）。把人工 Diff 的结论沉淀成「允许新增的路径列表 / 禁止变更的路径列表」，价值远大于一次截图。
9. 下一步
- 打开 JSON Diff，点「加载示例」熟悉图例。
- 用同一份 JSON 左右各贴一次，确认「无差异」基线。
- 只改右侧一个嵌套字段与一个数组元素，再比较，练习读路径。
- 下次联调从 Network 复制真实响应，先格式化再 Diff，把路径写进缺陷单。