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数据交换格式