JavaScript 中 JSON.stringify 的二八法则

JavaScript 中 JSON.stringify 的二八法则

JSON.stringify() 函数是一个把 JavaScript object 转换成 JSON 的标准方法。很多 JavaScript 框架在底层都使用了 JSON.stringify(),例如:Express' res.json(),Axios' post() 和 Webpack stats 都在底层调用了 JSON.stringify()。这篇文章会提供一个实用的、包含异常情况的 JSON.stringify() 的概述。

开始

几乎所有现代的 JavaScript 运行环境都支持 JSON.stringify()。甚至 IE 浏览器自从 IE8 支持 JSON.stringify()。下面是一个把普通的 object 转换成 JSON 的例子:

const obj = { answer: 42 };

const str = JSON.stringify(obj);
str; // '{"answer":42}'
typeof str; // 'string'

如你所见,下面的例子是 JSON.stringify() 和 JSON.parse() 一起使用的。这种写法可以用来深拷贝 JavaScript 对象

const obj = { answer: 42 };
const clone = JSON.parse(JSON.stringify(obj));

clone.answer; // 42
clone === obj; // false

错误和边界处理

如果 JSON.stringify() 的参数是 cyclical object,则会抛出一个错误(详情)。也就是说,如果对象 obj 有一个属性,这个属性的值是 obj 本身,那么 JSON.stringify() 会抛出一个错误。

const obj = {};
// 循环 object 指向它自身
obj.prop = obj;

// 抛出 "TypeError: TypeError: Converting circular structure to JSON"
JSON.stringify(obj);

这是 JSON.stringify() 唯一抛出异常的场景,除非你使用自定义的 toJSON() 函数或者使用替代函数(replacer)。然而即便这样,你也还是得把 JSON.stringify() 包在 try/catch 里调用,因为循环 objects 还是可能会出现。

还有很多边界场景 JSON.stringify() 不会抛出异常,但其结果可能不如你所想。比如,JSON.stringify() 会把 NaNInfinity 转换成 null

const obj = { nan: parseInt('not a number'), inf: Number.POSITIVE_INFINITY };

JSON.stringify(obj); // '{"nan":null,"inf":null}'

JSON.stringify() 也会把属性值为函数或者 undefined 的内容干掉:

const obj = { fn: function () {}, undef: undefined };

// 空 object `JSON.stringify()` 过滤 functions 和 `undefined`。
JSON.stringify(obj); // '{}'

优化输出

JSON.stringify() 的第一个参数是要被序列化成 JSON 的 object。实际上 JSON.stringify() 接受 3 个参数,第三个参数 spaces(译注:空隙)。参数 spaces 用来将 JSON 格式化输出成方便阅读的格式。

参数 spaces 可以是 string 或 number。如果 spaces 不是 undefined,那么 JSON.stringify() 则会把 JSON 中的每一个 key 单独作为一行输出,并且加上 spaces 的前缀。

const obj = { a: 1, b: 2, c: 3, d: { e: 4 } };

// '{"a":1,"b":2,"c":3,"d":{"e":4}}'
JSON.stringify(obj);

// {
//   "a": 1,
//   "b": 2,
//   "c": 3,
//   "d": {
//     "e": 4
//   }
// }
JSON.stringify(obj, null, '  ');

// 使用 2 个空格来格式化 JSON 输出。和上面的例子等价。
JSON.stringify(obj, null, 2);

把参数 spaces 作为字符串使用时,虽然在实际场景中大多是使用空格,但其实不限制必须全是空格。例如:

// {
// __"a": 1,
// __"b": 2,
// __"c": 3,
// __"d": {
// ____"e": 4
// __}
// }
JSON.stringify(obj, null, '__');

Replacers

JSON.stringify() 的第二个参数是 replacer 函数。在上面的例子中,replacernull。JavaScript 针对 object 中的每一个 key/value 对都会调用 replacer 函数,使用函数的返回值作为属性的值。例如:

const obj = { a: 1, b: 2, c: 3, d: { e: 4 } };

// `replacer` 使每个数字的值加 1。输出:
// '{"a":2,"b":3,"c":4,"d":{"e":5}}'
JSON.stringify(obj, function replacer(key, value) {
  if (typeof value === 'number') {
    return value + 1;
  }
  return value;
});

替代函数(译注:replacer)在过滤敏感词的场景非常有用。例如,假设你想过滤所有包含 'password' 及 'password' 子字符串的 keys

const obj = {
  name: 'Jean-Luc Picard',
  password: 'stargazer',
  nested: {
    hashedPassword: 'c3RhcmdhemVy',
  },
};

// '{"name":"Jean-Luc Picard","nested":{}}'
JSON.stringify(obj, function replacer(key, value) {
  // 这个函数会被调用 5 次。 `key` 等于:
  // '', 'name', 'password', 'nested', 'hashedPassword'
  if (key.match(/password/i)) {
    return undefined;
  }
  return value;
});

函数 toJSON()

JSON.stringify() 函数会遍历 object 寻找含有 toJSON() 函数的属性。如果它找到了 toJSON() 函数,JSON.stringify() 会调用 toJSON() 函数,并使用其返回值作为替代。例如:

const obj = {
  name: 'Jean-Luc Picard',
  nested: {
    test: 'not in output',
    toJSON: () => 'test',
  },
};

// '{"name":"Jean-Luc Picard","nested":"test"}'
JSON.stringify(obj);

函数 toJSON() 可以返回任何值,包括对象、原始类型的值,甚至 undefined。如果 toJSON() 返回 undefinedJSON.stringify() 会忽略这个属性。 许多 JavaScript 模块使用 toJSON() 这一特性来保证复杂的对象能被正确的序列化。比如 Mongoose documentsMoment objects

后续

函数 JSON.stringify() 是 JavaScript 基础的核心。许多库和框架在底层都使用了它,所以对 JSON.stringify() 的扎实理解,可以帮助更好的学习你感兴趣的 npm 模块。比如,针对你的 Express REST API,可以借用自定义 toJSON() 函数的能力来处理原生的 Date 类,以此实现一个日期格式化的替代方案,或者,当使用 Axios 发送 HTTP 请求时,确保客户端的循环对象能被正确地转换成 JSON。(译注:帕累托法则即 80/20 Rule,一般指 20% 的输入,决定 80% 的结果的现象。)

本文作者 Valeri Karpov,转载请注明来源链接:

原文链接:https://thecodebarbarian.com/the-80-20-guide-to-json-stringify-in-javascript.html

本文链接:https://tie.pub/2019/11/guide-to-json-stringify/