如何在线格式化和校验 JSON
如果您使用API、配置文件或任何类型的结构化数据,您会定期处理JSON。如果您曾经盯着一堆缩小的JSON试图找到缺失的括号,您就知道为什么格式化很重要。基于浏览器的格式化工具在本地处理整个工作,而无需将您的数据上传到服务器。
JSON格式化的作用
来自API响应或缩小文件的原始JSON看起来像这样:
{"users":[{"name":"Alice","age":30,"roles":["admin","editor"]},{"name":"Bob","age":25,"roles":["viewer"]}]}
格式化工具将其转换为可读的内容:
{
"users": [
{
"name": "Alice",
"age": 30,
"roles": ["admin", "editor"]
},
{
"name": "Bob",
"age": 25,
"roles": ["viewer"]
}
]
}
相同的数据,但现在您可以真正阅读、发现错误并理解结构。
如何在线格式化JSON
- 粘贴您的JSON到输入字段。格式化工具会立即检测语法错误并验证结构。
- 选择缩进:选择2或4个空格,或点击「缩小」将JSON压缩为单行。
- 复制结果:格式化的输出包括彩色语法高亮。复制它以在您的代码、配置文件或文档中使用。
JSON的简史
JSON(JavaScript对象表示法)由Douglas Crockford于2001年规定,于RFC 4627(2006)中正式记录,并于2013年标准化为ECMA-404,于2017年标准化为ISO/IEC 21778。Crockford没有发明JSON:他从已经在使用的JavaScript对象字面语法的子集中提取了它,并给它一个名称加上json.org上的单页规范。
JSON迅速取代了XML作为Web API的标准,因为它简单得多。XML响应使用开放/关闭标签很冗长;等效的JSON是其一半大小。浏览器可以原生解析JSON(自2009年ECMAScript 5起使用JSON.parse、JSON.stringify),无需XML解析器。
到2015年,世界上每个主要API都说JSON:REST API、GraphQL查询、WebSocket消息、配置文件(package.json、tsconfig.json、.vscode/settings.json),甚至数据库(PostgreSQL JSONB、类似JSON的MongoDB BSON)。它成为了Web上结构化数据的通用语言。
JSON的简单性也是其限制:没有注释、没有尾随逗号、没有日期类型、没有二进制支持。出现了几个JSON变体来解决这些差距(请参阅下面的「JSON类替代格式」)。
常见JSON错误以及如何发现它们
大多数JSON错误归结为一些常见错误:
- 缺失或多余的逗号:数组或对象中最后一项之后的逗号在JSON中是无效的(与JavaScript不同)
- 未引用的键:JSON要求所有键周围有双引号:
"name"而不是name - 单引号:JSON只接受双引号:
"value"而不是'value' - 尾随逗号:
{"a": 1,}无效;删除最后一个条目后的逗号 - 注释:JSON不支持
// 行或/* 块 */注释;大多数解析器拒绝它们 - Undefined / NaN / Infinity:JSON只允许数字、字符串、布尔值、null、数组和对象。JavaScript值如
undefined、NaN或Infinity无效 - 函数值:函数引用不能出现在JSON中
- 十六进制或八进制数:只有十进制数有效(
0xFF和0o17不是) - 前导零:
01在JSON中无效;使用1 - 十六进制转义:字符串中只允许
\uUnicode转义,不允许\x或\0 - 重复键:技术上符合规范,但大多数解析器静默使用最后一个值;依赖此行为风险自担
- UTF-8 BOM:文件开头的字节顺序标记不是有效的JSON,会破坏严格的解析器
- 尾随空格或内容:闭合
]或}之后的任何文本使文档无效
一个好的格式化工具会准确突出显示错误位置,以便您可以立即修复它,而不是猜测。
JSON数据类型
JSON只有6种数据类型:
| 类型 | 示例 | 备注 |
|---|---|---|
| 字符串 | "hello" | 始终为双引号,支持\n、\t、\\、\"、\uXXXX |
| 数字 | 42、3.14、-1e10 | 没有NaN或Infinity,没有前导零 |
| 布尔值 | true、false | 仅小写 |
| null | null | 仅小写 |
| 数组 | [1, 2, 3] | 有序,任何类型,逗号分隔 |
| 对象 | {"key": "value"} | 键必须是带引号的字符串,逗号分隔 |
明显缺失:日期(使用ISO 8601字符串)、二进制数据(使用Base64字符串)、注释(使用单独的文档字段)和bigint(JSON数字是双精度;值>= 2^53会丢失精度)。
何时格式化与缩小
格式化(漂亮打印)当您需要:
- 阅读和理解数据
- 调试API响应
- 编辑配置文件
- 与同事共享JSON
- 提交到版本控制(更干净的差异)
缩小当您需要:
- 通过网络发送数据(更小的负载=更快的传输)
- 将JSON存储在可读性不重要的数据库或日志中
- 将JSON嵌入URL参数或表单字段
- 生成紧凑的API响应
大小差异很显著:典型的50 KB漂亮打印的JSON缩小为约30 KB。对于高流量API,缩小的响应节省带宽。对于人类编辑的文件,格式化是必不可少的。
JSON类替代格式
当JSON的严格性是个问题时,几种变体放松了规则:
| 格式 | 在JSON之上添加 | 最佳用途 |
|---|---|---|
| JSON5 | 注释、尾随逗号、单引号、未引用的键 | 人类编辑的配置文件 |
| JSONC | 仅注释(// 和 /* */) | VS Code设置,tsconfig.json |
| HJSON | 注释、未引用的字符串、多行字符串 | 人类友好的配置 |
| JSON Lines(NDJSON) | 每行一个JSON对象,没有外层数组 | 日志文件、流式传输 |
| YAML | 基于缩进、注释、锚点、引用 | Kubernetes、GitHub Actions |
| TOML | 类似INI的语法、日期、注释 | Cargo.toml、pyproject.toml |
| BSON | 带有额外类型(Date、ObjectId、Binary)的二进制JSON | MongoDB内部存储 |
| CBOR(RFC 8949) | 针对大小优化的二进制格式 | 受约束设备API |
| MessagePack | 类似JSON的二进制,紧凑 | 内部API序列化 |
对于数据交换(API响应、配置),坚持严格的JSON。对于人类编辑的配置,JSON5或JSONC更友好。对于数据流式传输,NDJSON是事实标准。
常见陷阱
- 数字失去精度:JSON数字是IEEE 754双精度。大于2^53(9,007,199,254,740,992)的整数会丢失精度。将大ID作为字符串传输(
"id": "12345678901234567890")。 - 编辑器破坏Unicode转义:某些编辑器在保存时自动转换字符,这可能导致解析器行为意外。在所有地方使用UTF-8。
- 错误漂亮打印日期:日期作为ISO 8601字符串(
"2026-05-20T13:00:00Z")是标准的。避免将Unix时间戳作为字符串;它们看起来像数字,但通常意图是日期。 - 键中的空格:
{"first name": "..."}是有效的JSON,但会破坏许多期望标识符安全键的ORM和代码生成器。 - 空值与缺失键:
{"a": null}和{}(完全没有a)是不同的事情。选择一种约定并记录下来。 - Bigint不匹配:序列化为JSON数字的PostgreSQL bigint列可能会丢失精度。对2^53以上的ID使用字符串。
- 尾随换行:某些工具在闭合括号后添加尾随换行;某些严格解析器拒绝它。JSON-stringify不产生尾随换行。
- 编码不匹配:JSON规范要求UTF-8(或带BOM的UTF-16/UTF-32)。Latin-1中的非ASCII字符会失败。始终序列化为UTF-8。
- JSON中的字符串化JSON:嵌套转义字符很快变得难以处理。要么直接嵌套对象,要么选择base64编码的JSON约定。
- 源文件中的注释:如果您将JSONC或JSON5提交到期望严格JSON的系统,解析将失败。在构建步骤中转换为严格的JSON。
使用JSON的提示
- 发送前验证:如果您正在手动构建API请求,请先将您的JSON粘贴到验证器中。一个错位的逗号可能会在服务器端导致混乱的错误。
- 对深度嵌套数据使用2空格缩进。它使行更短,结构更易扫描。
- 书签该工具:如果您经常使用JSON,有一个一键可达的格式化工具与每次搜索一个相比节省时间。
- 使用jq进行命令行工作:
jq(以及jq语言替代品如gron、dasel、yq)对于在命令行中过滤和转换JSON至关重要。 - 使用JSON模式进行验证:对于重要的格式(API契约、配置文件),定义JSON模式并对其进行验证。诸如ajv(JavaScript)、python-jsonschema或VS Code的内置模式验证之类的工具可以防止形状错误。
- 使用Postman或Insomnia进行API请求:这些工具具有内置的JSON格式化工具和验证器、语法高亮和请求历史记录。
- 在代码库中通过prettier运行JSON:Prettier一致地格式化JSON;将其集成为预提交挂钩,这样格式化就永远不是代码审查的关注点。
- 对于差异,先排序键:JSON对象键是无序的。
{"a":1,"b":2}与{"b":2,"a":1}的差异显示一切都更改了,除非您先排序键。使用jq -S或类似工具。
隐私和机密JSON
JSON格式化工具完全在您的浏览器中运行。您粘贴的JSON、中间处理和格式化的输出都保留在您的设备上。没有任何内容上传到服务器、记录或与任何人共享。
这很重要,因为JSON通常包含极其敏感的数据:带有客户记录和电子邮件地址的API响应、身份验证令牌和会话数据、揭示产品架构的内部API模式、带有数据库密码的配置文件、来自会计API的财务数据、来自FHIR API的医疗记录、来自HR API的内部公司结构、揭示基础设施的带有堆栈跟踪的调试有效负载。云JSON格式化工具记录其请求日志中的每次粘贴,有时为「服务改进」保留它们,并参与了真正的事件,其中粘贴的API响应泄漏了客户数据和API密钥。基于浏览器的格式化工具没有任何暴露:JSON永远不会离开您的机器。
基于浏览器的格式化在页面加载后也可以离线工作,对于在飞机上、在没有互联网访问的安全环境中,或在任何您不能或不应将API数据(尤其是带有嵌入式凭据)粘贴到第三方服务的地方格式化JSON很有用。
常见问题
格式化器能处理大型 JSON 文件吗？
可以。由于工具在浏览器中运行，它可以处理数万行的文件。性能取决于您的设备，但大多数现代浏览器处理大型 JSON 都没问题。
它能离线工作吗？
可以。页面加载后，工具完全在您的浏览器中工作，无需联网。所有处理都通过 JavaScript 本地完成。
格式化和校验有什么区别？
格式化添加缩进和换行，让 JSON 可读。校验检查 JSON 结构是否正确 · 大括号是否平衡、引号是否正确、类型是否有效。大多数格式化器同时做两者。
可以在手机上使用吗？
可以。工具在任何带现代浏览器的设备上都能使用，包括手机和平板。