教程 ↗

API 返回 200,字段却变了:比较两份 JSON 的响应结构

用完整合成响应比较字段增删、嵌套路径与类型变化,解释空数组、混合类型和 null 的边界,并在浏览器内导出结构差异报告。

旧响应中的数字 id 变成新响应中的字符串,成功状态码下仍出现结构变化

假设订单页一直把 items[0].quantity 当作数字,接口某次更新后改成了字符串。请求依然返回 200 OK,JSON 也能正常解析,但后面的加法、校验和显示逻辑已经可能走向另一种结果。只检查状态码,看不到这个变化;逐字比较整个响应,又容易被每次都变的请求 ID、时间和业务值淹没。

API 响应结构比较工具接收旧、新两份 JSON,提取每个字段路径上观察到的类型,报告路径增加、路径消失和类型集合变化。可以粘贴文本,也可以读取本地文件;输入和报告都在浏览器内处理。下面用同一组完整合成样例,从输入一直走到可下载的结果。

先把成功状态和调用端需要的结构分开

这个选题来自一篇 r/webdev 帖子。作者用“监控全绿,客户却发现短信流程坏了”的故事介绍 API Drift Watch。项目 README描述了定时请求、提取响应结构、与仓库基线比较、更新告警 issue 的流程。这些是作者提供的故事与功能说明;本文的可复现实验使用下方合成 JSON。

README 中的 Action 示例仍有 uses: <owner>/api-drift-watch@v1 占位。本文没有运行这份工作流,也没有调用 Twilio 或 SendGrid。这里抽出的是一个可以独立检查的环节:拿到两份响应后,调用端关心的字段路径和类型发生了什么变化?

状态码、结构和业务含义分别回答不同问题。200 说明服务器把这次请求按成功处理;quantity 是否仍为数字,属于响应结构;数量从 1 变为 -1 是否可接受,则要看业务约定。结构比较适合定位第二层,业务范围仍需要调用端的校验和测试。

一组可以直接载入的旧、新响应

打开工具并载入样例。旧响应是:

{
  "request_id": "sample-100",
  "customer": {"id": "cus_42", "email": "mina@example.test"},
  "items": [{"sku": "starter", "quantity": 1}],
  "legacy_flag": true,
  "metadata": {"source": "sample-old"}
}

新响应是:

{
  "request_id": "sample-101",
  "customer": {"id": "cus_42", "email": null, "plan": "pro"},
  "items": [{"sku": "starter", "quantity": "1", "discount": {"code": "WELCOME"}}],
  "status": "accepted",
  "metadata": {"source": "sample-new"}
}

这些名字、地址和业务值都是合成数据。request_id 与 metadata.source 都换了值,类型仍是 string,因此不会出现在差异清单。customer.email 从字符串变成 null,quantity 从数字变成字符串,才会产生类型变化。

桌面上旧、新输入并列显示;窄屏通过两个输入标签切换,另一侧的草稿会保留。确认旧数据位于旧响应一侧,再点击比较。方向决定增加和删除的含义。

英文工具界面中的完整合成响应与结构差异结果

旧、新响应比较后,结果紧接输入区显示。

从 JSON 到路径与类型,再到七条差异

比较器先严格解析 JSON,再遍历对象和数组。对象属性写成带引号的路径段:$["customer"]["email"]。数组元素合并到 [*],所以所有 items 元素的数量字段都归到 $["items"][*]["quantity"]。

这一步产生的是中间结构,下面列出其中几项:

路径旧样本观察到的类型新样本观察到的类型
$objectobject
$["request_id"]stringstring
$["customer"]["email"]stringnull
$["items"]arrayarray
$["items"][*]objectobject
$["items"][*]["quantity"]numberstring

路径采用这种写法,是为了分清属性名和层级。例如,属性名 "a.b" 是一个键,不能误拆成 a 下的 b;对象里的 "*" 也要与数组通配段 [*] 区分。

接着按路径对齐两份结构,比较类型集合。完整样例得到 7 条差异:4 条增加、1 条删除、2 条类型变化:

路径变化旧 → 新
$["customer"]["email"]类型变化string → null
$["customer"]["plan"]增加缺失 → string
$["items"][*]["discount"]增加缺失 → object
$["items"][*]["discount"]["code"]增加缺失 → string
$["items"][*]["quantity"]类型变化number → string
$["legacy_flag"]删除boolean → 缺失
$["status"]增加缺失 → string

discount 和 discount.code 是两条路径,所以分别计数。若整个对象消失,也会同时列出容器及其已经观察到的子路径。这个计数方便定位,不等同于七个独立故障。

嵌套层级改变也按路径处理。例如 {"email": "a@example.test"} 变成 {"contact": {"email": "a@example.test"}},会报告 $["email"] 删除、$["contact"] 和 $["contact"]["email"] 增加。工具不会猜测这是不是同一个字段搬了位置;调用端仍需把读取路径一起改对。

报告记录路径、变化方向、旧类型和新类型,不包含 mina@example.test、WELCOME 等原值。字段名本身仍会进入报告;分享前应确认路径中没有业务上敏感的名称。

空数组、混合数组与 null 怎么读

结构来自有限样本,数组尤其需要小心解释。

{"items": []}

这里只有 $["items"]: array 的证据,还没有任何元素类型。若新样本变成下面这样:

{"items": [{"id": 1}, null, "sample"]}

新结构会包含 $["items"][*] 上的 null、object、string 三种类型,以及 $["items"][*]["id"] 上的 number。比较结果把这两条新观察到的路径列为增加。它可能只是旧请求恰好没有数据,需要结合请求条件和 API 文档判断是否真的发生了契约变更。

数组会遍历限制范围内的全部元素,并在同一路径合并类型;只调换元素顺序不会造成差异。这个合并也会丢掉元素之间的关联。例如:

[{"id": 1}, {"name": "Mina"}]
[{"id": 2, "name": "Bo"}]

两者都在 $[*]["id"] 观察到 number、在 $[*]["name"] 观察到 string,结构清单相同。单个元素是否必须同时具备这两个字段,要由完整 schema 或消费端测试来表达。工具也不会据样本自动推断必填、字符串格式、枚举值或数值范围。

null 则是独立类型。{"email": null} 中存在 email 路径,{} 中没有这个路径;这两份输入比较会得到删除。报告中的空类型列表表示该侧没有观察到路径,与 null 的意思不同。

连续修改、失败与恢复

可以先保留新响应的所有字段,只把 request_id 改成另一个字符串,再次比较:原来的七条结构变化仍然存在。若两侧字段和类型完全一致、只有值不同,结果是没有结构差异。这个结果的范围就是屏幕中的两份样本。

编辑任一侧后,工具保留上次有效结果,并标出结果已过期。故意在新响应末尾多加一个逗号,再点击比较,错误会指出新响应及行、列;旧结果仍可查看。需要继续核对旧结果时,可以恢复生成那份结果的输入。

英文窄屏界面指出无效 JSON,并保留上次结果及恢复入口

输入出错后,仍可恢复上次有效比较。

读取另一份文件或取消选择也应保留已有工作。交换旧、新输入后,增加与删除会反向,类型变化的两端也会互换;重新比较后再按新方向导出。过期状态下的导出入口明确指向上次结果,避免把旧报告当作当前草稿的比较结果。

每侧输入限制为 1 MiB,最多 64 层对象或数组、20,000 个值或容器节点。注释、尾逗号和重复属性名会被拒绝。重复键如 {"id": 1, "id": "1"} 容易被普通解析器覆盖成最后一个值,直接拒绝能让比较的输入更明确。较大的响应可以先在本地选取需要诊断的代表性片段,并保留原有嵌套关系。

导出报告,把差异交给下一步测试

结果可以复制,或下载为 JSON 与纯文本。先确认方向,再下载;如果界面标明上次结果,先恢复它的输入或重新比较。页面刷新后内存中的输入和结果会消失,需要保留的报告应先下载。

下载完整合成样例与预期结果。可以用其中的旧、新 JSON 分别载入工具,对照结构快照与差异清单,核对这七条结果。文件名和输入原文不会写入工具导出的差异报告。

拿到这份清单后,检查实际消费对应路径的代码:字符串数量是否被明确转换,email: null 是否有显示分支,删除的 legacy_flag 是否仍在控制流程。把这些场景加入调用端测试,再决定是否接受新的结构基线。之后若要把响应整理成表格,可以继续看 JSON 转 CSV 的显式列映射与信息边界,保留本次已经确认的字段语义。

← 返回列表