JSON格式化与校验实战：接口调试、Schema与精度陷阱

1. 接口调试前的第一道工序：JSON 格式化与校验到底在做什么

1.1 从一段没法看的响应体说起

上周帮一个同事定位联调问题，他把接口响应直接甩到群里，8KB 的字符串，全挤在一行里，横向滚动条拖了三屏还没到底。里面嵌套了三层数组，字段名 data、list、items、rows 混着用，中间还夹着几个转义过的引号，末尾跟着一坨时间戳。他说找不到问题在哪儿，其实问题就藏在那串字符里——某个本该是数字的字段，接口返回成了字符串，人眼在一整行里根本没法比对。

这种场景在接口联调里出现频率极高。压缩过的 JSON 是给网络传输用的，省带宽、省解析开销，但它不是给人看的。JSON 格式化与校验要做的事情很朴素：把"机器格式"翻译回"人格式"，并且在开始读之前，先确认这份数据本身是否合法。它解决的痛点很具体——层级看不清、错误看不见、改完不知道对不对。

不管你写前端、写后端、做测试还是做对接实施，只要你会打开接口调试窗口看响应体，这套动作就该变成肌肉记忆。新手常犯的毛病是拿到数据就直奔业务字段，老手会先干两件事：格式化、校验，然后才开始聊业务。顺序错了，后面全是白费功夫，因为你在读一份可能根本不成立的数据。

1.2 格式化和校验是两件不同的事，很多人把它们混为一谈

我见过不少人对格式化的理解停留在"按一下快捷键让它变好看"。实际上格式化和校验解决的是两个完全不同层面的问题，而且它们之间存在严格的依赖关系。

格式化是把一段已经被成功解析的数据结构，重新序列化成带缩进、带换行的文本。它的输出依然是 JSON，只是排列方式变了。

校验是判断这段文本是否符合规范——能不能被解析、字段齐不齐、类型对不对、值域合不合理。它的输出是一个结论：通过，或者在第几行第几列出了什么问题。

关键在于：任何格式化工具内部都跑着一个完整的解析器。它先把你的文本读成内存里的对象树，再按规则重新打印出来。这意味着，只要你的 JSON 有语法错误，格式化工具根本没法工作，它只会甩给你一句报错。所以"先格式化看看"这个动作本身，就已经完成了一次语法校验。

我经常跟人说，正确的顺序是：拿到原始数据 → 原样存档 → 语法体检 → 格式化 → 结构校验 → 业务语义校验。跳过语法体检直接格式化，你得到的是一个报错而不是结果；跳过结构校验直接看业务，你会在一个字段类型都错的响应里推理半天。

1.3 三类典型故障的定位成本对比

为了说清楚这道工序的价值，我把日常遇到的故障按定位成本列了个表。这里的"耗时"是我自己在中等复杂度响应（大概 200 行、4 层嵌套）上的粗略估计，因人而异，但量级是准的。

表格里最后一行值得单独说一句。它属于那种"格式化和校验都做了，但只要没专门盯着就发现不了"的问题，后面第 2 章会展开讲。这张表想表达的结论是：格式化和校验不是什么"讲究"，它把几类高频故障的定位成本从分钟级压到秒级，一天调五个接口，省下来的时间够你把文档写完。

2. 格式化的底层逻辑：解析、序列化与大数字陷阱

2.1 格式化器内部其实跑着一个完整的解析器

很多人把格式化当成"文本美化"，这个理解是错的，而且会导致一系列误判。格式化工具的工作流程是这样的：读入原始文本 → 逐字符扫描成 token → 按 JSON 语法规则构建对象树 → 再按目标风格把对象树重新打印成文本。中间那一步"构建对象树"，就是完整的解析过程。

理解这一点，几个看似奇怪的现象就都有了解释。

第一，为什么格式化工具没法修复非法 JSON？因为它卡在了第二步，树根本没建起来，谈不上重新打印。有些人指望格式化工具顺手把单引号改成双引号、把尾随逗号删掉，这是不可能的，那是"修复工具"的活，不是格式化器。

第二，为什么格式化之后数字的写法可能变了？因为数字在解析阶段被转成了语言内部的数值类型，打印时按语言的默认规则输出。1e3可能变成1000.0，1.0可能变成1，0.10变成0.1。这不是 bug，是数值语义归一化的必然结果。

第三，为什么字段顺序可能被打乱？对象在多数语言的实现里是无序的（或者按插入顺序但可以被工具重排），所以格式化工具可以自由决定输出顺序。这在做响应比对的时候是致命的——同一份数据两次打印，顺序不一样，diff 工具会报一堆假差异。解决办法是用带排序功能的参数，让输出稳定下来。

搞清这条链路，你就知道格式化不是万能的，它能给你的是可读性，不是合法性保证。合法性要靠校验来解决。

2.2 缩进、排序、转义这三个参数必须搞明白

格式化通常有若干可调参数，大部分人只用默认值，但有三项值得专门配置，因为它们直接影响你调试时的判断。

缩进宽度。两个空格是接口调试的主流选择，理由是嵌套层级深的时候不至于把内容挤到屏幕外。四个空格可读性更好，但在六层嵌套的响应里会让右边界跑到屏幕外面去。我的习惯是接口数据一律两空格，配置文件和代码里的常量用四空格。团队里如果有人用一种、有人用另一种，做 diff 的时候会满屏都是缩进差异，白白浪费注意力。

键排序。这一项在做响应比对时是刚需。默认不排序时，两次响应的字段顺序一旦变化，diff 工具会把整块内容都标成改动，你需要在噪音里找真正的差异。开启排序之后，同样的键会落在同样的行上，差异一目了然。命令行里这个能力通常叫 sort keys，编辑器插件里一般是一个"按字母排序"的开关。

中文转义。JSON 规范允许把非 ASCII 字符写成\uXXXX形式。一个中文字符会变成六个字符，一个正常的中文提示语 "用户名不能为空" 会变成一长串\u7528\u6237\u540d...。这种转义在传输上没问题，但调试时完全没法读。多数工具默认会把转义还原成可读字符，但有些库的默认行为是全部转义（Python 的 json.dumps 就是如此），需要显式关掉。我在排查带中文错误提示的接口时，经常要先把这一项打开，否则满屏都是反斜杠和 u。

2.3 精度陷阱：为什么你的订单号最后几位莫名其妙变成了 0

这是我踩过最疼的一个坑，必须单开一节讲。

在 JavaScript、以及所有遵循 IEEE 754 双精度浮点的解析环境里，能精确表示的整数上限是 2 的 53 次方，也就是 9007199254740992。超过这个值，数值就会丢失精度。而很多业务系统生成的订单号、流水号、雪花算法 ID 都是 18 位甚至 19 位十进制数，早就超了。

具体表现是这样的：

// Node 环境 const text = '{"orderId": 1234567890123456789}'; const obj = JSON.parse(text); console.log(obj.orderId); // 输出：1234567890123456800

最后三位变成了 800。你把这个对象再序列化回去发给下游，下游收到的就是一个错误的订单号。整个链路里没有人报错，没有任何异常日志，只有对账的时候发现钱对不上。

这个问题在调试阶段的表现更隐蔽：你在浏览器开发者工具里看到的响应是原始文本，看着是对的；一旦你复制那段 JSON 到某个工具里"格式化一下"，工具内部用 JS 解析了一遍，显示出来的就已经是被截断的数字。你以为你看到的是接口返回的，其实是解析器改写过的。

规避方式有三条，按推荐程度排序：

• 让接口把大数字用字符串传。这是最稳的做法，前端拿到字符串直接透传，不做数值运算。虽然破坏了"数字就该是数字类型"的纯洁性，但在工程上这是唯一可靠的方案。
• 在解析阶段保留原始字符串。Python 的 json.loads 提供了parse_int=str参数，可以让所有整数以字符串形式返回，不做数值转换。Node 侧可以用支持大数的库，或者在反序列化前做正则预处理给大数字加引号。
• 格式化工具的预览结果不可信。用 JS 内核实现的在线工具查看含大数字的 JSON 时，看到的数字可能已经被改过。想看原始值，直接看文本。

注意：这条对金额字段同样适用。以"分"为单位的金额通常是整数，如果金额超过 900 万（以分计就是 9 亿分），在 JS 环境里就已经在精度边界附近了。别觉得"钱能有多大"。

2.4 格式化的三种输出风格怎么选

缩进风格上有个小分歧：两空格、四空格、Tab。接口数据我建议统一两空格，理由是 JSON 的嵌套往往比代码更深，四空格在四层以上就开始折行了。团队里如果有统一规范最好，没有的话，做 diff 之前先统一格式化一次，能省掉大量假差异。

另一个风格选择是"单行紧凑"和"多行展开"。请求体在浏览器的网络面板里默认是紧凑的，方便看长度；但调试时你需要的是多行展开。有些工具支持"一键压缩/一键展开"的双向切换，做回归测试时压缩看体积，排查问题时展开看结构，这两种用法可以并存。

3. 工具矩阵与选型：编辑器、命令行、脚本该怎么搭

3.1 四类工具的适用边界

我日常会用到四类工具，它们不是互相替代的关系，而是覆盖不同场景。下面这张表是我自己的使用分布，供参考。

选型不用纠结，判断标准就三条。

数据敏不敏感。生产环境的响应里带着手机号、身份证、订单金额，这类数据一律不进在线页面。这条没有例外，我见过把真实用户数据贴到公开工具里还截图发群的，后果不用多说。

是一次性还是重复性。如果这个接口你只调一次，编辑器快捷键足够；如果这个接口要反复调、要回归、要写进测试用例，那值得花二十分钟写个脚本，后面每次运行省三分钟，一周就回本了。

在本地还是在服务器。很多问题只在测试环境的服务器上复现，本地没有同样的数据。这时候命令行工具是唯一选择，因为它能直接在服务器上跑，不用把数据搬来搬去。

3.2 命令行三件套的实操命令

命令行处理 JSON 的能力，基本靠三个东西：一门脚本语言的 JSON 库、一个专用的 JSON 查询工具、一个通用的文本工具。三者的分工是——脚本语言负责复杂逻辑和校验，查询工具负责抽取和格式化，文本工具负责比对。

先看格式化。Python 自带的模块就能干这事，不需要装任何东西：

# 基础格式化：读文件、两空格缩进、输出到终端 python3 -m json.tool response.json # 保留中文可读，不转成 \uXXXX（Python 3.9 及以上支持） python3 -m json.tool --no-ensure-ascii --indent 2 response.json # 从标准输入读，配合管道使用 cat response.json | python3 -m json.tool --no-ensure-ascii # 输出到新文件，保留原文件不动 python3 -m json.tool --no-ensure-ascii response.json > response.pretty.json

注意最后一条的写法。我强烈建议永远输出到新文件，不要在原文件上覆盖。原始响应是证据，改过之后如果出了问题你没法回溯"接口到底返回了什么"。

如果用专门的 JSON 查询工具，命令会更短，而且它自带键排序能力：

# 格式化，默认两空格 jq . response.json # 格式化并按字母排序键，用于稳定比对 jq -S . response.json # 只取出数组里的部分字段，做成精简视图 jq '.data.list[] | {id, name, status}' response.json # 去掉所有引号，输出纯文本，方便贴进表格 jq -r '.data.list[] | [.id, .name] | @tsv' response.json # 看这个对象有哪些键，快速摸清结构 jq 'keys' response.json # 列出所有叶子节点的路径，用于生成校验清单 jq '[paths(scalars)] | unique' response.json

最后那条命令是我最常用的一个技巧。拿到一个陌生接口的响应，先用它把全部叶子节点路径列出来，相当于自动生成了一份字段清单。这份清单可以直接变成校验脚本的骨架，比对着接口文档一个个核对快得多。

3.3 在线工具的使用红线

在线格式化页面确实方便，打开就能用，不用装环境。但它有三个硬伤，必须心里有数。

一是数据出去了。你粘贴的内容会经过对方的服务器，不管对方怎么承诺不留存，数据事实上离开了你的控制范围。凡是带用户标识、联系方式、金额、地址的数据，一律不用。

二是精度不可控。多数在线工具用浏览器 JS 解析，遇到超过 2 的 53 次方的整数会静默截断，你看到的数字可能不是原文的数字。这个坑在第 2.3 节已经讲透了，用在线工具查看时尤其容易中招，因为你连"被改了"这件事都无从察觉。

三是没法进流程。在线工具是手动的，你今天格式化了，明天换个人还得再来一遍，永远沉淀不下来。

我的用法是：结构不明的公开示例、教程里的样例数据，用在线工具随便看；跟业务沾边的一律走本地命令行或编辑器。这条线划清楚，能避免绝大多数麻烦。

4. 校验的三层结构：语法、Schema、业务语义

4.1 语法层：能被解析只是及格线

语法校验的判定标准只有一条：这段文本能不能被 JSON 解析器接受。它管的事情包括引号是不是双引号、逗号有没有多余或缺失、括号有没有配对、有没有出现规范不允许的字面量。

日常踩到的语法问题高度集中，我把它们整理成了一张对照表：

表格里最容易被忽略的是 BOM 和 NaN 这两条。

BOM 是文件开头的三个不可见字节，Windows 上某些编辑器保存 UTF-8 时会自动加上。肉眼完全看不出来，但解析器会在第一个字符就报错，报错信息还往往指向"第 1 行第 1 列"，让人以为是空文件。处理方式很简单，用 Python 读取时指定encoding='utf-8-sig'，它会自动跳过 BOM。

NaN 和 Infinity 更有意思。JSON 规范里根本没有这两个值，合法的数字只有十进制写法。但 Python 的 json 模块默认会把NaN解析成浮点数的 nan，把Infinity解析成无穷大，完全不报错。这意味着你的校验在 Python 环境里通过了，数据发给前端，前端的解析器直接报错。跨语言系统对接时这个问题会浪费大量时间。

兜底写法是这样：

import json def strict_loads(text): def reject_constant(name): raise ValueError(f"出现非标准字面量：{name}") return json.loads(text, parse_constant=reject_constant)

parse_constant会在解析器遇到 NaN、Infinity、-Infinity 时被调用，抛异常就等于把它们全部拦下。

4.2 结构层：用 Schema 把字段契约写死

语法合法只说明这段文本是"格式正确的 JSON"，不代表它是"你要的那个 JSON"。字段可能少了一个，类型可能不对，数组可能变成了对象。这一层要靠结构校验来解决，主流做法是 JSON Schema。

Schema 本质上是一份用 JSON 写的"数据合同"，描述了这个对象应该长什么样：哪些字段必填、每个字段什么类型、字符串长度范围、数组元素是什么结构、有没有枚举限制。下面是一个订单响应的 Schema 示例：

{ "$schema": "http://json-schema.org/draft-07/schema#", "type": "object", "required": ["code", "message", "data"], "properties": { "code": { "type": "integer", "enum": [0, 1001, 1002] }, "message": { "type": "string", "maxLength": 200 }, "data": { "type": "object", "required": ["orderId", "amount", "items"], "properties": { "orderId": { "type": "string", "pattern": "^[0-9]{19}$" }, "amount": { "type": "integer", "minimum": 0 }, "items": { "type": "array", "minItems": 1, "items": { "type": "object", "required": ["skuId", "qty"], "properties": { "skuId": { "type": "string" }, "qty": { "type": "integer", "minimum": 1 } } } } } } } }

注意 orderId 这里我特意写成了字符串类型加 19 位数字的正则。原因就是第 2.3 节讲的大数字精度问题——在合同层面就规定它必须是字符串，下游就不会有人误用数值类型去接。

Python 侧的校验脚本大概是这样：

import json import sys from jsonschema import Draft7Validator with open("schema.json", encoding="utf-8") as f: schema = json.load(f) with open("response.json", encoding="utf-8-sig") as f: data = json.load(f) validator = Draft7Validator(schema) errors = sorted(validator.iter_errors(data), key=lambda e: list(e.path)) if not errors: print("结构校验通过") sys.exit(0) for err in errors: path = "/".join(str(p) for p in err.path) or "(根节点)" print(f"[{path}] {err.message}") sys.exit(1)

iter_errors和validate的区别值得说一句：validate遇到第一个错误就抛异常，适合快速失败；iter_errors会收集全部错误，适合批量排查。调接口的时候我更愿意一次看到所有问题，而不是改一个跑一次。

4.3 语义层：Schema 管不到的那部分

Schema 能表达的是"形状"，表达不了"意义"。有一类问题它永远抓不到：

• 跨字段一致性：明细金额之和等于总金额，结束时间晚于开始时间，两个字段要么都有值要么都为空。
• 跨对象关联：订单里的商品 ID 在商品列表里是否存在，删除标记和状态字段是否矛盾。
• 业务规则：状态为"已支付"时支付时间不能为空，退款金额不能超过原订单金额。
• 幂等与重复：同一个请求 ID 是否已经处理过，数组里有没有重复的 ID。

这些只能靠写代码判断。我的做法是在 Schema 校验通过之后，追加一段语义检查，每个规则一个函数，返回问题列表。写法很朴素，但能拦住绝大多数"格式全对、业务全错"的情况：

def check_semantics(order): problems = [] items = order["data"]["items"] total = order["data"]["amount"] # 规则一：明细之和等于总额 if sum(i["qty"] * i.get("price", 0) for i in items) != total: problems.append("明细金额之和与总额不一致") # 规则二：商品 ID 不能重复 sku_ids = [i["skuId"] for i in items] if len(sku_ids) != len(set(sku_ids)): problems.append("明细中存在重复商品") # 规则三：状态与时间字段的联动 if order["data"].get("status") == "PAID" and not order["data"].get("payTime"): problems.append("已支付状态缺少支付时间") return problems

这段代码不长，但它把"格式全对但业务全错"这类问题挡在了调试环节之前。实际项目里，语义规则会随着业务演进不断增加，我的建议是每条规则都对应一条曾经真实出过的问题，别为了凑数写一堆永远为真的判断。

5. 完整实操：从抓到一段响应到定位问题

5.1 第一步：原样落盘，保留证据链

拿到响应之后，第一个动作不是格式化，是保存。这个习惯我养成得很晚，吃过亏之后才坚持下来。

保存的意义在于可回溯。你改了三轮参数，第四轮发现问题解决了，但你已经不记得第一轮的响应长什么样，没法对比到底哪个参数的改动起了作用。或者你把 JSON 复制进工具改了半天，最后发现改坏了，原始数据也没了。

命令行的做法：

# 带时间戳保存，避免覆盖 ts=$(date +%Y%m%d_%H%M%S) curl -s -o "resp_${ts}.json" \ -H "Content-Type: application/json" \ -H "Accept: application/json" \ "https://example.test/api/order/detail?id=1001" # 同时记录本次请求的参数，方便复现 echo "id=1001" > "req_${ts}.txt"

接口客户端里也一样，多数工具支持"保存响应"，我一般会在文件名里带上时间、环境、参数三个信息，比如20240512_1030_prod_id1001.json。听起来有点繁琐，但当你需要在二十份响应里找出"哪一份是出问题的那次"时，这个命名规则能救命。

注意：如果响应特别大（几十兆），先看看是不是分页没生效或者查询条件写错了。我遇到过一次，接口返回了全表数据，格式化工具直接卡死。这种情况应该先处理查询逻辑，而不是硬啃这份数据。

5.2 第二步：语法体检与编码清洗

保存好原始文件之后，先做一次不涉及任何改动的体检。这一步只回答一个问题：这段文本合法吗。

# 体检，只看能不能解析，不看内容 python3 -c " import json, sys try: json.load(open('resp.json', encoding='utf-8-sig')) print('语法合法') except json.JSONDecodeError as e: print(f'第 {e.lineno} 行 第 {e.colno} 列：{e.msg}') sys.exit(1) "

报错信息里的行号和列号是最有价值的信息。很多人看到一大段报错就慌，其实只要看这两个数字，把光标移过去，问题基本就在那一行附近。要注意的是，报错位置经常比真正的问题位置靠后一个字符——因为解析器是在读到不该出现的东西时才发现前面少了什么。比如对象最后多了一个逗号，报错往往指在下一个右括号上。

如果报错莫名其妙，位置显示在第 1 行第 1 列，又确认文件里确实有内容，八成是 BOM 或者编码问题。检查方式：

# 看文件头三个字节 head -c 3 resp.json | xxd # 出现 ef bb bf 就是带 BOM 的 UTF-8

确认之后，清洗一下：

# 去掉 BOM 另存 sed '1s/^\xEF\xBB\xBF//' resp.json > resp.clean.json

还有一种情况是编码不对。接口声明的字符集和实际编码不一致时，中文字段会变成一堆问号或者乱码方块。这类问题的表现是"JSON 语法合法，但中文全错"，属于内容错误而非语法错误，靠语法校验是发现不了的。判断方式是看响应头里的字符集声明，和实际抓下来的字节做比对。处理方式一般是用对应编码读取后重新以 UTF-8 写出。

5.3 第三步：格式化提取与响应比对

语法过关之后，格式化就没什么障碍了。但真正开始定位问题时，光格式化往往不够——你需要的是"只看关心的那几个字段"。

# 完整格式化，用于通读 jq -S . resp.clean.json > resp.pretty.json # 只看列表里的关键字段，快速扫一眼数据 jq -r '.data.list[] | [.orderId, .status, .amount] | @tsv' resp.clean.json # 统计某个状态的记录有多少条 jq '[.data.list[] | select(.status == "PAID")] | length' resp.clean.json # 找出所有字段为 null 的记录 jq '.data.list[] | select(.payTime == null) | .orderId' resp.clean.json # 检查有没有字段完全缺失（注意区分 null 和不存在） jq '.data.list[] | select(has("payTime") | not) | .orderId' resp.clean.json

最后两条命令的区别值得单独强调，这是我排查过最多次的一类问题：字段不存在和字段存在但值为 null是两种完全不同的情况。前者的意思是接口没返回这个字段，可能是不该返回、可能是漏了、可能是版本不匹配；后者的意思是接口明确告诉你"这个字段没有值"。在代码里，前者取出来是 undefined 或者抛键不存在异常，后者是明确的空值，走的分支完全不一样。

排查"为什么昨天还好今天挂了"这类问题，最有用的手段是响应比对：

# 两份响应各自排序格式化，然后对比 jq -S . resp_yesterday.json > a.json jq -S . resp_today.json > b.json diff -u a.json b.json

不排序直接 diff，会被字段顺序变化造成的假差异淹没。加上排序之后，真正的差异会清楚地呈现出来：少了一个字段、多了一层包装、某个值从数字变成了字符串。

5.4 第四步：把检查沉淀成脚本

手工跑过三五次之后，这个接口的检查动作就该固化了。我的一般做法是写一个几十行的脚本，输入响应文件，输出一份检查报告。

#!/usr/bin/env bash # check.sh 用法：./check.sh resp.json set -euo pipefail F="$1" # 1. 语法 python3 -m json.tool --no-ensure-ascii "$F" > /dev/null \ || { echo "语法失败"; exit 1; } # 2. 结构 python3 validate_schema.py "$F" || { echo "结构失败"; exit 1; } # 3. 关键字段抽查 echo "--- 关键字段抽查 ---" jq -r '.data.list[] | [.orderId, .status, (.amount|tostring)] | @tsv' "$F" \ | head -20 # 4. 常见异常扫描 echo "--- 异常扫描 ---" jq '[.data.list[] | select(.amount == null or .amount < 0)] | length' "$F" jq '[.data.list[] | select(.orderId | test("^[0-9]{19}$") | not)] | length' "$F"

这个脚本的价值不在于它有多聪明，而在于它每次跑的结果都一样。人手动检查会漏，会困，会因为"上次看过没问题"而跳过，脚本不会。团队里如果有多个人调同一个接口，脚本还能统一大家的标准，避免"我这边看着没问题"的扯皮。

再往前一步，把它接进持续集成的流水线，每次接口变更自动跑一遍，问题在发布之前就能暴露。

6. 常见报错速查与踩坑实录

6.1 报错信息对照表

我把这几年攒下来的报错信息整理成了一张表，按"看到什么"到"是什么原因"的映射来组织。这张表放在手边，能省掉大量猜测时间。

最后一行不是报错，但它比报错更值得警惕——报错至少告诉你出事了，静默改值不会。

6.2 几个反复踩到的坑

大整数精度。第 2.3 节已经展开讲过，这里只补充一个真实感受：这类问题不会在调试阶段暴露，只会在对账阶段爆炸。凡是 ID 类字段，我在 Schema 里一律写成字符串类型，宁可牺牲一点类型纯洁性。

重复键。JSON 规范对同名键的处理是"未定义行为"，不同解析器的选择不一样。有的取最后一个，有的取第一个，有的报错。我遇到过接口返回里status出现了两次，值还不一样，本地环境取到的是后一个，线上某个中间层软件取的是前一个，排查了两天才定位到。Schema 校验拦不住这个，因为它是解析阶段的问题，解析完之后重复的键已经消失了。防御方式是在语法校验阶段加一道正则扫描，或者用能保留重复键的解析模式做检查。

null 和缺失字段混淆。前面提过一次，这里再强调。写校验规则时，required只检查键是否存在，不检查值是否为 null。如果你要的是"必须有值"，需要写成"required": ["payTime"]加上"properties": {"payTime": {"type": "string"}}，两个条件组合才能排除 null。很多人只写了 required，结果 null 大摇大摆通过。

日期格式不统一。同一个系统里，有的接口返回时间戳（毫秒整数），有的返回 ISO 字符串，有的返回2024-05-12 10:30:00这种自定义格式。格式化之后看着都正常，一旦做时间比较就开始出问题。Schema 里可以限定格式，但不同方言对 format 的支持程度不一，实际校验时经常被忽略，得自己写正则兜底。

转义层级叠加。有些接口会把一段 JSON 字符串作为另一个 JSON 的字段值，形成双重转义。格式化一次只能解开外层，里层还是一长串带反斜杠的字符串。处理方式是单独把那个字段取出来再格式化一次：

# 取出被嵌套的字符串字段，再格式化一次 jq -r '.data.payload' resp.json | python3 -m json.tool --no-ensure-ascii

数组和对象的类型摇摆。有些接口在"只有一条记录"时返回对象，在"多条记录"时返回数组，导致下游代码必须写两套分支。这种设计问题靠校验脚本能提前发现：在 Schema 里把字段类型写死成数组，跑一次历史响应就能看出哪些场景不符合。

6.3 团队协作里值得定下来的几条小规矩

最后说几条跟技术无关、但影响效率的约定。

缩进统一两空格。不是为了好看，是为了 diff 的时候不产生假差异。团队里有人用四空格、有人用 Tab，做响应比对时满屏都是缩进改动，真正的差异被埋在里面。

Schema 放代码仓库，跟接口一起走。别放在某个人的本地目录里，也别放在文档系统里靠手动同步。接口改了 Schema 跟着改，Code Review 的时候一起看，这样才不会出现"文档说有三个字段、实际返回四个"的情况。

校验失败信息要说人话。我见过校验脚本只输出一句"校验失败"，等于没输出。至少要带上字段路径、期望值、实际值三项，让人一眼能定位。这点投入非常值得，因为校验脚本是给全团队用的，不是你一个人的工具。

原始响应一律保留到问题关闭。清理临时文件的时候注意别把证据删了。我的一般做法是按日期建目录，问题解决后统一清理，中间不动。

这几个约定看起来都是小事，但一个团队如果连缩进都不统一，说明没人认真对待过接口调试这件事。反过来，如果这些细节都到位了，说明这个团队对接质量是有底线的。

7. 一些踩过坑之后的个人做法

我不太喜欢给调试流程定什么"最佳实践"，因为每个团队的接口形态差异太大。但有三个习惯是我踩了足够多坑之后固定下来的，说出来供参考。

第一，拿到任何一段 JSON，先存再动。这个动作花不了两秒，但能救你于无数次"改坏了想回退"的窘境。文件名带上时间、环境和关键参数，一个月后再翻出来还能看懂。

第二，把所有超过 15 位的数字字段当成字符串处理，别管接口文档上写的是什么类型。文档可能没错，但中间经过的每一层都可能悄悄改了它，你控制不了。

第三，格式化和校验别指望一次搞定，先语法、再结构、最后语义，一层一层来。我见过太多人一上来就写一堆业务规则校验，结果脚本本身因为 JSON 语法错误跑不起来，白白折腾半天。

这套动作跑顺之后，看一个陌生接口的响应，从打开到判断"这个数据能不能用"，通常不超过两分钟。省下来的时间，够你把接口文档好好写一遍——而这恰恰是下一个接手的人最需要的东西。