每位开发者都应了解的 JSON 格式化最佳实践

JSON 结构基础

JSON（JavaScript Object Notation，JavaScript 对象表示法）是一种用于表示结构化数据的轻量级文本格式。尽管名称如此，它与语言无关，广泛用于从 REST API 到配置文件的各种场景。有效的 JSON 文档要么是对象（用花括号包裹的键值对集合），要么是数组（用方括号包裹的有序列表）。

JSON 中的六种值类型是：字符串、数字、布尔值（true/false）、null、对象和数组。JSON 对象中的每个键必须是用双引号括起来的字符串——不能是单引号，也不能是不带引号的标识符。

常见语法错误

JSON 格式严格。单个语法错误就会导致整个文档无法解析。最常见的错误有：

• 尾随逗号：{"name": "Alice",}——最后一项后面的尾随逗号在 JSON 中是非法的（在 JavaScript 中是合法的，这会造成混淆）。
• 单引号字符串：JSON 要求使用双引号。{'key': 'value'} 不是有效的 JSON。
• 不带引号的键：{name: "Alice"} 是 JavaScript 对象字面量语法，而非 JSON。
• 注释：JSON 不支持注释。如果你需要在配置文件中写注释，考虑使用 JSONC 或 YAML。
• Undefined 和 NaN：这些 JavaScript 值在 JSON 中不存在。使用 null 或省略该字段。
• 未转义的控制字符：字符串内的换行符必须写成 \n，而不是字面上的换行符。

格式化以提高可读性

通过网络发送的 JSON 通常是压缩的——去除空白字符——以减少载荷大小。但存储在配置文件中或提交到版本控制系统的 JSON 应格式化以便人类阅读。标准约定如下：

• 每个缩进级别使用两个或四个空格（选一种并保持一致）
• 对象中每行一个键值对
• 开括号与父键在同一行，闭括号单独一行
• 简单值的数组如果较短可以写在一行

大多数编辑器可以自动格式化 JSON。在 VS Code 中，右键单击并选择"格式化文档"，或使用快捷键 Shift+Alt+F。命令行用户可以使用 jq . input.json 来美化输出任何 JSON 文件。

命名约定

JSON 本身不强制命名约定，但你的 API 或代码库应选择一种并坚持使用。三种常见模式是：

• 驼峰式（firstName）——JavaScript API 和大多数 REST 服务的标准
• 下划线式（first_name）——Python API 和 PostgreSQL 中常见
• 帕斯卡式（FirstName）——在某些 .NET 和 C# 环境中使用

在单个 API 中混用约定会造成混乱。如果你使用的 API 采用一种约定，而你的代码库使用另一种，请在专用的序列化层中处理转换，而不是在代码中到处进行临时转换。

处理 Null 与缺失字段

JSON 对象可以用两种方式表示值的缺失：键存在但值为 null，或键完全不存在。这两种情况语义不同。当字段被期望存在但没有值时（例如用户留空的中间名字段），使用 null。当字段根本不适用于该记录时，则省略该字段。在 API 内部确定一致的方法，以便使用者知道预期的行为。

大数值与精度

JSON 数字没有定义大小限制，但许多解析器将其反序列化为 IEEE 754 双精度浮点值。这意味着大于 2^53 的整数无法精确表示。如果你的 JSON 需要携带大整数（数据库 ID、以最小货币单位计的金融金额、加密标识符），请将它们表示为字符串并在 API 中记录这一点。这是 Twitter 推文 ID 的著名陷阱之一。

验证 JSON

除了语法验证（这是有效的 JSON 吗？）之外，JSON Schema 允许你定义文档的预期结构：哪些字段是必需的、它们的类型、值范围等。ajv（JavaScript）、jsonschema（Python）等工具和在线验证器可以根据 schema 检查 JSON 文档。对于你在生产环境中发布或使用的任何 API，在边界处实施 JSON Schema 验证是值得的。

JSON 格式化和验证工具——例如 TheDailyUtils 上的工具——是捕获不熟悉载荷中语法错误的最快方式。粘贴原始 JSON，你将立即看到它是否可以解析以及错误在哪里。

即时格式化和验证 JSON

打开免费 JSON 格式化工具——粘贴任何 JSON，在几秒内美化输出、压缩或捕获语法错误。在浏览器中运行，你的数据保持私密。