JavaScript JSON.stringify()（详细教程）

JavaScript JSON.stringify() 的实用指南

在前端开发中，数据的格式转换是一项高频操作。当你需要将 JavaScript 对象或数组传递给后端、存储到本地存储（localStorage）或者在不同模块间共享时，JavaScript JSON.stringify() 就成了不可或缺的工具。它能将复杂的 JavaScript 数据结构“翻译”成标准的 JSON 字符串，让数据在不同系统间畅通无阻。

如果你刚接触 JavaScript，可能会觉得 JSON 是个神秘的格式。其实它很像一个“数据说明书”——结构清晰、易于阅读，也方便机器解析。而 JSON.stringify() 就是这本说明书的“翻译官”。

什么是 JSON 与 JavaScript JSON.stringify()

JSON（JavaScript Object Notation）是一种轻量级的数据交换格式，广泛用于 Web 应用的数据传输。它基于 JavaScript 的对象字面量语法，但具有更强的可读性和跨语言兼容性。

JavaScript 中的 JSON.stringify() 方法正是用来将 JavaScript 值（如对象、数组、基本类型）转换为 JSON 格式的字符串。这个过程也叫“序列化”（Serialization），即把内存中的数据结构变成可存储或传输的字符串。

// 示例：将一个对象转换为 JSON 字符串
const user = {
  name: "张三",
  age: 28,
  hobbies: ["读书", "游泳", "编程"]
};

const jsonString = JSON.stringify(user);
console.log(jsonString);
// 输出：{"name":"张三","age":28,"hobbies":["读书","游泳","编程"]}

注释：JSON.stringify() 接收一个 JavaScript 值作为参数，返回其对应的 JSON 字符串。注意，对象中的属性名必须用双引号包裹，这是 JSON 的语法要求。

基本用法：从对象到字符串

最常见的情况是将一个 JavaScript 对象转换为 JSON 字符串。这个过程看似简单，但背后有许多细节需要注意。

创建对象与初始化

// 定义一个用户信息对象
const userInfo = {
  id: 1001,
  username: "alice",
  email: "alice@example.com",
  isActive: true,
  lastLogin: new Date().toISOString() // 日期转为 ISO 字符串
};

// 使用 JSON.stringify() 转换为 JSON 字符串
const jsonStr = JSON.stringify(userInfo);

console.log(jsonStr);
// 输出：{"id":1001,"username":"alice","email":"alice@example.com","isActive":true,"lastLogin":"2024-04-05T10:30:45.123Z"}

注释：JSON.stringify() 会自动处理布尔值、数字、字符串和日期对象。其中，Date 类型会被转换为 ISO 8601 格式的字符串，这正是我们期望的格式。

处理数组

数组同样可以被 JSON.stringify() 处理，它会按顺序输出数组元素，保持原始结构。

// 定义一个包含多种数据类型的数组
const data = [
  "JavaScript",
  42,
  true,
  null,
  { city: "北京", population: 21890000 }
];

const jsonArr = JSON.stringify(data);
console.log(jsonArr);
// 输出：["JavaScript",42,true,null,{"city":"北京","population":21890000}]

注释：数组中的每一项都会被独立处理，包括嵌套对象。注意 null 会被保留为 null，而不是字符串 "null"。

处理复杂数据结构：嵌套对象与循环引用

当数据结构变得复杂时，JSON.stringify() 依然能胜任，但需要警惕一些边界情况。

嵌套对象

const company = {
  name: "科技未来有限公司",
  departments: [
    {
      deptName: "前端部",
      employees: [
        { name: "李四", role: "高级前端" },
        { name: "王五", role: "前端工程师" }
      ]
    },
    {
      deptName: "后端部",
      employees: [
        { name: "赵六", role: "后端架构师" }
      ]
    }
  ]
};

const jsonCompany = JSON.stringify(company, null, 2); // 第三个参数为缩进空格数
console.log(jsonCompany);

注释：这里使用了 JSON.stringify() 的第二个参数 replacer（暂设为 null）和第三个参数 space。space 为 2 表示使用两个空格缩进，让输出结果更易读。这在调试时非常有用。

循环引用：陷阱与解决方案

循环引用是 JSON.stringify() 的一个常见“坑”。当对象之间相互引用时，序列化会失败并抛出错误。

const a = { name: "A" };
const b = { name: "B" };

a.child = b;
b.parent = a; // 这里形成了循环引用

try {
  JSON.stringify(a);
} catch (error) {
  console.log("错误：", error.message);
  // 输出：Converting circular structure to JSON
}

注释：由于 a 包含 b，而 b 又包含 a，形成了“无限回环”，JSON.stringify() 无法处理，会抛出错误。这就像一个“死循环”的数据链。

解决方案：使用 replacer 函数来过滤或替换循环引用。

function replacer(key, value) {
  // 如果是循环引用，返回 undefined 跳过该属性
  if (key === 'parent') return undefined;
  return value;
}

const safeJson = JSON.stringify(b, replacer, 2);
console.log(safeJson);
// 输出：{"name":"B","child":{"name":"A","child":{}}}

注释：replacer 函数接收键和值，返回处理后的值。返回 undefined 时，该属性将被忽略。这种机制让开发者可以灵活控制序列化过程。

自定义序列化：使用 replacer 函数

replacer 参数让 JSON.stringify() 不只是“照搬”，还能“筛选”和“修改”数据。

过滤特定字段

const user = {
  id: 123,
  name: "小明",
  password: "123456", // 不希望被序列化
  email: "xiaoming@example.com"
};

// 只保留 id、name、email，忽略 password
const filtered = JSON.stringify(user, (key, value) => {
  if (key === 'password') return undefined; // 忽略密码字段
  return value;
}, 2);

console.log(filtered);
// 输出：{"id":123,"name":"小明","email":"xiaoming@example.com"}

注释：replacer 函数在递归遍历对象时，会为每个键值对调用一次。通过判断 key 是否为 password，可以安全地排除敏感信息。

按规则转换值

const data = {
  score: 95,
  level: "A",
  createdAt: new Date("2024-01-01")
};

const formatted = JSON.stringify(data, (key, value) => {
  if (key === 'score') return value + 1; // 加1分
  if (key === 'createdAt') return value.slice(0, 10); // 只保留日期部分
  return value;
}, 2);

console.log(formatted);
// 输出：{"score":96,"level":"A","createdAt":"2024-01-01"}

注释：replacer 不仅能过滤，还能修改值。这在数据预处理中非常实用，比如统一时间格式、添加默认值等。

格式化输出：使用 space 参数

默认情况下，JSON.stringify() 生成的字符串是紧凑的，没有换行和缩进。对于调试或日志记录，这不太友好。

使用数字指定缩进

const config = {
  theme: "dark",
  fontSize: 14,
  notifications: {
    email: true,
    push: false
  }
};

// 使用 4 个空格缩进
const prettyJson = JSON.stringify(config, null, 4);
console.log(prettyJson);

注释：space 参数可以是数字（如 2、4），也可以是字符串（如 " "）。数字表示空格数量，字符串则按字符填充。推荐使用 2 或 4，便于阅读。

使用字符串作为缩进

// 使用制表符缩进
const tabbed = JSON.stringify(config, null, "\t");
console.log(tabbed);

注释：虽然 "\t" 能实现缩进，但在多数编辑器中，制表符的显示行为不一致，建议使用空格。

常见错误与最佳实践

错误 1：试图序列化函数或 undefined

const obj = {
  name: "测试",
  fn: function () { console.log("hello"); },
  value: undefined
};

const result = JSON.stringify(obj);
console.log(result);
// 输出：{"name":"测试","value":null}

注释：函数和 undefined 在 JSON 中没有对应类型，会被忽略或转换为 null。不要试图序列化函数，它们无法在 JSON 中表达。

错误 2：忽略错误处理

// 建议在使用 JSON.stringify() 时加上 try-catch
try {
  const data = { a: 1, b: 2 };
  const json = JSON.stringify(data);
  console.log("序列化成功：", json);
} catch (err) {
  console.error("序列化失败：", err.message);
}

注释：虽然大多数情况下 JSON.stringify() 是安全的，但循环引用等极端情况会抛出异常。添加错误处理是专业开发的体现。

总结

JavaScript JSON.stringify() 是数据序列化的基石工具。它不仅能将对象、数组轻松转为字符串，还支持自定义过滤、格式化输出，甚至处理复杂结构。

掌握它，意味着你可以在前后端通信、本地存储、日志记录等场景中游刃有余。记住：数据结构再复杂，只要用对方法，就能被安全地“打包”传输。

下次你在写代码时，不妨多问一句：这个数据是否需要变成字符串？如果是，就用 JSON.stringify()，它永远是你最可靠的伙伴。