深入剖析JavaScript在将对象序列化为JSON时Date变字符串、undefined丢失、BigInt抛错等现象的底层原因,提供原生Replacer/Reviver无损编解码、成熟第三方库选型以及工程级DTO契约设计的完整落地方案。
JS转换JSON时Date、undefined等特殊类型丢失的处理方案
时间:2026-11-22
浏览:73
文章目录
JSON.stringify() 产生特殊类型丢失的根本原因,在于 JSON 规范(RFC 8259)仅支持字符串、数值、布尔、Null、普通对象与数组 6 种数据结构。对于 Date 会被降级为 ISO 字符串、undefined 会被剔除或转为 null、BigInt 会直接抛错。
解决这一问题有三条落地路径:轻量无依赖场景使用原生 replacer 与 reviver 双向拦截封包;全栈 TypeScript / RPC 场景引入 superjson 开箱即用;跨语言网络 API 场景则应坚持 DTO 契约设计,通过显式时间戳和运行时 Schema(如 Zod)做精准转型。
一、为什么特殊类型会在序列化时丢失或变形?
在实际项目开发中,很多开发者习惯将 JSON.stringify() 与 JSON.parse() 作为对象深拷贝或状态持久化的快捷手段。然而,JavaScript 作为动态语言,其内存对象拥有丰富的运行时类型系统,而 JSON 作为跨语言的数据交换协议,其类型集合高度精简。
当执行 JSON.stringify(target) 时,序列化引擎会按照 ECMAScript 规范内置的规则对属性进行映射。如果遭遇 JSON 格式之外的数据类型,其默认处理行为通常可以分为三类:
| 特殊类型 | 默认序列化行为 | 反序列化后的状态 | 产生的问题与影响 |
|---|---|---|---|
Date 实例 |
触发 Date.prototype.toJSON(),输出 ISO 8601 字符串 |
普通 string |
丢失原型链,无法调用 getTime() 等日期方法 |
undefined |
对象属性中被忽略并剔除;数组中转为 null |
键消失或变成 null |
破坏对象键名完整性,导致属性解构获取不到默认值 |
BigInt (如 10n) |
直接抛出 TypeError 异常 | 执行中断 | 导致整个序列化任务崩溃,中断业务主流程 |
Map / Set |
序列化为无键值的空对象 {} |
空对象 {} |
集合内存储的所有键值或元素全部丢失 |
RegExp 实例 |
序列化为无内容的空对象 {} |
空对象 {} |
正则规则与匹配修饰符全部丢失 |
NaN / Infinity |
强制转换为 null |
null |
丢失特殊的数值语义,可能误判为有效空值 |
Function / Symbol |
对象键被剔除;数组项转为 null |
完全丢失 | 闭包逻辑与 Symbol 唯一性标识不被支持 |
清晰认识上述类型的丢失特征后,我们就能针对不同的业务诉求,选用恰当的方案予以解决。
二、方案一:原生 Replacer 与 Reviver 双向编解码
在追求零外部依赖、包体积极致敏感(例如底层 SDK、公共工具类或浏览器端 LocalStorage 读写)的场景下,最推荐的做法是利用 JSON.stringify 的第二个参数 replacer,与 JSON.parse 的第二个参数 reviver 构建自定义类型协议。
1. 编解码机制与类型封包设计
replacer(key, value) 会在序列化过程中递归访问每一个节点。如果在拦截到目标特殊类型时,将其封装为一个包含元标记的常规对象(例如 { __t: 'Date', __v: value.getTime() }),就能绕过 JSON 引擎的强制降级。
相对应地,reviver(key, value) 采用自底向上的递归遍历方式。在解析每个节点时,只要检测到包含 __t 标记,便调用对应的构造函数(如 new Date(__v))将数据还原回原生实例。
2. 工业级可运行代码实现
下面是一个经过边界验证的通用工具函数实现,支持了 Date、undefined、BigInt、Map、Set 以及 RegExp 的无损传输与还原:
/**
* 通用无损 JSON 序列化器
*/
const TYPE_KEY = '__t';
const VALUE_KEY = '__v';
// 编码拦截器
function customReplacer(key, value) {
// 1. 处理原始类型 undefined
if (value === undefined) {
return { [TYPE_KEY]: 'undefined' };
}
// 2. 处理 BigInt(原生 stringify 默认会抛错)
if (typeof value === 'bigint') {
return { [TYPE_KEY]: 'BigInt', [VALUE_KEY]: value.toString() };
}
// 3. 处理 Date 实例
// 注意:Date 自带 toJSON,若传入的 value 已被降级为 string,需要通过 this[key] 获取原始实例
const rawValue = this[key];
if (rawValue instanceof Date) {
return { [TYPE_KEY]: 'Date', [VALUE_KEY]: rawValue.getTime() };
}
// 4. 处理 Map 集合
if (rawValue instanceof Map) {
return { [TYPE_KEY]: 'Map', [VALUE_KEY]: Array.from(rawValue.entries()) };
}
// 5. 处理 Set 集合
if (rawValue instanceof Set) {
return { [TYPE_KEY]: 'Set', [VALUE_KEY]: Array.from(rawValue.values()) };
}
// 6. 处理 RegExp 正则
if (rawValue instanceof RegExp) {
return { [TYPE_KEY]: 'RegExp', [VALUE_KEY]: { source: rawValue.source, flags: rawValue.flags } };
}
return value;
}
// 解码还原器
function customReviver(key, value) {
if (value && typeof value === 'object' && value[TYPE_KEY]) {
switch (value[TYPE_KEY]) {
case 'undefined':
return undefined;
case 'Date':
return new Date(value[VALUE_KEY]);
case 'BigInt':
return BigInt(value[VALUE_KEY]);
case 'Map':
return new Map(value[VALUE_KEY]);
case 'Set':
return new Set(value[VALUE_KEY]);
case 'RegExp':
return new RegExp(value[VALUE_KEY].source, value[VALUE_KEY].flags);
default:
return value;
}
}
return value;
}
// 封装导出 API
export function safeStringify(data, space) {
return JSON.stringify(data, customReplacer, space);
}
export function safeParse(text) {
return JSON.parse(text, customReviver);
}
customReplacer 中,判断 Date、Map、Set 时必须使用 this[key] 而非直接判断 value。这是因为 JavaScript 引擎在执行 JSON.stringify 时,会先调用对象内部的 toJSON() 方法(例如 Date.prototype.toJSON 返回 ISO 字符串),导致传入 replacer 的 value 已经变成了普通的 string。
3. 执行验证示例
// 测试数据源
const payload = {
createdAt: new Date('2026-11-12T05:00:00Z'),
unassignedKey: undefined,
largeId: 9007199254740993n,
userTags: new Set(['admin', 'editor']),
cacheMap: new Map([['uid_1', { active: true }]]),
validator: /^[a-z0-9_-]+$/gi
};
// 执行无损序列化与还原
const jsonString = safeStringify(payload);
const restored = safeParse(jsonString);
// 验证结果
console.log(restored.createdAt instanceof Date); // 输出示例: true
console.log(restored.unassignedKey === undefined); // 输出示例: true
console.log('unassignedKey' in restored); // 输出示例: true(键完整保留)
console.log(typeof restored.largeId === 'bigint'); // 输出示例: true
console.log(restored.userTags instanceof Set); // 输出示例: true
console.log(restored.userTags.has('admin')); // 输出示例: true
三、方案二:生产级成熟库对比与应用
当项目规模扩大、涉及全栈 React / Next.js、tRPC 接口通信或需要处理复杂引用图谱时,手写 Replacer 会面临维护成本高、无法自动处理嵌套对象原型、以及容易触发循环引用等挑战。此时应优先考虑成熟的业界标准开源库。
1. Superjson:全栈 TypeScript 的事实标准
superjson 采用独特的元数据附录模式(Annotation)。它不会在原始数据内部胡乱插入侵入性属性,而是将原始值规范化后,额外生成一份轻量的路径类型索引树。
// 安装命令示例:npm install superjson
import superjson from 'superjson';
const complexObject = {
timestamp: new Date(),
limit: 100000000000000000n,
status: undefined
};
// 序列化
const { json, meta } = superjson.serialize(complexObject);
// 传输文本格式
const serializedString = superjson.stringify(complexObject);
// 还原
const original = superjson.parse(serializedString);
console.log(original.timestamp.getFullYear()); // 正常执行,完整 Date 实例
2. Devalue 与 Flatted:针对极端场景的专业利器
- Devalue: 由 Rich Harris(Svelte 作者)开发,体积仅约 2.7KB,特别强化了抵御 XSS 注入攻击的能力,并且能够序列化循环引用与自身引用结构,被广泛用于 SvelteKit 和 Nuxt 的 SSR 水合通信。
- Flatted: 专为解决
TypeError: Converting circular structure to JSON而生。它将树状 JSON 转换为平铺的索引数组,非常适合包含复杂 DOM 镜像、AST 语法树或双向图结构的场景。
四、方案三:工程架构视角的规避与契约设计
在微服务、前后端分离等跨语言架构中,后端往往是 Java、Go 或 Python。这些系统无法直接读取包含了 JavaScript 专属标记(如 __t 或 superjson 元数据)的 JSON。
从工程架构上看,网络传输层不应该直接承载复杂的内存运行时实体,而应当传输标准化的数据传输对象(DTO)。
1. 传输层契约设计规范
- 时间格式标准化: 所有时间字段统一以毫秒级时间戳(
1762923540000)或 UTC 标准 ISO 8601 字符串传输,禁止前后端依赖隐式序列化。 - 大整数规整为 String: 超过 JavaScript 精度安全上限(
Number.MAX_SAFE_INTEGER为2^53 - 1)的数值,在接口定义中必须显式定义为string。 - 集合扁平化:
Map统一转为键值元组数组[[k1, v1], [k2, v2]],Set统一转为普通数组[item1, item2]。 - 显式处理空值: 统一空值语义。如果字段缺失有明确业务含义,使用
null代替undefined,避免属性在网络传输过程中被剪除。
2. 利用运行时 Schema(以 Zod 为例)实现安全还原
前端在接收到服务端返回的标准 JSON 后,利用类型验证工具在反序列化入口处进行类型升级(Transform),实现既合规又类型安全的闭环:
import { z } from 'zod';
// 定义业务契约模型
const OrderSchema = z.object({
id: z.string(),
// 自动将字符串或时间戳安全转换为 Date 实例
createdAt: z.coerce.date(),
// 接收字符串并安全转回 BigInt
amountInWei: z.string().transform((val) => BigInt(val)),
// 接收数组并还原为 Set 集合
permissions: z.array(z.string()).transform((arr) => new Set(arr)),
// 允许 null 或可选值
remark: z.string().nullable().optional()
});
// 模拟网络接收到的标准 JSON
const networkJson = JSON.parse(`{
"id": "ord_8820",
"createdAt": "2026-11-12T05:19:00Z",
"amountInWei": "90000000000000000000",
"permissions": ["READ", "WRITE"]
}`);
// 运行时校验并自动恢复类型实例
const safeOrder = OrderSchema.parse(networkJson);
console.log(safeOrder.createdAt instanceof Date); // 输出示例: true
console.log(typeof safeOrder.amountInWei === 'bigint'); // 输出示例: true
console.log(safeOrder.permissions instanceof Set); // 输出示例: true
五、高频常见问题与陷阱(FAQ)
Q1: 既然深拷贝也会丢失 Date,可以用 structuredClone() 代替吗?
答:如果是纯粹为了在内存中克隆对象,绝不要再使用 JSON.parse(JSON.stringify(obj))。现代浏览器与 Node.js 17+ 已经原生支持 structuredClone()。
它原生支持 Date、Map、Set、RegExp、ArrayBuffer 以及循环引用的拷贝。但需要注意:structuredClone 是基于结构化克隆算法的内存操作 API,无法直接输出跨网络传输的字符串。网络传输依然需要使用 JSON 或其扩展协议。
Q2: 为什么自定义 replacer 第一次触发时 key 为空字符串 ""?
答:这是 ECMAScript 规范明确规定的行为。在序列化的一开始,引擎会构建一个伪包装对象 { "": rootObject },并将空字符串 "" 作为 key、目标对象作为 value 传入第一次调用。
编写 replacer 时,切忌盲目根据 key 过滤根对象,否则会导致整个序列化过早终止。
Q3: 如果给对象自定义 .toJSON() 方法,有哪些注意事项?
答:当对象拥有 toJSON() 方法时,JSON.stringify 会直接使用该方法的返回值参与后续流程。
很多第三方库的类实例(如 Decimal.js、Day.js、Moment.js)内部均实现了 toJSON()。在使用自定义 Replacer 时,必须警惕该方法可能先于你的拦截器执行,从而改变原本的实例类型。
实用工具推荐
绿化、压缩、噪点和虚拟水印,自由调节做旧程度。
选择画质和输出格式,预览压缩前后的大小。