JSON

是什么，为什么存在

JSON 是 JavaScript Object Notation 的缩写。它是一种数据交换语法，不是 JavaScript 对象，也不是带方法的运行时值。符合 JSON 语法的一段 Unicode 文本称为 JSON 文本（JSON text） ，它可以表示对象、数组、字符串、数字、布尔值或 null。

JSON 解决的是系统边界上的表示问题。内存中的对象不能直接穿过 HTTP、消息队列、文件或 Web Storage；把数据变成文本后，不同语言和进程就能按同一套语法交换它。把运行时值转换为这种表示的过程称为 序列化（serialization） ，反方向通常称为解析或反序列化。

你会在 API 响应、请求正文、配置文件、缓存项和日志中遇到 JSON。JavaScript 提供全局 JSON 对象，其中最常用的两个静态方法是 JSON.parse() 与 JSON.stringify()。它们只负责语法与值之间的转换，不会替你检查字段是否存在、字符串是否真是日期，或当前用户是否有权使用某个字段。

JSON 的数据模型有意保持很小。它没有 undefined、BigInt、Date、Map、Set、函数、Symbol、类实例、共享引用或循环引用。跨边界需要这些概念时，发送方与接收方必须先约定如何把它们表示成 JSON 支持的值。

工作原理

JSON 的两个方向可以看作一条边界管道。进入应用的数据先经过语法解析，再经过形状与业务验证；离开应用的数据先被投影成公开表示，再被序列化。

JSON 的语法与值模型

JSON 对象用花括号包围，成员名必须是双引号字符串。数组用方括号包围并保持元素顺序。对象与数组可以递归包含 JSON 支持的任意值，因此 JSON 表示的是一棵树。

字符串必须使用双引号，并用反斜杠转义双引号、反斜杠和控制字符。JSON 没有单引号字符串、注释或尾随逗号。成员名不能像 JavaScript 对象字面量那样省略引号。

JSON 数字支持十进制整数、小数和指数形式，但不支持 NaN、Infinity、-Infinity、BigInt 后缀 n、前导加号或十六进制写法。语法中的数字范围并不等于 JavaScript Number 能精确表示的范围；解析器最终仍会生成 Number。

顶层值不必是对象或数组。"ready"、42、false 与 null 都是完整的 JSON 文本。若接口只接受对象，必须在解析后单独检查，不能把“是有效 JSON”当作“是有效请求”。

对象成员名应当唯一。JSON.parse() 遇到重复成员名时保留后一个值，但其他实现的可观察行为未必适合互操作。生产者不应依赖重复成员覆盖来传达含义。

JSON.parse() 的处理过程

JSON.parse(text) 必须消费完整输入。语法无效时，它会抛出 SyntaxError，不会返回已经解析的前半段。语法有效时，它可以返回任意 JSON 值对应的 JavaScript 值，包括 null 与原始值。

可选的第二个参数是 恢复函数（reviver） 。解析器先构造普通 JavaScript 值，再从最深的子属性向根部调用恢复函数。回调接收字符串形式的 key 和当前 value；根调用的键是空字符串 ""。

在 Node 24 中，恢复函数处理原始值时还会收到第三个 context 参数，其 source 属性保存该值对应的原始 JSON 片段。处理对象或数组时没有这个上下文。这个信息可以在已经生成不精确 Number 后，从原始数字文本重建精确整数。

恢复函数的返回值会替换当前属性。返回 undefined 会删除对象属性；数组元素则变成空槽，而不是让后续元素前移。根调用返回 undefined 时，整个 JSON.parse() 的结果也是 undefined。

JSON.stringify() 的处理过程

JSON.stringify(value) 访问一个 JavaScript 值，并生成紧凑的 JSON 文本。第二个参数可以是 替换函数（replacer） 或属性名数组；第三个 space 参数控制缩进，数值最多按 10 个空格处理，字符串最多使用前 10 个字符。

对象若有 toJSON() 方法，序列化器会先调用它，再把结果交给替换函数。Date 正是通过 toJSON() 变成 ISO 字符串，所以普通替换函数看到的通常已经不是 Date 实例。自定义类中的 toJSON() 也会改变对外表示，应当把它当作 API 契约审查。

替换函数从一个键为 "" 的包装根开始，然后按序访问后代。它返回 undefined 时，对象属性会被省略；数组位置会写成 null。属性名数组则会在对象的每一层筛选成员，并不会只筛选顶层。

默认序列化行为不是对所有 JavaScript 值的一一映射：

普通对象只序列化自有、可枚举、字符串键属性。Symbol 键不会出现，继承属性也不会出现。数组按从 0 到 length - 1 的位置序列化；其他自有属性不会成为数组 JSON 的成员。

边界上的职责

解析、验证和授权是三个不同步骤。解析器回答“文本是否符合 JSON 语法”，形状验证回答“值是否具有预期字段与类型”，业务验证回答“这些值是否满足当前操作的规则”。授权还要根据身份与资源判断操作是否允许。

发送数据时也应先定义线格式。构造只包含公开字段的新对象，比把领域对象直接传给 JSON.stringify() 再按黑名单删除秘密更可靠。新增内部字段时，允许列表不会自动把它泄露到响应中。

JSON.parse(JSON.stringify(value)) 只对 JSON 数据模型内的树状值近似往返。它不是通用深拷贝，也不会恢复类实例、原型、属性描述符或共享引用。内存复制与跨系统序列化是两个不同问题。

示例

下面四个示例依次展示语法解析、形状验证、显式序列化和带来源文本的恢复。所有输出都来自 Node 24.14.0。

1. 解析完整 JSON 文本

第一次解析得到普通对象、数组、字符串、数字和布尔值。第二次输入使用单引号，因此不是 JSON；它看起来像某些语言的对象字面量，并不会让 JSON 解析器放宽语法。

只在能处理失败的边界捕获 SyntaxError。若调用方需要区分无正文、错误页和格式错误的 JSON，就应保留这些不同状态，而不是统一返回空对象。

2. 解析后验证形状

function parseOrder(source) {
  const value = JSON.parse(source);

  if (value === null || typeof value !== "object" || Array.isArray(value)) {
    throw new TypeError("order must be an object");
  }
  if (typeof value.orderId !== "string" || !Array.isArray(value.items)) {
    throw new TypeError("orderId and items are required");
  }
  if (!value.items.every((item) =>
    item !== null &&
    typeof item === "object" &&
    typeof item.sku === "string" &&
    Number.isInteger(item.quantity) &&
    item.quantity > 0
  )) {
    throw new TypeError("each item needs a SKU and positive quantity");
  }
  return value;
}

for (const source of [
  '{"orderId":"A-17","items":[{"sku":"PEN","quantity":2}]}',
  '{"orderId":"A-18","items":[{"sku":"PEN","quantity":0}]}',
  'null'
]) {
  try {
    console.log("accepted", parseOrder(source).orderId);
  } catch (error) {
    console.log("rejected", error.message);
  }
}

accepted A-17
rejected each item needs a SKU and positive quantity
rejected order must be an object

三个输入在语法上都有效，只有第一个满足订单契约。验证先排除 null 和数组，再读取对象属性，从而避免把 typeof null === "object" 误当作足够的对象检查。

真实边界通常使用经过审查的 schema 验证器，但验证顺序仍然相同：先解析不可信文本，再检查顶层类别、必需字段、嵌套结构与业务约束。不要通过 TypeScript 类型断言跳过运行时验证，因为类型在运行时不存在。

3. 构造公开表示后序列化

const invoice = {
  id: "INV-9",
  totalCents: 1250n,
  customer: { name: "Mira", passwordHash: "not-for-output" },
  exportedAt: new Date("2026-09-04T10:30:00.000Z")
};

// 先构造公开数据形状，比尝试用黑名单删除秘密更安全。
const publicInvoice = {
  id: invoice.id,
  totalCents: invoice.totalCents,
  customerName: invoice.customer.name,
  exportedAt: invoice.exportedAt
};

const json = JSON.stringify(
  publicInvoice,
  (key, value) => typeof value === "bigint" ? value.toString() : value,
  2
);

console.log(json);

{
  "id": "INV-9",
  "totalCents": "1250",
  "customerName": "Mira",
  "exportedAt": "2026-09-04T10:30:00.000Z"
}

公开对象按允许列表选择字段，所以 passwordHash 根本不会进入序列化器。替换函数把 BigInt 转成十进制字符串；接收方必须知道 totalCents 的字符串代表整数，而不是任意文本。

日期在替换函数运行前通过自己的 toJSON() 变成 ISO 字符串。若协议需要时区名称、日历日期或其他日期语义，就要把这些字段显式加入公开表示；一个 Date 本身只提供时间点。

4. 用恢复函数保留整数精度

const source = `{
  "orderId": "A-17",
  "placedAt": "2026-09-04T10:30:00.000Z",
  "transactionId": 9007199254740993
}`;

const order = JSON.parse(source, (key, value, context) => {
  if (key === "placedAt" && typeof value === "string") {
    return new Date(value);
  }
  if (key === "transactionId" && typeof value === "number") {
    return BigInt(context.source);
  }
  return value;
});

console.log(order.placedAt instanceof Date);
console.log(order.placedAt.toISOString());
console.log(typeof order.transactionId);
console.log(order.transactionId.toString());

true
2026-09-04T10:30:00.000Z
bigint
9007199254740993

transactionId 超出 安全整数（safe integer） 范围。回调中的 value 已经是不精确的 Number，但 Node 24 提供的 context.source 仍保存原始数字字符，因此可以直接交给 BigInt()。

这个转换只应用于协议明确指定的字段。按“像日期”或“数字很大”等启发式条件转换所有字符串，会悄悄改变合法业务文本；更通用的协议应使用经过验证的类型标签，并处理标签与用户字段冲突。

陷阱

延伸阅读

• MDN：JSON 对象
• MDN：JSON.parse()
• MDN：JSON.stringify()
• ECMAScript 规范：JSON 对象
• RFC 8259：JSON 数据交换格式