JSON 格式化工具

JSON 是 JavaScript 对象字面量所允许语法的一个严格子集,两者之间的差距正是大多数"无效 JSON"错误的来源。数组或对象最后一项后面的尾随逗号,在现代 JavaScript 里是合法的,但在 JSON 里是语法错误。单引号字符串在 JavaScript 里完全没问题,但会被 JSON 直接拒绝,因为 JSON 要求使用双引号。没加引号的对象键——写成 `{name: "value"}` 而不是 `{"name": "value"}`——是合法的 JavaScript 简写,却是无效的 JSON。这些都不是什么冷门的边界情况;它们正是从写 JavaScript 中养成的习惯,不知不觉产出了一份看起来像 JSON、实际上却不是的文档。

注释是另一个常见的困惑来源,因为很多看起来像 JSON 的配置文件格式——甚至一些故意使用的、JSON 衍生的格式——允许 `//` 或 `/* */` 注释,而 JSON 规范本身完全没有注释语法。把一个实际上包含注释的"JSON"配置文件复制进一个严格的解析器,会立刻失败,解决办法要么是去掉这些注释,要么是意识到这个文件从一开始用的就不是标准 JSON。

一个只报告"无效 JSON"却不说明位置的解析器,会逼着你用肉眼扫描整份文档,去找一个缺失的逗号或没转义的引号,这在超过几十行之后会变得相当繁琐。报告第一个问题的精确行号和列号,能把这种搜索变成一次直接的定位——错误描述的是一个具体字符,而不是一个笼统模糊的失败——这就是几秒钟修好一个大型 API 响应和花几分钟手动扫描之间的区别。

值得注意的是,错误提示指向的永远是解析器遇到的*第一个*问题,而不一定是文档里的每一个问题:一份有两处语法错误的文档只会报告第一处,修好之后可能要到下一次尝试才会发现第二处,因为一个已经无法理解文档结构的解析器,无法可靠地在它第一次感到困惑的位置之后继续寻找更多问题。

带有统一缩进和换行的美化 JSON,是为阅读它的人而存在的——调试一个 API 响应、审查一份配置文件、一眼看懂一个数据结构。这些结构对解析同一份 JSON 的程序来说毫无意义,这也是为什么压缩后的输出会剥离所有纯粹为了方便人类阅读而存在的字符:缩进、换行,以及任何不是用来分隔标记所必需的空白。两种形式代表的数据完全相同;不同的只是传输或存储它所需要的字节数,对于层层嵌套的结构来说,这个差异往往相当可观。

实用的规则很简单:在处理 JSON 的过程中——阅读、调试、手动编辑——保持格式化状态,而在它要发往任何按体积计费的地方之前——比如一个 HTTP 请求体、一个 URL 查询参数,或者一个有长度限制的环境变量——就把它压缩。