JS生成JSON时怎么处理Date和undefined类型

作者:拾光

时间:2026-11-19

浏览:411

全面讲解在 JavaScript 中使用 JSON.stringify 生成 JSON 字符串时,Date 对象与 undefined 类型的默认处理机制,以及通过 replacer 函数、toJSON 方法和数据预处理保留字段与定制格式的实用解决方案。

文章目录

在 JavaScript 中通过 JSON.stringify() 序列化数据时,Date 对象会被自动转化为 ISO 8601 格式的 UTC 字符串,而普通对象中的 undefined 属性则会被静默剔除(在数组中则会被转为 null)。这一原生行为常导致前端在调用后端接口时出现时区偏差、时间戳精度丢失或由于字段缺失引发的入参校验失败。要规范化生成符合业务要求的 JSON 字符串,主要有三种解法:利用 JSON.stringify 的第二个参数 replacer 函数进行拦截替换、在数据类中实现 toJSON 实例方法,或在序列化前对数据结构做统一的递归克隆预处理。

JS生成JSON时怎么处理Date和undefined类型
图 1:JavaScript 对象在序列化生成 JSON 时的类型转换路径与关键节点

一、了解默认行为:为什么 Date 变成了字符串,undefined 会直接“消失”

JSON(JavaScript Object Notation)是一种纯文本的数据交换格式,严格遵循 RFC 8259 规范。在 JSON 规范中,合法的值类型仅限于:string、number、object、array、boolean 以及 null。因为 JSON 本身不具备原生的“日期对象”类型,也没有 undefined 语义,所以 JavaScript 运行时在执行 JSON.stringify() 时,对这两者有着截然不同的内置处理逻辑。

1. Date 对象的内建 toJSON 机制

JavaScript 的 Date.prototype 原生实现了一个名为 toJSON() 的方法。当 JSON.stringify() 遇到一个 Date 实例时,并不会按照普通对象那样去枚举它的属性,而是直接调用该实例的 toJSON() 方法。默认情况下,Date.prototype.toJSON 返回的是该时间在 UTC 时区下的 ISO 8601 格式字符串(等同于调用 toISOString()),例如 "2026-11-18T04:42:36.000Z"。

这会带来两个实际问题:一是接收端如果直接读取,需要额外的反序列化逻辑才能重新构建 Date 实例;二是如果业务接口规范要求传输毫秒时间戳(Timestamp)或特定的本地格式(如 YYYY-MM-DD HH:mm:ss),原生的 ISO 格式便无法满足需求。

2. undefined 类型的丢弃与占位

由于 JSON 规范中不存在 undefined,JavaScript 在序列化包含 undefined 的数据时采取了分流策略:

  • 作为普通对象的键值:属性键和值会被完全忽略,生成的 JSON 字符串中根本不存在该键。
  • 作为数组的元素:为了保证数组各元素的索引位置不发生位移,undefined 会被强制替换为 null。
  • 作为单独的根值:例如直接执行 JSON.stringify(undefined),返回值是 JS 基础类型 undefined,而不是字符串 "undefined"。
// 默认行为示例代码
const payload = {
  title: "任务详情",
  deadline: new Date("2026-11-18T12:00:00Z"),
  assignee: undefined,
  tags: ["技术", undefined, "置顶"]
};

const jsonResult = JSON.stringify(payload);
console.log(jsonResult);
控制台示例输出
{"title":"任务详情","deadline":"2026-11-18T12:00:00.000Z","tags":["技术",null,"置顶"]}

从输出中可以看到,assignee 键直接从结果中消失了,而 tags 数组中间的 undefined 项则变成了 null。在许多面向接口编程的场景中,后端框架可能会根据“键是否存在”来决定是否执行更新操作,字段消失很容易导致“字段未传递”与“字段设为空”产生歧义。

JS生成JSON时怎么处理Date和undefined类型
图 2:JSON.stringify 原生规则下 Date 与 undefined 的处理逻辑和差异分析

二、方案一:使用 JSON.stringify 的 replacer 函数统一拦截

JSON.stringify 支持传入第二个参数:转换函数 replacer(key, value)。序列化引擎在访问每一个节点的属性时,都会先调用该函数。函数返回的值将作为实际被序列化的内容;如果返回 undefined,该属性就会被剔除。

特别注意(Date 拦截陷阱):在 replacer(key, value) 中,参数 value 是经过 toJSON() 转换后的值。因为 Date 原型自带 toJSON,所以进入 replacer 时,value 已经变成了 ISO 字符串,直接使用 value instanceof Date 会返回 false!正确做法是通过当前执行上下文 this[key] 来访问未被转换前的原始属性。

完整实现代码

下面的示例展示了如何同时解决两个问题:将对象中为 undefined 的键保留并转为 null,同时将 Date 对象统一转换为精确的毫秒时间戳。

function customReplacer(key, value) {
  // 1. 处理 undefined:如果值为 undefined,返回 null 以保留键名
  if (value === undefined) {
    return null;
  }

  // 2. 处理 Date:通过 this[key] 获取转换前的原生对象
  // 必须排除空键根节点(首次调用时 key 为 "",this 为包含根对象的包裹对象)
  if (key !== "" && this[key] instanceof Date) {
    // 这里可以按需定制:返回时间戳 getTime(),或者自定义格式化字符串
    return this[key].getTime();
  }

  // 3. 其他常规类型正常返回
  return value;
}

// 验证测试
const data = {
  userName: "林晓",
  createTime: new Date("2026-11-18T08:30:00+08:00"),
  department: undefined,
  permissions: ["read", undefined, "write"]
};

const result = JSON.stringify(data, customReplacer, 2);
console.log(result);
控制台示例输出(带格式缩进)
{
  "userName": "林晓",
  "createTime": 1794961800000,
  "department": null,
  "permissions": [
    "read",
    null,
    "write"
  ]
}

通过检查 this[key],我们成功在 createTime 上拿到了原生的 Date 实例,将其格式化为毫秒时间戳(而不是默认的 UTC 字符串);同时,原先会被直接丢弃的 department 键被安全转换成了 null,在输出中完整保留了数据结构。

JS生成JSON时怎么处理Date和undefined类型
图 3:replacer 拦截流水线的执行逻辑与 Date/undefined 条件分支

三、方案二:对象自定义 toJSON 方法与原型扩展

当序列化一个对象时,JSON.stringify 会优先探测该对象是否拥有 toJSON() 方法。若存在,引擎将以调用 toJSON() 后的返回值作为序列化标的。这种模式特别适合在业务实体(Entity)或数据传输对象(DTO)中封装自洽的序列化逻辑。

1. 在自定义业务类中实现 toJSON

如果数据通过 ES6 Class 或构造函数进行建模,直接在类内部定义 toJSON 是最干净、内聚性最高的方式:

class OrderItem {
  constructor(skuId, createdTime, note) {
    this.skuId = skuId;
    this.createdTime = createdTime; // Date 实例
    this.note = note;               // 可能为 undefined
  }

  // 显式声明序列化行为
  toJSON() {
    return {
      skuId: this.skuId,
      // 将 Date 转为秒级或毫秒级时间戳
      createdTimestamp: this.createdTime instanceof Date ? this.createdTime.getTime() : null,
      // 若 note 为 undefined,显式回退为 null 保留字段
      note: this.note !== undefined ? this.note : null
    };
  }
}

const item = new OrderItem("SKU-9901", new Date(), undefined);
console.log(JSON.stringify(item));
// 示例输出:{"skuId":"SKU-9901","createdTimestamp":1794961800000,"note":null}

2. 修改 Date 原型的 toJSON(全局生效的权衡)

有些项目希望全局所有 Date 实例在调用 JSON.stringify 时都自动变成时间戳,开发者可能会选择重写 Date.prototype.toJSON:

// 全局重写:将所有 Date 默认序列化为毫秒时间戳
Date.prototype.toJSON = function() {
  return this.getTime();
};

const record = { time: new Date() };
console.log(JSON.stringify(record)); 
// 示例输出:{"time":1794961800000}
注意事项:直接修改 Date.prototype.toJSON 属于全局 Monkey Patch(猴子补丁)。如果在项目中引入了依赖标准 ISO 8601 字符串的第三方依赖库(如某些图表库或上报 SDK),此举可能导致第三方模块异常。因此,非必要不建议直接篡改原生原型,优先推荐在局部使用 replacer 或独立 DTO 类。
JS生成JSON时怎么处理Date和undefined类型
图 4:toJSON 方法在序列化管线中的最高优先级与执行层级关系

四、方案三:序列化前的深拷贝预处理与反序列化还原

如果数据结构较为深层,或者需要处理多种复杂规则(例如同时将空字符串或 undefined 统一定制,并将嵌套的 Date 对象统一处理),编写一个轻量的前置转换函数也是非常直观的做法。该方法不侵入原生原型,也不依赖 this[key] 的特殊上下文。

1. 前置深拷贝转换器

function sanitizeForJSON(obj) {
  // 处理基础类型或 null
  if (obj === null || typeof obj !== "object") {
    return obj === undefined ? null : obj;
  }

  // 针对 Date 实例进行特定转换(例如时间戳)
  if (obj instanceof Date) {
    return obj.getTime();
  }

  // 针对数组进行递归处理
  if (Array.isArray(obj)) {
    return obj.map(item => sanitizeForJSON(item));
  }

  // 针对普通对象递归遍历所有自有属性
  const result = {};
  for (const key of Object.keys(obj)) {
    const val = obj[key];
    // 显式将 undefined 转换为 null,确保键名不丢失
    result[key] = val === undefined ? null : sanitizeForJSON(val);
  }
  return result;
}

const originalData = {
  id: 101,
  meta: {
    createdAt: new Date("2026-11-18T10:00:00Z"),
    extraInfo: undefined
  }
};

const cleanObj = sanitizeForJSON(originalData);
const jsonOutput = JSON.stringify(cleanObj);
console.log(jsonOutput);
// 示例输出:{"id":101,"meta":{"createdAt":1794996000000,"extraInfo":null}}

2. 对应接收端的反向还原(reviver 机制)

序列化完成后,接收端解析时同样需要考虑类型还原。通过 JSON.parse 的第二个参数 reviver(key, value),可以将符合日期格式的字符串或时间戳重新实例化为 Date 对象:

// 针对 ISO 字符串的反序列化恢复
const isoRegex = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d+)?Z$/;

function dateReviver(key, value) {
  if (typeof value === "string" && isoRegex.test(value)) {
    return new Date(value);
  }
  return value;
}

const parsedObj = JSON.parse(jsonResult, dateReviver);
console.log(parsedObj.deadline instanceof Date); // true

五、综合对比与选型指南

在实际工程开发中,应根据项目架构、团队约定以及运行环境选择最合适的方案:

对比维度 方案一:replacer 拦截函数 方案二:定义 toJSON 方法 方案三:前置递归转换器
生效范围 单次 JSON.stringify 调用生效 绑定在特定 Class 或对象实例上 显式调用转换函数后生效
Date 处理方式 需通过 this[key] 读取原始实例 直接在方法内部处理 this 递归直接检测 instanceof Date
undefined 保留 直接判断并返回 null 保留键名 在返回值对象中显式映射键名 递归检测并将值赋为 null
代码侵入性 极低,无任何副作用 低(原型重写除外,类方法内聚度高) 极低,纯函数转换
推荐使用场景 通用的 API 统一请求拦截层或工具函数 具有完备领域模型(Domain/DTO)的项目 复杂多层异构数据、全量数据清洗任务
JS生成JSON时怎么处理Date和undefined类型
图 5:Date 与 undefined 序列化方案选型依据与避坑检查项

实用工具推荐

电子包浆

绿化、压缩、噪点和虚拟水印,自由调节做旧程度。

使用 ›
图片压缩

选择画质和输出格式,预览压缩前后的大小。

使用 ›
相关文章