JSON 格式化与验证工具使用教程:语法、校验、Schema 与大文件处理

这篇回答什么

操作层的问题:怎么压缩与格式化、报错怎么定位、Schema 怎么当契约、大文件怎么处理、两版 JSON 怎么对比。JSON 的类型与语法规则本身,见 JSON 完全指南。

语法速查:只列真会踩的

语法细节不在这里展开,只留一张对照表。下表每一行的非法写法,都是实际排错时最常遇到的那几种:

写法 判定 原因
{"a": 1} ✅ 合法
{a: 1} ❌ 键名未加引号
{'a': 1} ❌ 单引号
{"a": 1,} ❌ 尾随逗号
{"a": 01} ❌ 前导零
{"a": NaN} ❌ JSON 无此字面量
{"a": undefined} ❌ 无此类型
[1, "2", null] ✅ 数组元素可混类型

中文内容还有一条表外的坑:文件开头带 BOM(\uFEFF),JSON.parse 会在 position 0 直接失败,而编辑器里完全看不出异常。

格式化与压缩:传输和阅读是两套

压缩(去掉全部缩进与换行)通常减少 30–50% 体积;键名重复度高时,配合 gzip/Brotli 差距会进一步拉大。线上响应、消息体、生产配置都该压缩;阅读、评审、排错时才展开。

不要用正则删空白——它会把字符串值内部的空格一起吃掉。用格式化工具里的压缩功能,语义不变,风险为零。

缩进风格本身没有对错:2 空格是 JS/TS 生态默认(Prettier、ESLint),4 空格常见于 Python/Java 项目;重要的是同一仓库内保持一致,不一致比选哪个更伤。

两个反直觉的注意点:

  • 先格式化再签名,验签必然失败。HMAC、数字签名、JWT 计算的是原始字节序列,多一个空格结果就完全不同。
  • 生产日志不要打印格式化后的大对象。应打印压缩版并按长度截断,否则写入耗时与日志配额一起失控。

校验:五类报错与定位

JSON.parse 抛出的多半只有一句 Unexpected token } in JSON at position 1234,看着毫无信息量。报错的分布其实是固定的:

错误类型 典型报错 真实原因
尾随逗号 Unexpected token } 对象/数组最后一项后多写了逗号
单引号 Unexpected token ' 从 JS 字面量复制过来
括号不闭合 Unexpected end of JSON input 少了 } 或 ],报在文件末尾
注释 Unexpected token / 手写了 // 说明
BOM 头 Unexpected token 在 position 0 文件以  开头

定位心法只有一句:报错位置往前看。解析器是在遇到「无法继续的字符」时才报错的,笔误通常在它前面几行。具体到症状:

  • 报在末尾 → 几乎一定是括号不闭合,从外往内数配对。
  • 指向逗号 → 通常是多写了尾随逗号,而不是少写内容。
  • 在 position 0 → 先查 BOM 和编码。
  • 在中间某行 → 看这一行的上一行末尾。

position 的真实语义(前缀导致整体偏移、0 起与编辑器列号 1 起的差)见 JSON.parse 报错详解。日常最快的一步仍是把原始内容粘进 JSON 格式化工具,多数实现会直接标出出错行列。

JSON Schema:契约,不是文档

验证「是不是合法 JSON」只解决语法;验证「字段对不对、类型对不对」要靠 Schema:

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "required": ["id", "email", "createdAt"],
  "additionalProperties": false,
  "properties": {
    "id": { "type": "string", "format": "uuid" },
    "email": { "type": "string", "format": "email" },
    "age": { "type": "integer", "minimum": 0, "maximum": 150 },
    "status": { "enum": ["active", "suspended", "deleted"] },
    "createdAt": { "type": "string", "format": "date-time" }
  }
}

生成出来的 Schema 只是宽松推断,要变成契约得人工做三件事:把确实必填的字段写进 required;给值域补约束(enum、format、minimum、minItems);把 additionalProperties 收紧,让未声明字段直接失败。

手写 Schema 容易和真实数据漂移,更稳的起点是拿一份真实响应生成初版(JSON Schema 生成工具),再逐项收紧。在 CI 里用 ajv 跑一遍,接口改动导致的结构破坏会在合并前暴露,而不是上线后变成 500。

大文件:内存是文本的 3–10 倍

最容易误判的一点:解析后内存占用通常是原始文本的 3–10 倍。每个键和值都会变成独立对象或字符串,附带指针与元数据开销。100MB 的 JSON,直接 JSON.parse 很可能需要 500MB–1GB 内存。

文件规模 建议做法
< 10 MB 直接 JSON.parse,不必优化
10–100 MB 流式解析,或按批次切片处理
> 100 MB 必须流式,且考虑换行分隔的 JSONL 格式
> 1 GB 改用列式/二进制格式(Parquet、Arrow)
库 语言 特点
simdjson C++ / 多语言绑定 利用 SIMD 指令,解析可达 GB/s 级
ijson Python 惰性迭代,边读边产出
JSONStream Node.js 按 JSONPath 增量抽取
serde_json StreamDeserializer Rust 零拷贝友好

只需要大文件里的某几个字段时,不必解析整棵树:用 JSONPath 表达式直接定位,边解析边丢弃无关分支。表达式可以对着真实数据在 JSONPath 查询工具 上调好再写进代码。

结构对比:改完到底变了什么

改配置、升级接口之后,肉眼比对两个 JSON 几乎必然漏掉东西。正确做法是对比解析后的结构而非文本行:

  • 键的增删 → 关注 required 与兼容性。
  • 值的变化 → 关注类型是否漂移("1" 与 1)。
  • 数组顺序变化 → 判断业务上是否有序语义。

JSON Diff 给的是结构化差异,比 diff 的文本行差异可靠——后者会被缩进和换行差异淹没。

安全:解析 JSON 的四个真实风险

风险 危害 修法
eval() / new Function() 解析 远程代码执行,直接沦陷 一律用 JSON.parse
原型链污染 深合并后篡改所有对象原型 合并前剔除 __proto__/constructor/prototype
深度嵌套爆栈 递归解析器栈溢出,服务拒绝 解析前做深度上限校验
大整数精度丢失 金额/订单号静默变成错误值 超过 2^53-1 的字段用字符串传输

第 2 条最隐蔽:JSON.parse('{"__proto__":{"isAdmin":true}}') 返回的是个普通对象,__proto__ 只是一个普通键,单纯取值无害;危险发生在深合并之后——

const payload = JSON.parse('{"__proto__":{"isAdmin":true}}');
const config = {};
merge(config, payload);           // 危险:污染 Object.prototype
console.log({}.isAdmin);          // true —— 全站对象都被改了

第 4 条在金融、订单类接口里最致命:9007199254740993 解析后变成 9007199254740992,且不会报错。

常见任务速查表

任务 做法 工具
读懂压缩成一行的 JSON 格式化(2 空格缩进) JSON 格式化
排查解析报错 粘进去看行列号 JSON 格式化
缩小传输体积 压缩去空白 JSON 压缩
折叠浏览深层结构 树形查看器 JSON 查看器
对比两版配置差异 结构化 diff JSON Diff
从响应反推 schema 自动生成 + 人工收紧 JSON Schema 生成
从大文件抽字段 JSONPath 表达式 JSONPath 查询
调试字段级正则 先验证 pattern 正则测试

可复现的实测结果

格式化工具的「验证」不是摆设:把非法输入逐个粘进 JSON 格式化工具,报错会带行号列号指出位置——与 Python 的 json.loads 报的位置一致,因为两者遵循同一个 JSON 规范。

工作流建议:粘贴 → 看报错 → 修正 → 格式化 → 再最小化。最后一步最小化用于确认「结构信息没有丢」:压缩前后用 JSON 对比 跑一遍,差集为空才说明你只改了格式。

常见问题

JSON 字符串到底能不能用单引号?

不能。JSON 规范要求键名和字符串值必须用双引号包裹,单引号、反引号或不加引号都不合法。这是从 JavaScript 对象字面量迁移过来时最常见的错误——{ name: 'Alice' } 在 JS 里是合法对象,但作为 JSON 解析时会直接抛错。同理,末尾不能有多余逗号:{ "a": 1, } 在 JS 里合法,在 JSON 里非法。JSON 也不是 YAML:不要因为 YAML 支持注释就往 JSON 里写 // 或 /* */,标准 JSON 解析器一律报错。

JSON 解析失败了,报错只给一个行列号,怎么快速定位?

从报错位置往前看,而不是往后。 解析器在遇到第一个无法继续的字符时才报错,而真正的笔误通常在它前面几行。实战步骤:① 把原始字符串丢进 [JSON 格式化工具](/json-formatter.html),多数工具会直接标出出错行列;② 若报错在文件末尾,几乎一定是括号不闭合,从外往内数一遍 {} 与 [] 的配对;③ 报错指向某个逗号,通常是多写了一个尾随逗号,而不是少写了内容;④ 中文场景额外检查:文件是否带 BOM(\uFEFF 开头会让 JSON.parse 直接失败)、编码是否 UTF-8。

什么时候该压缩 JSON,什么时候该格式化?

传输用压缩,人读用格式化,两者不要混。 线上的 API 响应、配置文件、消息体都应该压缩(去掉所有缩进与换行),实测能减少 30–50% 体积;本地调试、代码评审、日志排查时再格式化。两个容易被忽略的点:① 不要格式化后再做签名——数字签名、HMAC、JWT 的计算对象是原始字节,格式化会改变字节序列导致验签失败;② 生产日志里直接打印格式化后的大对象会显著拖慢写入、撑爆日志配额,应打印压缩版并按长度截断。压完之后想确认没改坏语义,可以用 [JSON Diff](/json-diff.html) 对比压缩前后解析出的结构是否一致。

解析不可信来源的 JSON 有哪些真实安全风险?

四个,按危险程度排序:① 用 eval() 或 new Function() 解析——等于把对方的字符串当代码执行,可直接沦陷,必须永远用 JSON.parse;② 原型链污染——JSON.parse('{"__proto__":{"isAdmin":true}}') 会得到一个带 __proto__ 键的普通对象,一旦被深合并(Object.assign、lodash merge)进配置,就可能篡改所有对象的原型,修法是合并前过滤 __proto__/constructor/prototype 三个键;③ 深度嵌套导致栈溢出——恶意构造十万层 [[[[...]]]] 会让递归解析器爆栈,应对外层做深度上限校验;④ 超大数字精度丢失——JSON.parse 会把超过 Number.MAX_SAFE_INTEGER 的整数转成浮点数,金额、订单号这类字段必须用字符串传输。

← 返回博客首页