JSON处理总出错？JavaScript中stringify常见问题与解决方案

大家好，欢迎来到今天的技术讲座。我是你们的编程专家，今天我们将深入探讨JavaScript中一个看似简单却又充满陷阱的内置对象方法——JSON.stringify()。在现代Web开发中，JSON已经成为数据交换的标准格式，而JSON.stringify()则是将JavaScript对象转换为JSON字符串的核心工具。然而，许多开发者在使用它时常常会遇到各种意想不到的问题，从简单的类型转换到复杂的循环引用，每一个都可能导致数据丢失、程序崩溃或难以调试的错误。

本次讲座的目标是帮助大家系统性地理解JSON.stringify()的工作原理、常见陷阱及其解决方案。我们将从基础语法开始，逐步深入到高级用法，并通过丰富的代码示例，确保大家能够掌握在不同场景下安全、高效地使用JSON.stringify()。

---

1. JSON.stringify() 基础：从概念到语法

在深入探讨问题之前，我们首先需要对JSON.stringify()有一个扎实的基础理解。

1.1 JSON：数据交换的通用语言

JSON (JavaScript Object Notation) 是一种轻量级的数据交换格式。它基于JavaScript的一个子集，但独立于语言。因为其简洁和易于人阅读、机器解析的特性，JSON已成为Web API、配置文件、数据存储等领域的首选。

JSON格式的规则非常严格：

• 数据是名/值对，例如 "key": "value"。
• 数据由逗号分隔。
• 花括号 {} 保存对象。
• 方括号 [] 保存数组。
• 值可以是：字符串、数字、布尔值 (true/false)、null、对象或数组。
• 字符串必须使用双引号。

1.2 JSON.stringify() 的核心作用

JSON.stringify() 方法用于将一个JavaScript值（通常是对象或数组）转换为一个JSON字符串。这个过程称为“序列化”（Serialization）。

为什么需要序列化？

• 网络传输： HTTP协议只能传输字符串。当我们需要通过网络发送JavaScript对象到服务器或另一个客户端时，必须先将其序列化为JSON字符串。
• 本地存储： Web浏览器提供的localStorage和sessionStorage只能存储字符串。为了存储复杂的JavaScript对象，我们需要将其序列化。
• 数据持久化： 将JavaScript对象保存到文件系统或数据库中通常也需要先将其转换为字符串格式。
• 深拷贝（有限制）： 在某些简单场景下，JSON.parse(JSON.stringify(obj)) 可以实现一个对象的深拷贝，但这种方法有严格的限制，我们稍后会讨论。

1.3 基本语法

JSON.stringify() 方法接受三个可选参数：

JSON.stringify(value, replacer, space)

• value: 必需。要转换成JSON字符串的JavaScript值。
• replacer: 可选。一个函数或一个数组。
  • 如果是一个函数，它将为每个属性调用，允许你修改值或过滤属性。
  • 如果是一个数组，它指定了哪些属性应该被包含在JSON字符串中。
• space: 可选。一个字符串或数字。用于在输出JSON字符串中添加空白（空格或制表符），以提高可读性。

示例：基本用法

const user = {
    id: 1,
    name: "Alice",
    email: "[email protected]",
    isActive: true
};

const jsonString = JSON.stringify(user);
console.log(jsonString); // {"id":1,"name":"Alice","email":"[email protected]","isActive":true}

// 格式化输出，增加可读性
const prettyJsonString = JSON.stringify(user, null, 2);
console.log(prettyJsonString);
/*
{
  "id": 1,
  "name": "Alice",
  "email": "[email protected]",
  "isActive": true
}
*/

const prettyJsonStringWithTab = JSON.stringify(user, null, 't');
console.log(prettyJsonStringWithTab);
/*
{
    "id": 1,
    "name": "Alice",
    "email": "[email protected]",
    "isActive": true
}
*/

---

2. replacer 参数的深度解析：定制化序列化

replacer 参数是JSON.stringify()中一个非常强大的功能，它允许我们对序列化过程进行精细的控制，解决许多常见问题。

2.1 replacer 作为函数

当replacer是一个函数时，它会为被序列化的对象或数组中的每个键值对调用。这个函数接收两个参数：key 和 value。

replacer 函数的返回值决定了序列化结果：

• 如果返回一个值，该值将被序列化到结果中。
• 如果返回 undefined，则该键值对将从结果中跳过（不会被序列化）。
• 注意：当replacer函数处理顶级对象时，key是空字符串 ""。

应用场景：

1. 过滤敏感信息： 从对象中移除不应该暴露给外部的属性。
2. 转换数据类型： 在序列化前将特定类型的数据转换为JSON兼容的格式。
3. 处理特殊值： 解决BigInt、undefined、function等无法直接序列化的问题。

示例：过滤敏感信息

假设我们有一个用户对象，其中包含密码哈希，我们不希望将其序列化到JSON中。

const sensitiveUser = {
    id: 101,
    username: "dev_master",
    email: "[email protected]",
    passwordHash: "a1b2c3d4e5f6g7h8i9j0", // 敏感信息
    lastLogin: new Date(),
    settings: {
        theme: "dark",
        notifications: true
    }
};

function replacerForSensitiveData(key, value) {
    if (key === "passwordHash") {
        return undefined; // 过滤掉 passwordHash 属性
    }
    if (key === "lastLogin" && value instanceof Date) {
        return value.toISOString(); // 将 Date 对象转换为 ISO 字符串
    }
    return value; // 其他值正常返回
}

const safeUserJson = JSON.stringify(sensitiveUser, replacerForSensitiveData, 2);
console.log(safeUserJson);
/*
{
  "id": 101,
  "username": "dev_master",
  "email": "[email protected]",
  "lastLogin": "2023-10-27T10:00:00.000Z", // 示例日期，实际会是当前时间
  "settings": {
    "theme": "dark",
    "notifications": true
  }
}
*/

// 注意：顶级对象（sensitiveUser本身）调用replacer时，key是空字符串""
const topLevelCheck = JSON.stringify(sensitiveUser, (key, value) => {
    if (key === "") {
        console.log("Processing top-level object:", value);
    }
    return value;
});
// Processing top-level object: {id: 101, username: "dev_master", ...}

2.2 replacer 作为数组

当replacer是一个字符串数组时，它指定了哪些属性应该被包含在序列化的结果中。数组中的每个字符串都必须是将被序列化的对象或数组中的属性名。只有这些属性会被序列化，其他属性将被忽略。

应用场景：

1. 精确控制输出： 当你只需要对象中的特定几个属性时，这比函数形式更简洁。

示例：选择特定属性

const product = {
    id: "prod-001",
    name: "Wireless Mouse",
    price: 25.99,
    category: "Electronics",
    stock: 150,
    manufacturer: {
        name: "TechCorp",
        country: "USA"
    }
};

// 只序列化 id, name, price, category
const selectedProductJson = JSON.stringify(product, ["id", "name", "price", "category"], 2);
console.log(selectedProductJson);
/*
{
  "id": "prod-001",
  "name": "Wireless Mouse",
  "price": 25.99,
  "category": "Electronics"
}
*/

// 嵌套对象的属性不会被自动包含，除非你指定它们
const nestedSelectedJson = JSON.stringify(product, ["id", "name", "manufacturer"], 2);
console.log(nestedSelectedJson);
/*
{
  "id": "prod-001",
  "name": "Wireless Mouse",
  "manufacturer": {
    "name": "TechCorp",
    "country": "USA"
  }
}
*/
// 注意：数组形式的replacer不会递归地处理嵌套对象的属性，它只作用于当前层级。
// 如果你想选择 manufacturer 内部的属性，你需要手动处理或使用函数形式。

总结 replacer 参数：

replacer 类型	描述	优点	缺点	适用场景
null 或 undefined	不使用 replacer，默认行为	最简单，默认序列化所有可序列化属性	无法过滤或转换数据	简单对象，无特殊处理需求
函数	为每个键值对调用，可修改或过滤数据	极高的灵活性，可处理复杂逻辑、数据转换和过滤	实现相对复杂，性能开销可能略高	过滤敏感数据、处理特殊类型、自定义序列化逻辑
数组	指定要包含在JSON中的属性名列表	简洁高效，明确指定所需属性	只能包含/排除顶级属性，无法转换数据，不递归	只需要对象中特定几个属性，且无嵌套过滤需求

---

3. space 参数：美化输出

space 参数用于在生成的JSON字符串中插入空白字符，以提高可读性。这对于调试、日志记录或人工审查JSON数据非常有用。

3.1 space 作为数字

如果space是一个数字，它表示在JSON字符串中缩进的空格数量。有效值范围是0到10。如果大于10，则按10处理；如果小于0，则不缩进。

const data = { a: 1, b: { c: 2, d: [3, 4] } };

console.log(JSON.stringify(data));         // {"a":1,"b":{"c":2,"d":[3,4]}}
console.log(JSON.stringify(data, null, 0));  // {"a":1,"b":{"c":2,"d":[3,4]}} (不缩进)
console.log(JSON.stringify(data, null, 2));
/*
{
  "a": 1,
  "b": {
    "c": 2,
    "d": [
      3,
      4
    ]
  }
}
*/
console.log(JSON.stringify(data, null, 4));
/*
{
    "a": 1,
    "b": {
        "c": 2,
        "d": [
            3,
            4
        ]
    }
}
*/

3.2 space 作为字符串

如果space是一个字符串，它将被用作缩进字符。这个字符串的长度不能超过10个字符。

const data = { a: 1, b: { c: 2, d: [3, 4] } };

console.log(JSON.stringify(data, null, '--'));
/*
{
--"a": 1,
--"b": {
----"c": 2,
----"d": [
------3,
------4
----]
--}
}
*/
console.log(JSON.stringify(data, null, 't')); // 使用制表符缩进
/*
{
    "a": 1,
    "b": {
        "c": 2,
        "d": [
            3,
            4
        ]
    }
}
*/

重要提示： space 参数只影响输出的可读性，不影响JSON数据的实际内容或解析。在生产环境中，通常会省略space参数以减小JSON字符串的大小，从而提高传输效率。

---

4. JSON.stringify() 的“陷阱”：常见问题与解决方案

现在，我们进入本次讲座的核心部分：JSON.stringify()在使用过程中常见的陷阱和它们的解决方案。理解这些“陷阱”是成为JSON.stringify()真正专家的关键。

4.1 陷阱一：循环引用（Circular References）

这是JSON.stringify()最臭名昭著的问题。当一个对象直接或间接引用了自身时，就会形成循环引用。JSON.stringify()遇到这种情况时，会抛出 TypeError: Converting circular structure to JSON 错误。

问题示例：

const obj1 = {};
const obj2 = { parent: obj1 };
obj1.child = obj2; // obj1 引用 obj2，obj2 引用 obj1，形成循环

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

解决方案：

处理循环引用没有银弹，通常需要根据具体业务需求选择策略。

1. 使用 replacer 函数手动移除或替换循环引用

这是最常见和推荐的方法之一。通过自定义replacer函数，我们可以检测并处理循环引用。

const objA = {};
const objB = { id: 'B' };
objA.refB = objB;
objB.refA = objA; // 循环引用

const cache = new Set(); // 用于存储已经序列化过的对象

const circularReplacer = (key, value) => {
    if (typeof value === 'object' && value !== null) {
        if (cache.has(value)) {
            // 循环引用，就地删除，或者返回一个标识符
            // return undefined; // 彻底移除循环引用的属性
            return '[Circular Reference]'; // 替换为标识符字符串
        }
        // 缓存当前对象
        cache.add(value);
    }
    return value;
};

const jsonString = JSON.stringify(objA, circularReplacer, 2);
console.log(jsonString);
/*
{
  "refB": {
    "id": "B",
    "refA": "[Circular Reference]"
  }
}
*/

// 注意：JSON.stringify 会对每个对象进行深度遍历，每次遍历到新的对象时，
// replacer 函数的 key 和 value 都会更新。
// 在处理完一个对象的所有属性后，为了避免误删，需要清空 cache。
// 然而，在 JSON.stringify 的单次调用中，cache 不会自动清空。
// 如果你想在每次 stringify 调用时都有一个全新的 cache，
// 应该将 cache 的创建封装在 stringify 调用外部或 replacer 内部。
// 更好的做法是，如果 replacer 函数内部需要维护状态（如 cache），
// 那么它应该是一个闭包或一个方法。

function getCircularReplacer() {
    const seen = new WeakSet(); // 使用 WeakSet 避免内存泄漏
    return (key, value) => {
        if (typeof value === 'object' && value !== null) {
            if (seen.has(value)) {
                return; // 返回 undefined，移除此属性
            }
            seen.add(value);
        }
        return value;
    };
}

const objX = {};
const objY = { name: "Y" };
objX.parent = objY;
objY.child = objX;

const jsonStringFixed = JSON.stringify(objX, getCircularReplacer(), 2);
console.log(jsonStringFixed);
/*
{
  "parent": {
    "name": "Y",
    "child": {} // objX 的 child 属性被移除了
  }
}
*/
// 这种方法的好处是，`WeakSet` 不会阻止垃圾回收，更适合处理大型或临时对象。

**2. 预处理数据结构**

在调用`JSON.stringify()`之前，手动遍历对象，识别并解除循环引用。例如，将循环引用替换为对象的ID，然后在解析时再根据ID重建引用。这通常需要更复杂的逻辑，特别是在大型应用中。

```javascript
// 假设有一个简单的用户-文章关系，文章引用用户，用户引用文章列表
class User {
    constructor(id, name) {
        this.id = id;
        this.name = name;
        this.articles = [];
    }
}

class Article {
    constructor(id, title, author) {
        this.id = id;
        this.title = title;
        this.author = author; // 引用 User 对象
    }
}

const user1 = new User(1, "Alice");
const article1 = new Article(101, "JS Tips", user1);
const article2 = new Article(102, "CSS Tricks", user1);

user1.articles.push(article1, article2); // 用户引用文章列表

// 此时 user1.articles[0].author === user1，形成循环引用

// 解决方案：在序列化前，将循环引用转换为可序列化的ID
const prepareForSerialization = (obj) => {
    if (obj instanceof User) {
        return {
            id: obj.id,
            name: obj.name,
            // 仅保留文章ID，而不是完整的文章对象
            articles: obj.articles.map(article => article.id)
        };
    }
    if (obj instanceof Article) {
        return {
            id: obj.id,
            title: obj.title,
            // 仅保留作者ID，而不是完整的User对象
            authorId: obj.author ? obj.author.id : null
        };
    }
    return obj;
};

const processedUser = prepareForSerialization(user1);
const processedArticle1 = prepareForSerialization(article1);

// 现在序列化处理过的对象
console.log(JSON.stringify(processedUser, null, 2));
/*
{
  "id": 1,
  "name": "Alice",
  "articles": [
    101,
    102
  ]
}
*/
console.log(JSON.stringify(processedArticle1, null, 2));
/*
{
  "id": 101,
  "title": "JS Tips",
  "authorId": 1
}
*/

// 反序列化后，你需要手动根据ID重建引用关系。

3. 使用第三方库

有一些库专门用于处理复杂的序列化需求，例如 flatted、json-cycle 等，它们可以处理循环引用，并在反序列化时重建原始结构。

// 示例（不实际引入库，仅作说明）
// 假设使用 flatted 库
// import { stringify, parse } from 'flatted';

// const obj1 = {};
// const obj2 = { parent: obj1 };
// obj1.child = obj2;

// const flattedJson = stringify(obj1);
// console.log(flattedJson); // 会生成一个特殊格式的JSON字符串
// const reconstructedObj = parse(flattedJson);
// console.log(reconstructedObj.child.parent === reconstructedObj); // true

4.2 陷阱二：特定数据类型的处理行为

JSON.stringify()并非对所有JavaScript数据类型都一视同仁。某些类型会被特殊处理，有些则会被忽略或导致错误。

4.2.1 被忽略或转换为 null 的值

• undefined：
  • 作为对象属性的值时，该属性会被完全忽略。
  • 作为数组元素时，会被序列化为 null。
  • 作为顶级值序列化时，会返回 undefined（而不是字符串 "undefined"）。
• function： 行为与 undefined 类似。
• Symbol： 行为与 undefined 类似。

示例：undefined, function, Symbol

const data = {
    a: 1,
    b: undefined,
    c: function() { console.log('hello'); },
    d: Symbol('test'),
    e: [1, undefined, 3, function() {}]
};

console.log(JSON.stringify(data)); // {"a":1,"e":[1,null,3,null]}
// 'b', 'c', 'd' 属性被忽略了
// 数组中的 undefined 和 function 变成了 null

console.log(JSON.stringify(undefined)); // undefined (不是字符串 "undefined")
console.log(JSON.stringify(function() {})); // undefined
console.log(JSON.stringify(Symbol('foo'))); // undefined

解决方案：
如果需要序列化这些类型，你必须在 replacer 函数中显式地将它们转换为JSON支持的类型（如字符串）。

const dataWithSpecialTypes = {
    myUndefined: undefined,
    myFunction: () => "I am a function",
    mySymbol: Symbol('id')
};

const customStringifier = JSON.stringify(dataWithSpecialTypes, (key, value) => {
    if (value === undefined) {
        return "[[undefined]]"; // 将 undefined 转换为特定字符串
    }
    if (typeof value === 'function') {
        return value.toString(); // 将函数转换为其代码字符串
    }
    if (typeof value === 'symbol') {
        return value.toString(); // 将 Symbol 转换为其描述字符串
    }
    return value;
}, 2);

console.log(customStringifier);
/*
{
  "myUndefined": "[[undefined]]",
  "myFunction": "() => "I am a function"",
  "mySymbol": "Symbol(id)"
}
*/

4.2.2 Date 对象

Date 对象会被序列化为ISO 8601格式的字符串。

const event = {
    name: "Meeting",
    date: new Date("2024-01-01T10:30:00.000Z")
};

console.log(JSON.stringify(event)); // {"name":"Meeting","date":"2024-01-01T10:30:00.000Z"}

注意： 反序列化时，此字符串不会自动转换回 Date 对象，你需要手动处理：new Date(JSON.parse(jsonString).date)。

4.2.3 RegExp、Map、Set、BigInt 等

• RegExp (正则表达式)： 序列化为 {} 空对象。
• Map, Set： 序列化为 {} 空对象。它们的数据结构在JSON中没有直接对应。
• BigInt： 序列化时会抛出 TypeError。JSON不支持任意精度的整数。
• NaN, Infinity, -Infinity： 序列化为 null。

示例：RegExp, Map, Set, BigInt, NaN

const complexData = {
    pattern: /abc/gi,
    settings: new Map([['key1', 'value1'], ['key2', 'value2']]),
    tags: new Set(['tagA', 'tagB']),
    largeNumber: 123456789012345678901234567890n, // BigInt
    notANumber: NaN,
    positiveInfinity: Infinity,
    negativeInfinity: -Infinity
};

try {
    console.log(JSON.stringify(complexData, null, 2));
} catch (error) {
    console.error("错误：", error.message); // 错误：Do not know how to serialize a BigInt
}

// 解决 BigInt 错误
const fixedComplexDataJson = JSON.stringify(complexData, (key, value) => {
    if (typeof value === 'bigint') {
        return value.toString() + 'n'; // 将 BigInt 转换为字符串，并添加 'n' 后缀以示区分
    }
    if (value instanceof Map) {
        return Array.from(value.entries()); // 将 Map 转换为键值对数组
    }
    if (value instanceof Set) {
        return Array.from(value); // 将 Set 转换为数组
    }
    if (value instanceof RegExp) {
        return value.source; // 将 RegExp 转换为其模式字符串
    }
    return value;
}, 2);

console.log(fixedComplexDataJson);
/*
{
  "pattern": "abc",
  "settings": [
    [
      "key1",
      "value1"
    ],
    [
      "key2",
      "value2"
    ]
  ],
  "tags": [
    "tagA",
    "tagB"
  ],
  "largeNumber": "123456789012345678901234567890n",
  "notANumber": null,
  "positiveInfinity": null,
  "negativeInfinity": null
}
*/

总结：不同数据类型的序列化行为

JavaScript 类型	序列化结果	备注
Number	JSON 数字	NaN, Infinity, -Infinity 变为 null
String	JSON 字符串 (双引号)
Boolean	JSON 布尔值 (true/false)
null	JSON null
Array	JSON 数组	元素中的 undefined, function, Symbol 变为 null
Object (Plain)	JSON 对象	只序列化可枚举的自身属性；属性中的 undefined, function, Symbol 被忽略
Date	ISO 8601 格式的字符串	例如 "2023-10-27T10:00:00.000Z"
BigInt	抛出 TypeError	JSON 不支持任意精度整数
undefined	对象属性被忽略；数组元素变为 null；顶级值返回 undefined
function	对象属性被忽略；数组元素变为 null；顶级值返回 undefined
Symbol	对象属性被忽略；数组元素变为 null；顶级值返回 undefined
RegExp	{} (空对象)
Map, Set	{} (空对象)
Error 对象	{} (空对象)，只包含 name 和 message (非标准)	不同浏览器实现可能略有差异，通常只保留少量属性或空对象
自定义 Class 实例	行为类似于普通对象，只序列化可枚举的自身属性。	可通过 toJSON() 方法自定义行为

4.3 陷阱三：数据精度丢失

JavaScript的 Number 类型是双精度浮点数，它能安全表示的整数范围是 -(2^53 - 1) 到 2^53 - 1，即 Number.MIN_SAFE_INTEGER 到 Number.MAX_SAFE_INTEGER。超出这个范围的整数在序列化和反序列化过程中可能会丢失精度。

问题示例：

const largeNumber = 9007199254740991; // Number.MAX_SAFE_INTEGER
const largerNumber = 9007199254740992; // 超出安全范围，但仍然是 JS 数字

const dataWithNumbers = {
    safe: largeNumber,
    unsafe: largerNumber,
    veryLarge: 90071992547409921234567890 // 这在 JS 中会变为 90071992547409920000000000
};

const jsonStringNumbers = JSON.stringify(dataWithNumbers);
console.log(jsonStringNumbers);
// {"safe":9007199254740991,"unsafe":9007199254740992,"veryLarge":90071992547409920000000000}

const parsedData = JSON.parse(jsonStringNumbers);
console.log(parsedData.safe === largeNumber);   // true
console.log(parsedData.unsafe === largerNumber); // true (这里虽然是同一值，但已是精度丢失后的值)
console.log(parsedData.veryLarge);              // 9.007199254740992e+27 (注意科学计数法)
console.log(parsedData.veryLarge === 90071992547409921234567890); // false

当 veryLarge 这样的数字在 JavaScript 中被创建时，就已经失去了精度，JSON.stringify 只是序列化了那个不精确的值。

解决方案：将大整数作为字符串处理

对于需要精确表示的大整数，最佳实践是在前端和后端都将其作为字符串进行传输和存储。

const trulyLargeNumber = "90071992547409921234567890"; // 明确作为字符串处理
const dataWithTrulyLargeNumber = {
    id: 1,
    value: trulyLargeNumber
};

const jsonString = JSON.stringify(dataWithTrulyLargeNumber);
console.log(jsonString); // {"id":1,"value":"90071992547409921234567890"}

const parsed = JSON.parse(jsonString);
console.log(parsed.value); // "90071992547409921234567890" (保持为字符串)

如果你的数据源中包含的是JavaScript Number 类型的大数字（已经丢失精度），并且你无法控制源数据，那么在序列化时转换成字符串也无济于事，因为精度已在创建时丢失。你需要确保从一开始就以字符串形式接收或处理这些大数字。

4.4 陷阱四：toJSON() 方法的隐式调用

如果被序列化的对象拥有一个名为 toJSON 的方法，JSON.stringify() 在序列化该对象时会优先调用这个方法，并序列化其返回值，而不是对象本身。

应用场景：

1. 自定义序列化逻辑： 允许对象定义自己的JSON表示形式。
2. 处理复杂对象： 例如，一个表示用户信息的类，可能只想暴露部分属性。

示例：toJSON() 方法

class UserProfile {
    constructor(id, name, email, passwordHash) {
        this.id = id;
        this.name = name;
        this.email = email;
        this._passwordHash = passwordHash; // 私有属性，不希望直接序列化
        this.createdAt = new Date();
    }

    // 定义 toJSON 方法来自定义序列化行为
    toJSON() {
        // 返回一个只包含公共属性的新对象
        return {
            userId: this.id,
            fullName: this.name,
            emailAddress: this.email,
            registeredAt: this.createdAt.toISOString()
        };
    }
}

const alice = new UserProfile(1, "Alice Smith", "[email protected]", "secret123");

const userJson = JSON.stringify(alice, null, 2);
console.log(userJson);
/*
{
  "userId": 1,
  "fullName": "Alice Smith",
  "emailAddress": "[email protected]",
  "registeredAt": "2023-10-27T10:00:00.000Z" // 示例日期
}
*/
// 即使没有使用 replacer，_passwordHash 也不会被序列化，属性名也被重命名了。

注意： toJSON() 方法可以在 replacer 函数之前被调用。如果 toJSON() 返回了一个值，那么 replacer 函数将接收到 toJSON() 的返回值，而不是原始对象。

4.5 陷阱五：非可枚举属性和原型链属性

JSON.stringify() 默认只会序列化对象自身的可枚举属性。以下类型的属性会被忽略：

• 不可枚举属性： 使用 Object.defineProperty() 定义的，且 enumerable: false 的属性。
• 原型链上的属性： 从原型链继承的属性。
• Symbol 属性： 除非通过 replacer 明确处理。

示例：不可枚举属性和原型链属性

const baseConfig = {
    version: '1.0.0',
    owner: 'Admin'
};

const appConfig = Object.create(baseConfig);
appConfig.appName = 'MyWebApp';
appConfig.port = 3000;

Object.defineProperty(appConfig, 'secretKey', {
    value: 'super-secret-value',
    enumerable: false // 不可枚举
});

console.log(Object.keys(appConfig)); // ["appName", "port"]
console.log(JSON.stringify(appConfig, null, 2));
/*
{
  "appName": "MyWebApp",
  "port": 3000
}
*/
// version, owner (原型链上), secretKey (不可枚举) 都被忽略了。

解决方案：
如果需要序列化这些属性，通常需要手动遍历并将它们复制到另一个可序列化的普通对象中，或者在 toJSON() 方法中显式地包含它们。

class Config {
    constructor(name, port, secret) {
        this.name = name;
        this.port = port;
        Object.defineProperty(this, 'secret', {
            value: secret,
            enumerable: false
        });
    }

    // 自定义 toJSON 方法来包含不可枚举属性
    toJSON() {
        const obj = { ...this }; // 复制所有可枚举属性
        obj.secret = this.secret; // 手动添加不可枚举属性
        return obj;
    }
}

const myConfig = new Config("MyService", 8080, "my-app-secret");
console.log(JSON.stringify(myConfig, null, 2));
/*
{
  "name": "MyService",
  "port": 8080,
  "secret": "my-app-secret"
}
*/

4.6 陷阱六：属性顺序不保证

虽然现代JavaScript引擎（如V8）在序列化普通对象时通常会保持属性的插入顺序，但ECMAScript规范实际上不保证 JSON.stringify() 输出的属性顺序。依赖属性顺序可能会导致跨平台或跨浏览器兼容性问题。

问题示例：

const orderedObj = {
    first: 1,
    second: 2,
    third: 3
};

// 在大多数现代浏览器和Node.js中，输出顺序是稳定的
console.log(JSON.stringify(orderedObj)); // {"first":1,"second":2,"third":3}

const anotherOrderedObj = {
    z: 1,
    a: 2,
    b: 3
};
// 对于非数字键，ES2015+ 规范要求对象属性的迭代顺序是：
// 1. 所有数字键（按升序）
// 2. 所有非数字字符串键（按插入顺序）
// 3. 所有 Symbol 键（按插入顺序）
console.log(JSON.stringify(anotherOrderedObj)); // {"z":1,"a":2,"b":3}

解决方案：
不依赖JSON字符串中属性的特定顺序。JSON解析器应该能够处理任何顺序的属性。如果你的应用逻辑依赖于属性顺序，那么你需要重新设计数据结构或处理方式。例如，可以将属性存储在数组中，其中每个元素都是一个键值对对象：[{key: "first", value: 1}, {key: "second", value: 2}]。

4.7 陷阱七：序列化 Error 对象

直接序列化 Error 对象通常不会得到你期望的完整错误信息。JSON.stringify() 通常只会序列化 Error 对象的 name 和 message 属性（并且这也不是标准行为，不同环境可能表现不同）。stack 属性等关键信息会被忽略。

问题示例：

const err = new Error("Something went wrong!");
err.code = "APP_ERROR_001";
err.details = { component: "AuthService" };

console.log(JSON.stringify(err, null, 2));
/*
{
  // 不同的JS引擎可能会有不同的输出，有些可能只有 {}，有些可能有 name 和 message
  "name": "Error",
  "message": "Something went wrong!"
}
*/
// stack, code, details 等属性都被忽略了。

解决方案：自定义序列化 Error 对象

通过 replacer 函数或在 Error 类的原型上定义 toJSON() 方法来捕获所有相关信息。

const errorToJSON = (key, value) => {
    if (value instanceof Error) {
        const errorObject = {};
        Object.getOwnPropertyNames(value).forEach(prop => {
            errorObject[prop] = value[prop];
        });
        // 额外添加 stack，因为它不是可枚举的自身属性
        errorObject.stack = value.stack;
        return errorObject;
    }
    return value;
};

const customErr = new Error("Custom error message.");
customErr.code = "CUSTOM_ERROR_CODE";
customErr.details = { service: "Payment" };

const errorJson = JSON.stringify(customErr, errorToJSON, 2);
console.log(errorJson);
/*
{
  "stack": "Error: Custom error message.n    at <anonymous>:1:17", // 实际栈信息会更长
  "message": "Custom error message.",
  "code": "CUSTOM_ERROR_CODE",
  "details": {
    "service": "Payment"
  },
  "name": "Error"
}
*/

---

5. 高级应用与最佳实践

掌握了JSON.stringify()的常见问题与解决方案后，我们来看看一些高级应用场景和最佳实践。

5.1 深拷贝的局限性

JSON.parse(JSON.stringify(obj)) 常常被用作深拷贝的“捷径”。

const original = {
    name: "John",
    age: 30,
    address: {
        city: "New York",
        zip: "10001"
    }
};

const deepCopy = JSON.parse(JSON.stringify(original));
console.log(deepCopy);
console.log(deepCopy.address === original.address); // false (证明是深拷贝)

然而，这种方法有严重的局限性：

• 无法处理循环引用： 会抛出 TypeError。
• 无法拷贝函数、undefined、Symbol： 这些会被忽略或转换为 null。
• 无法拷贝 Date 对象： Date 会被转换为字符串，反序列化后仍是字符串，不是 Date 对象。
• 无法拷贝 RegExp、Map、Set 等： 它们会变成空对象 {}。
• 无法拷贝原型链上的属性和不可枚举属性。
• 无法拷贝 BigInt： 会抛出 TypeError。

因此，对于复杂的对象，应使用更健壮的深拷贝方法（如结构化克隆算法 structuredClone() API，或第三方库如 lodash.cloneDeep）。

5.2 性能考量

对于非常大的JavaScript对象，JSON.stringify() 可能会是一个计算密集型操作，可能导致主线程阻塞，影响用户体验。

优化策略：

• 只序列化必要数据： 使用 replacer 数组或函数过滤掉不必要的属性。
• 分块处理： 如果可能，将大型数据结构分解为更小的部分进行序列化和传输。
• Web Workers： 在浏览器环境中，将 JSON.stringify() 操作放在 Web Worker 中执行，可以避免阻塞主线程。

// 示例：在 Web Worker 中执行 JSON.stringify (概念性代码)

// main.js
// const worker = new Worker('worker.js');
// worker.postMessage(largeObject);
// worker.onmessage = (event) => {
//     const jsonString = event.data;
//     console.log("Received JSON from worker:", jsonString.substring(0, 100) + "...");
// };

// worker.js
// onmessage = (event) => {
//     const data = event.data;
//     const jsonString = JSON.stringify(data);
//     postMessage(jsonString);
// };

5.3 安全性考虑

尽管 JSON.stringify() 本身不会直接引入安全漏洞，但在某些特定场景下需要注意：

• 敏感数据过滤： 确保在使用 JSON.stringify() 发送数据到客户端或第三方时，所有敏感信息（如密码、API密钥）都已被 replacer 过滤掉。
• 与 eval() 结合的风险： 永远不要使用 eval() 来解析不信任的JSON字符串。JSON.parse() 是安全且推荐的JSON字符串解析方法。

5.4 替代方案和扩展

对于超出 JSON.stringify() 能力范围的复杂序列化需求，可以考虑：

• structuredClone() API： 浏览器环境下的新API，可以处理循环引用、Map、Set、Date、RegExp、ArrayBuffer 等多种复杂类型，是深拷贝的推荐方案。但它不是用于生成JSON字符串，而是生成新的JavaScript对象。
• 第三方序列化库：
  • superjson：用于序列化和反序列化无法被 JSON.stringify 处理的JavaScript类型，如 Date, Map, Set, BigInt, RegExp 等。
  • flatted / json-cycle：专门处理循环引用。
  • bson：MongoDB使用的二进制JSON格式，更高效，支持更多数据类型。

---

6. 总结与展望

JSON.stringify() 是JavaScript中一个至关重要的工具，它的核心功能是将JavaScript值转换为JSON字符串，广泛应用于数据传输和存储。然而，正如我们今天所见，其行为并非总是直观，尤其是在处理特定数据类型、循环引用和非可枚举属性时。

通过深入理解其参数——replacer 和 space，以及掌握如何解决循环引用、数据类型转换、精度丢失等常见陷阱，我们能够更安全、更高效地利用这个强大的方法。记住，对于复杂的序列化或深拷贝需求，了解其局限性，并适时考虑使用 toJSON() 方法、structuredClone() API 或专业的第三方库，是成为一名优秀开发者的必备技能。

希望今天的讲座能帮助大家在未来的开发工作中，自信地驾驭 JSON.stringify()，避免那些恼人的“坑”，写出更健壮、更可靠的代码。数据序列化是现代编程的基石，掌握好它，你将能更好地构建高性能、高可维护性的应用程序。