接口联调时，最费时间的往往不是请求发不出去，而是“看起来差不多”的两份数据到底哪里不同。
一份 JSON 只是对象字段顺序变了，文本 diff 却整页飘红；XML 换了命名空间前缀，实际节点含义没变；又或者配置里的 1 被写成 "1"，肉眼很容易漏掉。处理这类问题，先要把格式、语义和差异分开。
本文用 JSON 与 XML 的常见场景，梳理格式化、结构化比较的实现思路。
一、格式化不是美化，而是先让结构可读
先看一段压缩的接口响应：
{
"id":1024,"name":"edge-gateway","enabled":true,"rules":[{
"path":"/api","timeout":3000},{
"path":"/health","timeout":500}]}
它是合法 JSON，但不方便检查字段层级。格式化后：
{
"id": 1024,
"name": "edge-gateway",
"enabled": true,
"rules": [
{
"path": "/api",
"timeout": 3000
},
{
"path": "/health",
"timeout": 500
}
]
}
这一步通常是“解析后再序列化”：
const value = JSON.parse(input);
const formatted = JSON.stringify(value, null, 2);
JSON.parse() 负责验证语法，JSON.stringify() 负责输出统一缩进。遇到缺少逗号、键名未加双引号、末尾多一个逗号等问题，应该直接报错，而不是擅自修复。猜测用户本意很危险，特别是配置文件和接口样例。
JSON 的标准允许对象、数组、字符串、数字、布尔值和 null 作为顶层值；对象成员名应保持唯一。RFC 8259 也明确提到，重复成员名会让不同实现出现不同结果，有的保留最后一个，有的报错。
日常整理接口数据时，可以用 JSON Formatter 完成校验、格式化、压缩和对象键排序。键排序适合生成较稳定的配置快照，但要注意：对象键可以排序，数组不能随手排序。数组通常表达的是有顺序的列表。
二、文本不同，不等于 JSON 数据不同
下面两份 JSON 的文本内容不同：
{
"name": "worker",
"retries": 3
}
{
"retries":3,"name":"worker"}
如果用普通文本 diff，会看到缩进和字段位置都变了。可从 JSON 语义看，两者相同。JSON 对象是无序的名称和值集合，字段顺序本身不应决定比较结果。
结构化比较的基本流程是：
解析 JSON
→ 校验输入
→ 对象按键名比较
→ 数组按索引比较
→ 输出字段路径和变化类型
例如，旧配置：
{
"service": {
"port": 8080,
"debug": false
},
"regions": ["cn-hangzhou", "cn-shanghai"]
}
新配置：
{
"service": {
"port": "8080",
"debug": true
},
"regions": ["cn-hangzhou", "cn-beijing"],
"timeout": 5000
}
结构化比较应该输出这类结果：
/service/port：类型变化，number → string
/service/debug：值变化，false → true
/regions/1：值变化，"cn-shanghai" → "cn-beijing"
/timeout：新增，5000
路径可以采用 JSON Pointer 风格。它比“第 27 行不同”更适合接口调试，因为格式化方式改变后，行号会变，字段路径不会变。
JSON Diff Checker 会按 JSON 结构比较两份输入：对象字段顺序和空白字符不会造成差异；数组元素按索引比较；缺失字段、null、值变化和类型变化会分别标出。
这里有两个常见误判。
第一，null 不等于字段不存在：
{
"token": null }
和：
{
}
语义不同。前者表示字段存在，值为空；后者表示字段根本没有出现。
第二，数字 1 不等于字符串 "1"。有些接口在宽松语言里会自动转换，但这不应该成为比较工具默认忽略的差异。类型变化往往正是联调失败的根源。
三、数组的顺序要不要比较，取决于业务语义
JSON 对象字段一般按键名比较，但数组不能一概而论。
例如发布流程：
{
"steps": ["build", "test", "deploy"]
}
把数组改成：
{
"steps": ["deploy", "build", "test"]
}
这显然是变化，甚至可能导致严重后果。数组应按索引比较。
但如果数组只是标签集合：
{
"tags": ["prod", "edge", "api"]
}
业务可能并不关心顺序。这时不能简单把它当作普通数组比较，而应在业务层显式定义为集合，再按集合规则处理。
通用工具不应猜测数组里哪个字段是主键、元素是否允许移动、顺序是否可忽略。默认按索引比较更保守，也更容易解释。
四、XML 比较的难点在命名空间和空白字符
XML 看起来像标签文本，实际是树结构。下面两段 XML 的前缀不同：
<a:order xmlns:a="https://example.com/order">
<a:id>1001</a:id>
</a:order>
<o:order xmlns:o="https://example.com/order">
<o:id>1001</o:id>
</o:order>
如果只比较标签文本，结果会认为完全不同。实际应比较元素的命名空间 URI 和本地名称：
namespace URI: https://example.com/order
local name: order
两份 XML 的节点身份相同，前缀只是书写方式。
XML 结构化比较通常需要处理这些规则：
- 元素通过命名空间 URI 和本地名称识别；
- 属性顺序不影响语义；
- 子节点顺序通常有意义；
- 缩进产生的纯空白文本节点可按需求忽略；
- 注释是否比较，应由场景决定；
- CDATA 的内容应按文本处理。
例如：
<server host="api.example.com" port="443" />
与：
<server port="443" host="api.example.com"/>
属性顺序不同，但通常应判定为相同。
而下面两份文档不能简单视为相同：
<workflow>
<step>build</step>
<step>deploy</step>
</workflow>
<workflow>
<step>deploy</step>
<step>build</step>
</workflow>
子节点顺序已经变化。XML 规范定义了文档中元素和内容的顺序，比较时应保留这个信息。W3C XML 1.0 规范 是相关语法与结构规则的基础参考。
需要核查配置、SOAP 报文或旧系统导出的 XML 时，可以使用 XML Compare。它会按节点结构、属性和有序子节点对比，并识别命名空间 URI，而不是只盯着前缀和缩进。
五、比较前先确定“什么算相同”
格式化和比较工具能减少人工排查时间，但不能替代业务规则。动手之前，最好先定下这几个问题：
| 数据类型 | 默认比较方式 | 需要业务确认的地方 |
|---|---|---|
| JSON 对象 | 按键名和值比较 | 是否忽略某些动态字段 |
| JSON 数组 | 按索引比较 | 是否应按集合或主键比较 |
| XML 属性 | 忽略属性顺序 | 是否忽略特定属性 |
| XML 子节点 | 保留顺序 | 子节点是否允许重排 |
| XML 空白文本 | 可忽略缩进空白 | 内容中的空格是否有业务意义 |
例如响应里的 requestId、时间戳和签名字段，每次请求都会变。如果它们不属于本次核查目标，应在比较前明确排除。把动态字段留在结果里，只会制造噪声。
六、一个实用的排查顺序
遇到“接口返回不对”或“配置发布后行为异常”时，可以按下面顺序处理：
- 先格式化并校验单份 JSON，确认问题不是语法错误。
- 对两份 JSON 做结构化比较，优先检查类型变化、字段新增和字段删除。
- 遇到数组差异，回到业务规则确认顺序是否有意义。
- XML 使用命名空间感知的比较，不要直接拿两段文本做 diff。
- 先排除时间戳、请求 ID 等已知动态字段，再判断实际变更。
格式化解决的是“看不清”，结构化比较解决的是“差在哪”。两者配合后，很多原本要在日志里翻半天的问题，通常能收敛到一个字段路径或一个 XML 节点。
