Javascript is required

JSON 语义对比与 API 字段差异

语义化 JSON 对比工作台

按字段路径比较,选择数组顺序规则并筛选结果行;破坏性标记需要结合接口契约复核。

数组对比:
路径过滤:
基准 JSON (原始版本)
目标 JSON (新版本)
Diff 对比结果

等待输入

四组可重复的 API 比较案例

载入案例会替换两份输入并重置全部比较选项。修改一个选项即可观察另一种结果。

对象键顺序改变

基准输入

{
  "id": 101,
  "status": "active"
}

变更后输入

{
  "status": "active",
  "id": 101
}

初始选项: 忽略键顺序开启;数组按索引;没有筛选条件。

预期结果: 没有差异。关闭“忽略 Key 顺序”后,$ 会显示一条 key-order 行。

键顺序只是可选比较信号,不能据此判断业务兼容性。

带重复项的数组重排

基准输入

{
  "tags": ["reader", "admin", "reader"]
}

变更后输入

{
  "tags": ["reader", "reader", "admin"]
}

初始选项: 忽略键顺序开启;数组按索引;没有筛选条件。

预期结果: $.tags[1] 和 $.tags[2] 出现两条 changed 行,破坏性标记为零。切换到无序集合模式后没有差异。

无序比较保留重复项,不会按 ID 配对元素。

路径子串同时命中两个字段

基准输入

{
  "user": {"name": "Ada"},
  "username": "ada",
  "version": 1
}

变更后输入

{
  "user": {"name": "Grace"},
  "username": "grace",
  "version": 2
}

初始选项: 忽略键顺序开启;数组按索引;路径筛选为 user。

预期结果: 显示 $.user.name 与 $.username,隐藏 $.version。将条件改为 missing 会隐藏全部结果行,但总体报文仍有差异。

筛选只隐藏报告行;使用不区分大小写的子串匹配,不执行 JSONPath 查询。

字段删除与值类型变化

基准输入

{
  "id": 101,
  "displayName": "Ada",
  "active": true
}

变更后输入

{
  "id": "101",
  "active": false,
  "role": "reader"
}

初始选项: 忽略键顺序开启;数组按索引;仅显示破坏性变更开启。

预期结果: 两条破坏性结果:$.id 为 type-changed,$.displayName 为 removed。关闭破坏性筛选后,还会显示 $.active 的 changed 与 $.role 的 added。

值变化不会被标记为破坏性,即使业务行为依赖该值。

JSON 字段比较的实际规则

分别粘贴基准报文和待比较报文,按字段路径查看新增、删除、值变化与类型变化。默认忽略对象键顺序;关闭该选项后,也会报告键顺序差异。

先选择按索引或无序数组模式,再审阅报告。路径筛选与“仅显示破坏性变更”只隐藏结果行,总体差异状态和破坏性计数仍反映完整比较。下载的 Markdown 包含筛选后的行与总体计数。

使用边界与限制条件

  • 无序模式先按序列化值排序,再逐项比较,并保留重复项。它不会按记录的 ID 字段配对;报告中的数组索引对应排序后的数组。
  • 路径筛选使用不区分大小写的子串匹配,逗号分隔多个条件,不执行 JSONPath 表达式。例如 user 同时匹配 $.user.name 与 $.username。
  • 破坏性标记只覆盖删除和类型变化。枚举、单位、字段含义变化或新增字段仍可能影响调用方,即使没有此标记。
  • 无效 JSON 会回退为文本比较,不提供语义报告。有效输入使用 JSON.parse,大整数可能丢失精度。比较在主线程执行,内存与渲染开销取决于输入,不承诺固定文件大小。

常见问题与技术解答 (FAQ)

只改变对象键顺序会出现差异吗?▼

启用“忽略 Key 顺序”时,键顺序案例没有差异;关闭后会在 $ 报告 key-order 行。新增或删除键也可能改变记录到的键序列。

无序数组模式会去重或按 ID 匹配吗?▼

不会。它按序列化值排序、保留重复项,再按排序后的索引比较。相同值的重排被忽略,但删除重复项仍会报告删除;记录不会按 ID 字段配对。

为什么 user 路径筛选也匹配 username?▼

筛选条件会在整个报告路径中进行不区分大小写的子串搜索,逗号表示多个候选条件。若筛选后没有结果行,但完整报文不同,总体差异状态仍然保留。

没有破坏性标记就说明 API 更新兼容吗?▼

不能这样判断。标记只覆盖删除和类型变化,值变化也可能改变业务行为;筛选不会减少总体破坏性计数。请结合接口契约和调用方测试审阅报告。