JSON格式化最佳实践

JSON（JavaScript对象表示法）已成为Web上数据交换的事实标准。API返回JSON，配置文件使用JSON，甚至数据库也存储JSON文档。尽管JSON很简单，但它有严格的语法规则，很容易违反，格式不当的JSON会导致调试困难、性能问题和安全漏洞。本指南涵盖了关于正确格式化JSON你需要了解的一切，从基本语法到Schema验证和处理大型文件等高级主题。

什么是JSON？

JSON是一种轻量级的、基于文本的数据交换格式，源自JavaScript对象字面量语法。它由Douglas Crockford在2000年代初指定，并标准化为ECMA-404和RFC 8259。JSON的设计目标是简单性、人类可读性和跨编程语言的易实现性。如今，每种主要编程语言都包含内置的JSON支持。

JSON支持六种数据类型：字符串（双引号）、数字（整数和浮点数）、布尔值（true和false）、null值、对象（无序键值集合）和数组（有序列表）。它原生不支持注释、日期、二进制数据或undefined值。

JSON语法规则

JSON有必须严格遵循的语法。即使一个字符错误也会导致整个文档解析失败。理解这些规则可以防止最常见的格式化错误。

字符串必须使用双引号

所有字符串值和对象键必须用双引号括起来。单引号不是有效的JSON字符串分隔符。这是从JavaScript转来的开发者最常见的错误之一，在JavaScript中单引号和双引号可以互换使用。

// Invalid - single quotes
{'name': 'Alice', 'age': 30}

// Valid - double quotes
{"name": "Alice", "age": 30}

对象键必须加引号

与JavaScript对象字面量不同，JSON要求所有对象键都用双引号括起来。未加引号的键是语法错误。

// Invalid - unquoted keys
{name: "Alice", age: 30}

// Valid - quoted keys
{"name": "Alice", "age": 30}

禁止尾随逗号

JSON不允许在对象或数组的最后一项后加逗号。这是JavaScript开发者的另一个常见错误，在JavaScript中尾随逗号是允许的（在某些风格指南中甚至被鼓励）。

// Invalid - trailing comma
{
  "name": "Alice",
  "age": 30,
}

// Valid - no trailing comma
{
  "name": "Alice",
  "age": 30
}

不支持注释

JSON不支持注释。//单行注释和/* */多行注释在JSON中都无效。如果你需要包含文档，考虑使用单独的文档文件或某些工具支持的JSONC（带注释的JSON）格式。

严格的值类型

JSON值必须是六种支持类型之一。undefined、NaN、Infinity和-Infinity不是有效的JSON值。包含其中任何一个都会导致解析错误或产生许多解析器会拒绝的非标准JSON。

常见格式化错误

除了语法错误，还有几种格式化错误会产生技术上有效但有问题的JSON：

• 不一致的缩进：混合使用制表符和空格，或使用不同的缩进深度，使JSON在代码审查和差异比较中更难阅读。标准化使用2空格缩进，这是最常见的约定。
• 深层嵌套结构：超过4-5层嵌套的JSON变得难以阅读和调试。考虑扁平化结构或将其拆分为单独的文档。
• 不一致的键顺序：虽然JSON对象在技术上是无需的，但保持一致的键顺序（如按字母顺序或按重要性）使差异比较更有意义，并减少版本控制中的合并冲突。
• 过长的行：单行上有许多项的数组难以浏览。将长数组分成多行，每行一项以提高可读性。
• 缺失或不一致的null处理：决定是完全省略null值还是显式包含它们，并在整个API中一致地应用该决定。

美化打印与压缩

JSON的两种主要格式化模式服务于不同目的，在正确的上下文中使用正确的格式很重要。

美化打印的JSON

美化打印添加缩进和换行符使JSON对人类可读。这在开发、调试和文档编写期间至关重要。大多数JSON格式化器默认使用2空格缩进：

{
  "users": [
    {
      "id": 1,
      "name": "Alice",
      "email": "alice@example.com"
    },
    {
      "id": 2,
      "name": "Bob",
      "email": "bob@example.com"
    }
  ]
}

压缩的JSON

压缩移除所有不必要的空白，产生尽可能小的有效JSON。这对于每个字节都很重要的生产API至关重要：

{"users":[{"id":1,"name":"Alice","email":"alice@example.com"},{"id":2,"name":"Bob","email":"bob@example.com"}]}

何时使用哪种

JSON Schema验证

虽然JSON语法验证检查文档是否格式良好，但它不验证数据是否具有预期的结构、类型或值。JSON Schema通过提供描述JSON数据预期形状的词汇来填补这一空白。

什么是JSON Schema？

JSON Schema是一个描述其他JSON文档结构的JSON文档。它让你可以指定必填字段、预期类型、值范围、字符串模式和嵌套对象结构。符合Schema的JSON文档称为有效实例。

常见Schema功能

• 类型检查：确保字段是字符串、数字、布尔值、对象或数组。
• 必填字段：指定哪些属性必须存在。
• 字符串验证：强制模式（正则表达式）、最小/最大长度和格式（电子邮件、日期时间、URI）。
• 数字验证：设置最小值、最大值、排他边界和倍数约束。
• 数组验证：控制项类型、最小/最大项数和唯一性。
• 组合：使用allOf、anyOf、oneOf和not进行复杂验证逻辑。

何时使用Schema验证

每当你从外部来源接收JSON时都应使用JSON Schema验证：API请求体、配置文件、数据导入和消息队列负载。Schema验证可以及早捕获错误，提供清晰的错误消息，并作为数据格式的活文档。像Ajv（JavaScript）、jsonschema（Python）和json-schema-validator（Java）等库使得将Schema验证集成到任何应用中变得简单。

JSON大小的性能影响

JSON文档的大小直接影响应用性能，体现在多个方面：网络传输时间、解析时间和内存消耗。理解这些影响有助于你对JSON格式化和结构做出明智的决策。

网络传输

JSON的每个字节都必须通过网络从服务器传输到客户端。在快速连接上，10KB和100KB之间的差异可能看似微不足道，但在移动网络或互联网较慢地区的用户看来，影响是显著的。研究表明，每增加100ms的加载时间会降低约1%的转化率。压缩通常将JSON大小减少30-50%，gzip压缩额外减少70-85%。始终为JSON API响应启用gzip或Brotli压缩。

解析性能

JSON解析的代价惊人地高。对于大型文档（超过1MB），在移动设备上解析可能需要数百毫秒。成本大致与文档大小成线性关系。减少解析成本的关键策略包括：仅发送客户端需要的数据（字段过滤）、对大型结果集进行分页，以及在不需要人类可读性的内部服务间通信中使用更高效的序列化格式如Protocol Buffers或MessagePack。

内存使用

解析后的JSON通常消耗比其序列化形式多3-10倍的内存，因为每个值成为具有自己内存分配的独立对象。1MB的JSON字符串解析后可能使用5-10MB的RAM。对于在内存有限的浏览器中运行的JavaScript应用，这可能导致低端设备上的性能下降或崩溃。

JSON与JSONL

JSON Lines（JSONL或NDJSON）是一种相关格式，解决了JSON的一个关键限制：要求将整个文档作为单个单元解析。在JSONL中，文件的每一行都是一个完整的、独立的JSON对象。

何时使用JSONL

• 日志文件：每条日志记录是独立一行上的自包含JSON对象。你可以追加新记录而无需修改现有数据，也可以独立读取任何一行。
• 数据流：在记录到达时处理，无需等待完整数据集。每行是一条完整的消息。
• 大型数据集：逐条解析和处理记录，无需将整个文件加载到内存中。这对于超过可用RAM的数据集至关重要。
• 并行处理：在行边界处分割JSONL文件并将块分发给不同的工作线程。这对于标准JSON是不可能的，因为在任意字节位置分割会破坏结构。

何时坚持使用标准JSON

• API响应：标准JSON是REST API的预期格式。将结果包装在数组或对象中是常规和预期的做法。
• 配置文件：配置通常需要一次性加载，因此JSONL的流式优势无关紧要。
• 嵌套数据结构：如果你的数据具有无法轻松扁平化为单独记录的复杂嵌套，标准JSON更自然。

处理大型JSON文件

大型JSON文件（超过10MB）提出了需要特殊处理的独特挑战。标准解析方法在这种规模下可能失败或性能不佳。

流式解析器

流式（或SAX风格）解析器增量处理JSON，无需将整个文档加载到内存中。它们在遇到结构元素（如对象开始、键值对和数组项）时发出事件。这种方法无论文件大小如何都使用恒定内存。像oboe.js（JavaScript）、ijson（Python）和Jackson Streaming API（Java）等库提供流式JSON解析。

大文件的实用技巧

• 先转换为JSONL：如果你有一个大型JSON数组，将其转换为JSONL（每行一个对象）可以使用grep、awk和jq等标准工具进行逐行处理。
• 使用命令行工具：jq是从命令行处理JSON的标准工具。它可以高效处理大文件，并支持超大型输入的流式模式。
• 分割和并行化：将大型JSONL文件分割成更小的块并并行处理。每个块可以独立处理，因为每行是自包含的。
• 避免加载到内存：永远不要对大于可用内存的文件使用JSON.parse()。使用流式解析器或逐行处理文件。
• 压缩存储：大型JSON文件使用gzip压缩效果极好（通常减少80-90%）。保留压缩副本用于存储，在处理期间即时解压缩。

JSON安全注意事项

虽然JSON是一种数据格式且本身并非不安全，但应用处理JSON的方式可能引入漏洞。理解这些风险对于构建安全系统至关重要。

永远不要使用eval()解析JSON

最关键的安全规则：永远不要使用JavaScript的eval()函数来解析JSON。eval()执行任意JavaScript代码，这意味着恶意JSON负载可以在用户机器上运行代码。始终使用JSON.parse()，它只解析有效的JSON并拒绝任何可执行代码。这是不可商量的。

JSONP和跨域风险

JSONP（带填充的JSON）是在CORS被广泛支持之前绕过同源策略限制的一种技术。它通过将JSON数据包装在作为脚本执行的函数调用中来工作。这本质上是危险的，因为它执行来自第三方服务器的任意JavaScript。如果你同时控制客户端和服务器，请使用CORS而非JSONP。JSONP应被视为遗留技术，在新应用中应避免使用。

原型污染

在JavaScript中合并或深拷贝JSON对象时，要警惕__proto__、constructor和prototype等键。如果用户提供的JSON在未清理这些键的情况下被递归合并到现有对象中，它可以修改应用中所有对象的原型，导致权限提升或拒绝服务。合并前始终清理对象键。

通过深度嵌套的拒绝服务

精心构造的具有极端嵌套深度（数千层）的JSON文档可能导致递归解析器中的堆栈溢出错误。通过在解析器中设置最大嵌套深度来缓解此问题。大多数生产JSON解析器允许你配置此限制。

输入验证

永远不要信任来自外部来源的JSON数据。在使用之前始终验证传入JSON的结构、类型和值范围。JSON Schema验证是最稳健的方法，但即使是对必填字段和类型断言的简单检查也能对格式错误或恶意输入提供显著保护。