JSON 格式化与验证：开发者快速参考指南

Code on screen

JSON（JavaScript Object Notation）是 Web API 的通用语言。其设计简洁——但一个缺失的逗号或不匹配的花括号就可能悄无声息地导致应用程序崩溃。以下是自信使用 JSON 所需了解的一切。

90 秒掌握 JSON 语法

JSON 只有六种值类型：

{
  "string": "hello world",
  "number": 42,
  "boolean": true,
  "null_value": null,
  "array": [1, 2, 3],
  "object": { "nested": "value" }
}

容易踩坑的规则：

键名必须是双引号字符串 — {name: "Alice"} 不是有效的 JSON
不允许尾随逗号 — [1, 2, 3,] 是无效的
不支持注释 — JSON 没有 // 或 /* */ 语法
字符串必须使用双引号 — 不允许使用单引号
数字不能有前导零 — 007 是无效的

最常见的 JSON 错误

1. 尾随逗号

// Invalid
{ "a": 1, "b": 2, }

// Valid
{ "a": 1, "b": 2 }

2. 单引号字符串

// Invalid
{ 'name': 'Alice' }

// Valid
{ "name": "Alice" }

3. 未加引号的键名

// Invalid
{ name: "Alice" }

// Valid
{ "name": "Alice" }

4. Undefined 或 NaN 值 — 这些 JavaScript 值在 JSON 中不存在。请改用 null。

格式化与压缩

美化输出的 JSON（格式化）使用缩进和换行提升可读性：

{
  "user": {
    "id": 1,
    "name": "Alice"
  }
}

压缩后的 JSON 去除所有空白字符：

{"user":{"id":1,"name":"Alice"}}

在配置文件和源代码中使用格式化 JSON；在 API 响应和存储中使用压缩 JSON 以减小数据体积。我们的 JSON Formatter 一键切换两种模式。

JSON Schema 验证

JSON Schema 允许您定义 JSON 文档的预期结构，并据此验证数据。这对于 API 契约和配置文件验证至关重要。

一个简单的 schema 示例：

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "required": ["name", "age"],
  "properties": {
    "name": { "type": "string" },
    "age": { "type": "integer", "minimum": 0 }
  }
}

此 schema 会拒绝任何缺少 name 或 age 字段、或 age 为负数的对象。JSON Schema Validator 支持粘贴 schema 和数据进行实时验证。

从 JSON 生成 TypeScript 类型

如果您收到来自 API 的 JSON 响应并需要 TypeScript 接口，可将 JSON 粘贴到我们的 JSON to TypeScript 转换工具中。它会从数据结构推断类型：

输入：

{ "id": 1, "name": "Alice", "active": true, "tags": ["admin"] }

输出：

interface Root {
  id: number;
  name: string;
  active: boolean;
  tags: string[];
}

JSONPath：查询嵌套数据

JSONPath 之于 JSON，正如 XPath 之于 XML——是一种从嵌套结构中提取值的查询语言。基本语法：

表达式	含义
`$.store.book`	`store` 内的 `book` 键
`$.store.book[0]`	第一本书
`$.store.book[*].title`	所有书籍的标题
`$..price`	文档中任意位置的所有 `price` 值

JSON Path Finder 支持点击渲染后的 JSON 树中的任意值，并自动复制其路径。

比较两个 JSON 对象

在调试 API 变更或配置偏差时，您需要查看两个 JSON 对象之间的差异。JSON Diff Viewer 可并排高亮显示新增、删除和修改的字段。

将 JSON 转换为 Zod schema

如果您在 TypeScript 中使用 Zod 进行运行时验证，JSON to Zod 工具可将示例 JSON 转换为开箱即用的 Zod schema，并对 email、URL 和 datetime 字段进行智能类型推断。

总结

JSON 简单却不容出错。在解析前务必进行验证，使用 TypeScript 接口在编译时捕获结构不匹配问题，并随时准备好格式化工具用于调试 API 响应。养成这些习惯，可以从根本上杜绝整类运行时 Bug。