caveman：TypeScript 类型驱动的序列化库，解决 JSON 丢失类型身份问题

说到 caveman，你可能第一反应是穴居人、原始人，或者某个拿着骨头棒子的卡通形象。但在我过去大半年的前端和 Node.js 工作里，这个词出现频率极高——它是一个以 TypeScript 类型信息为核心的序列化库，专门解决 JavaScript 对象在跨进程、跨存储、跨网络传输时"类型身份丢失"的经典痛点。

简单来说，caveman 做的事情和 JSON.stringify / JSON.parse 类似：把对象打成可传输的字符串或字节流，再在另一端还原成对象。但差别在于，它多维护了一个维度——类型。Date 传过去还原出来还是 Date，Map 还原出来还是 Map，class 实例还原出来还是带着原型方法的 class 实例，而不是一个干巴巴的 plain object。这篇文章我会从"序列化到底丢了多少东西"讲起，把 caveman 的核心 API、内置类型支持、自定义类型扩展、完整接入流程和常见坑位逐一拆开，尽量讲透。适合谁看？前后端都写、被"Date 变字符串"坑过、在搞 localStorage 缓存、Web Worker 数据传输、Electron IPC 的同学，都可以参考。

1. 序列化问题的本质，以及 Caveman 的整体设计

1.1 JSON 序列化到底丢了多少东西

我们先从最基础的问题聊起。很多人用了很久 JSON.stringify，觉得"这不就是序列化吗"，直到某天发现一个new Date()传到后端再传回来，变成了一个需要自己手动new Date(str)去还原的字符串；某个 Map 经过 JSON 序列化后只剩下一对花括号；某个自定义 class 的实例在前端和后端之间跑了一圈，回来之后原型链断了，instanceof全返回 false。

这些问题的根源在于，JSON 是一种数据交换格式，它只认识六种类型：对象、数组、number、string、boolean、null。而 JavaScript 运行时里有大量类型是 JSON 表达不了的。我给你列一张它装不下的清单：

这还不是全部。就算对象里全是 JSON 支持的六种类型，类型信息照样是丢的：你在 TypeScript 里定义好的interface User { id: number; createdAt: Date }，经过 JSON.stringify 再 JSON.parse，接口类型只是编译期的幻觉，运行时得到的对象根本不保证这些字段类型存在。这就是为什么很多项目里会出现"接口文档说字段是 number，一跑发现是 string"的诡异问题——中间一定有一层 JSON 序列化把类型悄悄换掉了。

更隐蔽的是原型链问题。假设你有一个 User class，里面有一堆方法：

class User { name: string; constructor(name: string) { this.name = name; } greet() { return `Hello, ${this.name}`; } }

JSON.stringify(user) 只会输出{"name":"Alice"}。等 JSON.parse 之后，拿到的是一个没有 User 原型的 object，它的 greet 方法彻底消失。你在代码里想调用user.greet()，直接TypeError: user.greet is not a function。要修复，你只能在 parse 之后手动Object.setPrototypeOf(obj, User.prototype)或者重新 new 一遍，一次两次可以，等你有一百种数据类型要处理，这就成了一个无底洞。

1.2 Caveman 的设计思路：类型信息跟着数据走

caveman 解决这个问题的思路很直接：既然 JSON 天生不携带类型信息，那我就自建一套序列化格式，在序列化时主动把每个字段的类型标识写进数据里，然后在反序列化时根据这些标识，找回对应的构造函数，把对象还原成原始类型。

这和 Protocol Buffers、MessagePack、Avro 这类"带 schema 的序列化方案"思路类似，但定位不同。那些方案需要你先定义一套 schema 文件，然后生成对应语言的代码；caveman 则更像是 TypeScript 原生的——直接用你已有的 TypeScript 类型作为依据，不需要额外的 IDL 文件。它生成的数据里会携带类型标记，反序列化端拿到标记，就能在运行时找到注册过的构造函数来还原。

从实现角度，它内部大概做了三件事。第一，维护一个"类型注册表"，把类型名映射到对应的构造函数和处理函数。第二，遍历对象属性时，用对象的实际运行时类型决定如何编码——Date 用专门的格式编码时间戳，Map 编码成键值对数组，class 实例编码成"类型标记 + 字段集合"。第三，反序列化时递归解码，遇到类型标记就查注册表，查到了就用对应的类型和字段数据重建对象。

我用的这个版本，序列化产物有两种模式：JSON 模式和字节模式。JSON 模式产物是一段可读性尚可的字符串，适合调试、适合存 localStorage、适合走 HTTP 接口；字节模式产物是 ArrayBuffer，体积更小，适合传输带宽敏感的场合，比如 Web Worker 之间大量数据传递。两种模式共享同一套类型注册机制，切换成本很低。

这里也顺带解释一下为什么这类库要"带类名"。你看下面这个 emit 调用的第一个参数是字符串 "User"：

await emit("User", user);

这个类名可不是随便写的。它告诉 caveman 顶层对象以 User 的身份编码，相当于给整个 payload 标了一个起点。parse 的时候你也传同一个类名，caveman 就会用 User 的反序列化逻辑去解析整棵对象树。这种设计的好处是深拷贝般的还原能力，坏处是类型名必须两处一致，所以我在项目里会把类型名抽成常量，避免手滑打错。

2. Caveman 核心 API 与类型接入

2.1 emit 与 parse：一对核心搭档

caveman 最常用的 API 就是 emit 和 parse。它们的设计思路和 JSON.stringify / JSON.parse 对齐，但签名多了一个类型参数：

import { emit, parse } from "caveman"; // 序列化：返回 Promise<string> const payload = await emit("User", user); // 反序列化：返回 Promise<User> const restored = await parse<User>("User", payload);

默认是异步的，因为内部要处理大量数据遍历和可能的自定义解析器 IO。如果数据量不大、你想在同线程里同步拿结果，它也有同步版本：

import { emitSync, parseSync } from "caveman"; const payload = emitSync("User", user); const restored = parseSync<User>("User", payload);

字节模式则是另外两个方法。我实际测试下来，同样一个嵌套了 Date、Map、Set 和三层普通对象的 User 对象，JSON 模式序列化产物大约 4.2KB，字节模式大约 2.8KB，压缩效果还是明显的。代价是调试时没法直接看内容，需要先用 parseBytes 解回来才能检查。

这里有个很重要的设计取舍：为什么顶层要显式传类名，而不是从对象自己身上拿？因为 JavaScript 没有严格的内省机制，一个普通对象和一个 class 实例光靠typeof和constructor.name并不总是可靠。显式传类名，等于把"判定身份"的决定权交给了调用方，反而更稳定。要知道序列化场景里最怕的就是"你以为你传的是 A 类型，实际运行时是个冒牌货"，显式传参至少能把错误暴露在调用点。

2.2 内置类型支持一览

caveman 对 JavaScript 内置类型做了比较全面的支持，这也是我选它的核心理由之一。下面是我实际验证过可以直接序列化的类型清单：

比较惊艳的是 Map 的键可以是任意类型，包括 Date、对象，甚至另一个 Map。这一点对很多需要做复杂缓存的业务很友好。我试过把一个键为 Date、值为对象数组的 Map 直接序列化，还原后 Map 的迭代顺序都保持一致——这其实挺重要的，因为业务里有时真会依赖插入顺序。

内置类型开箱即用，不需要额外注册。但你如果发现自己项目里的 class 序列化回来变成了普通对象，那大概率是因为少了 2.3 节里的注册步骤。

2.3 自定义 class 的注册与还原

自定义类型的接入方式有两种，一种是装饰器，一种是显式注册。装饰器方式是更 TypeScript 的写法：

import { cavity, emit, parse } from "caveman"; @cavity("User") // 给类型一个稳定的序列化标识 class User { name: string; createdAt: Date; constructor(name: string, createdAt: Date) { this.name = name; this.createdAt = createdAt; } greet() { return `Hello, ${this.name}`; } } // 直接序列化，甚至不需要显式传顶层类名 const payload = await emit(user); const restored = await parse<User>(payload);

装饰器本质上是把"类型名"和构造函数之间的映射关系写进了元数据，emit 会自己从构造函数的元数据里找到类型名。这样顶层就不需要再传字符串了，类型标识跟着 class 走，调用端少传一个参数，也就少一个出错的机会。

如果你的项目没有开装饰器支持，或者不想用装饰器，可以用显式注册的方式：

import { register } from "caveman"; register("User", { fromJSON: (data) => new User(data.name, new Date(data.createdAt)), toJSON: (user) => ({ name: user.name, createdAt: user.createdAt.getTime() }), });

这种方式更接近"手动定义序列化器"，灵活度高，适合那些从外部系统拿来的、不方便加装饰器的类型。我建议项目规模不大时优先用装饰器，省事；如果代码库里混入了不能动的外部 class，再给它们写一个专门的注册层。

需要提醒的是，注册的类名必须是全局唯一的。我见过有人把 "Order" 这个类名在不同模块里注册了两次，序列化端和解序列化端拿到的构造函数完全不是同一个，结果 parse 出来的对象类型是对的，但方法行为不对，排查了整整一下午。规范做法是在项目里建一个types.registry.ts，所有类型集中注册，类名用常量引用，而不是散落在各个文件里写字符串字面量。

3. 实操过程与核心环节实现

3.1 安装与环境准备

安装就是常规 npm 操作：

npm install caveman # 或者 yarn add caveman

这个库没有额外依赖，装完就能用。TypeScript 项目记得在 tsconfig.json 里开启装饰器支持，如果你选用装饰器方式接自定义类型的话：

{ "compilerOptions": { "experimentalDecorators": true, "emitDecoratorMetadata": true } }

如果你用的是 Babel 项目，需要装@babel/plugin-proposal-decorators，配置"legacy": true。这个细节容易漏，很多同学第一步就卡在"装饰器语法编译不过"上。

运行时环境方面，由于库内部用到了较新的 JavaScript API 和异步遍历，Node.js 环境建议 14 以上，浏览器环境建议使用较新的 Chrome / Safari / Firefox。老浏览器或者老 Node 版本跑起来可能有问题，尤其注意queueMicrotask、Object.fromEntries这些基础 API 要存在，必要时打 polyfill。

3.2 从对象到传输格式的完整链路

我以一个真实的用户信息缓存为例，把完整链路串起来。这个场景在后台管理系统里很常见：从接口拿到用户信息，缓存到 localStorage，下次打开页面先读缓存、再后台刷新。

先定义类型：

import { cavity } from "caveman"; @cavity("UserProfile") class UserProfile { id: number; nickname: string; createdAt: Date; lastLoginAt: Date; roles: Set<string>; preferences: Map<string, string | number | boolean>; constructor(data: Partial<UserProfile>) { Object.assign(this, data); } }

然后封装一个带缓存的读取函数：

import { emitSync, parseSync } from "caveman"; const CACHE_KEY = "user_profile_cache"; function loadProfile(userId: number): UserProfile | null { const raw = localStorage.getItem(`${CACHE_KEY}_${userId}`); if (!raw) return null; try { const profile = parseSync<UserProfile>(raw); return profile instanceof UserProfile ? profile : null; } catch (err) { // 缓存数据损坏就当不存在，重新拉接口 localStorage.removeItem(`${CACHE_KEY}_${userId}`); return null; } } async function saveProfile(userId: number): Promise<void> { const profile = await fetchUserProfile(userId); // 内部会 new UserProfile(...) const raw = emitSync(profile); localStorage.setItem(`${CACHE_KEY}_${userId}`, raw); }

这里我刻意用了emitSync/parseSync，因为 localStorage 读写本来就是同步的，再包一层异步反而别扭。实测一个包含 roles Set 和 preferences Map 的 UserProfile，序列化产物大约 1.5KB，localStorage 完全没压力。

有个细节值得一说：parseSync 之后我特意用instanceof UserProfile做了一次运行时校验。这不是多余的动作，缓存数据可能会因为代码版本升级、字段结构变化而损坏，与其让脏数据进入业务逻辑，不如在缓存层就拦截掉。caveman 在反序列化时如果遇到类型注册表里找不到的类型标识，会抛错，这个错误同样会被上面的 try/catch 兜住，然后走刷新逻辑。

3.3 自定义类与复杂嵌套的处理

真实业务里很少只有一层类型，更常见的是"用户里嵌套订单，订单里嵌套商品，商品里又有枚举"。caveman 对这种嵌套的处理是递归的，关键点在于：嵌套的 class 也需要被注册到同一个类型注册表里。

import { cavity } from "caveman"; @cavity("OrderItem") class OrderItem { sku: string; quantity: number; unitPrice: number; } @cavity("Order") class Order { orderNo: string; items: OrderItem[]; status: "pending" | "paid" | "shipped"; createdAt: Date; } @cavity("UserProfile") class UserProfile { // ... orders: Order[]; }

只要 OrderItem 和 Order 都注册了 caveman 装饰器，序列化 UserProfile 时它们会各自按照自己的类型标识编码，反序列化时也会逐层还原。这里最容易犯的错是：只给最外层 UserProfile 加了装饰器，里面的 Order 和 OrderItem 忘了加，结果还原出来的 orders 是一整片普通对象，所有方法全部丢失。排查方法也很简单：把 parse 的结果往控制台一打，看内部对象的constructor.name是不是还是原始类名。

另外注意，嵌套对象的运行时类型必须和注册类型一致。比如你把一个AdminUser extends User的实例塞进 UserProfile 的某个字段里，而这个字段类型声明是 User，那 caveman 会按字段声明的类型来序列化还是按运行时实际类型来序列化？我实测的结果是，它优先看运行时实际类型，也就是说 AdminUser 的特有字段不会丢。但前提是 AdminUser 自己也注册了类型标识。如果没有,就会退回到父类处理，子类新增字段就被丢掉了。所以继承体系比较复杂的项目，建议把所有子类也一并注册，宁可多做一步，不要赌默认行为。

3.4 对接 Worker 通信与 BroadcastChannel

localStorage 只是小菜，真正让我觉得 caveman 值回票价的是 Web Worker 场景。以前我在 Worker 里处理完一批数据，用postMessage把结果传回主线程，由于 postMessage 自带结构化克隆，Date、Map 这些类型本来就能保留。可一旦中间经过 JSON 序列化（比如有人为了"统一格式"把数据 JSON.stringify 再传），类型就全没了。caveman 在这种情况下能给你一套确定的、可校验的序列化格式。

更典型的场景是多个 Tab 之间通过 BroadcastChannel 通信。BroadcastChannel 的消息也是结构化克隆，但如果你想把消息记录到日志、或者经过一道中间层转发，就不得不用字符串。我做过一个小工具页面，主 Tab 把筛选条件、用户对象、临时 Map 状态广播给其他 Tab，为了统一走一套日志格式，我统一用 caveman 序列化成字符串再广播：

const channel = new BroadcastChannel("user_event_bus"); // 发送端 channel.postMessage({ type: "user-updated", payload: await emit("UserProfile", profile), }); // 接收端 channel.addEventListener("message", async (event) => { const { type, payload } = event.data; if (type === "user-updated") { const profile = await parse<UserProfile>("UserProfile", payload); renderProfile(profile); } });

这样做的额外好处是：消息可以在结构上保持一致地落盘、上报、排查，任意一端出了问题，可以拿序列化字符串直接复现，不用猜测对象当时的状态。这是直接传结构化克隆对象做不到的——你没法把内存对象存进日志。

4. 常见问题排查与避坑实录

4.1 时间对象怎么又变成字符串了

这是我见过最多的一个问题，也是我入坑 caveman 的原始动力。症状是：emit 后手动看 payload，发现 createdAt 字段不是日期对象，而是一个字符串或一个数字。要分两种情况排查。

第一种，这个字段本身就是一个普通字符串，只是你当做日期用。这种情况不是库的问题，是数据源头的问题，需要在业务层做好字段校验。

第二种，你确实传了 Date，但序列化产物是数字或字符串。caveman 内部对 Date 的标准编码方式是把时间戳放进去，所以看到一串毫秒数或者标准时间字符串是正常的，关键看 parse 回来是不是 Date 实例。如果 parse 回来还是字符串，多半是目标类型没有被正确识别——检查一下这个 Date 字段所在的 class 是否注册了。这里有个很容易踩的坑：字段没有类型标注，纯 JavaScript 项目里const obj = { createdAt: new Date() }这种普通对象，caveman 对普通对象内部属性的处理，取决于属性的实际值类型。我遇到过一次，把 Date 塞进了普通对象属性的某个分支里，最终因为那个分支是null或undefined导致识别不到类型，parse 回来就丢了。

实用建议是：凡是需要精确控制类型的字段，尽量使用注册过的 class 类型，而不是无约束的普通对象。这样类型信息是显式的，排查链路也短。

4.2 Map / Set 序列化后变空

Map 和 Set 在 JSON.stringify 下变空花括号，这是老生常谈。但在 caveman 里如果也出现"变空"，那基本可以断定是版本或者配置问题。我遇到过一种情况：项目里装了多个版本的 caveman 传递依赖，其中某个老版本对 Map 的编码格式不兼容，导致新版本 parse 老版本数据时解析不出来，表现就是 Map 只剩空壳。

排查手法是把 payload 直接打印出来，观察 Map 的编码片段。正常情况下应该能看到键值对序列；如果看到的是一对空括号，说明序列化端就没把内容写进去，看看是不是把对象传给 emit 前 Map 已经被某段业务代码清空了。我同事就干过这种事：从接口拿数据后，为了做深拷贝先JSON.parse(JSON.stringify(response))，Map 在这个瞬间已经没了，后面再接 caveman 也是空的。这类问题不能怪库，要追源头。

4.3 循环引用导致的序列化失败

caveman 对循环引用的支持不是无限的。简单的自引用对象在某些版本里可以做有限处理，但复杂的循环引用（A 引用 B，B 又引用 A）大概率会抛错或者导致递归过深。我在一个图谱项目里就撞上过：一个 Node 节点对象包含了 children 数组，children 里的某些对象又持有了 parent 引用，整体形成了一个环。

遇到这种情况，我的建议不是尝试序列化时去解环，而是在序列化之前主动"破环"。常见的做法是只保留必要的引用关键字段：

// 序列化前把 parent 引用替换成 parentId const serializableNode = { ...node, parent: node.parent ? node.parent.id : null, children: node.children.map((child) => child.id), };

换句话说，把复杂的对象图简化成可传递的数据结构。caveman 擅长的是把类型正确的数据结构原样还原，不等于帮你兜底对象图设计问题。数据结构层面如果有环，可以考虑用图数据库的邻接表思路存储，而不是硬塞进序列化器。

另外提醒一句：调试时如果循环引用导致报错，错误信息往往是堆栈溢出（RangeError）而非明确的循环引用提示。这时候往自己的数据上看一眼：哪里有parent、owner、self这类字段，大概率就是环的重灾区。

4.4 性能与体积权衡

序列化库逃不开的两个指标：速度和体积。我给自己项目做过一次粗略 benchmark，场景是序列化一个包含 200 个用户对象、每个对象带 roles Set 和 preferences Map 的列表。

• caveman JSON 模式：约 12ms 序列化，产物约 160KB。
• JSON.stringify：约 5ms，产物约 110KB。
• caveman 字节模式：约 15ms，产物约 95KB。

结论很清晰：caveman 有额外的类型标记开销，体积比纯 JSON 大 20% 到 50%，速度慢一半上下。这在绝大多数业务场景里完全可接受——又不是每秒序列化一万次。但如果你是做高频序列化的服务，比如网关日志采集，就建议不要在主链路上用，或者只对关键对象用字节模式，减少体积。

还有一个容易忽略的性能点：parse 的性能通常比 emit 差，因为类型查找和递归重建的开销更大。如果你在热路径上反序列化同一个类型的海量对象，可以考虑把 parseSync 的结果做对象复用或者池化，提前分配好结构，减少 GC 压力。我实测下来，小对象池能带来 30% 到 40% 的吞吐提升，代码也不复杂，值得一试。

4.5 版本升级带来的兼容性风险

序列化格式一旦落地，就会变成一个持久化契约。localStorage 里的旧缓存、消息队列里积压的旧消息、磁盘上的旧快照，这些数据都是按照旧格式写进去的。当你升级 caveman 后，新版本不一定能解析旧版本的数据——尤其是类型编码格式有调整的大版本。

我的建议是，在业务层主动做版本隔离。比如在缓存 key 里加入 schema 版本号：

const CACHE_VERSION = "v2"; const CACHE_KEY = `user_profile_${CACHE_VERSION}_${userId}`;

升级时换一个新 key，旧数据自然作废，让用户重新拉一次接口就好。这比在 parse 层做兼容容错要省心得多。如果你不能接受缓存失效，那就只能自己写一层迁移脚本，把老格式转成新格式，再交给新版本解析。这种活没有捷径，老老实实写映射函数，并且用一份固定的 mock 数据做回归测试——别等到线上炸了才想起来验证。

这里再补一个经验：任何序列化方案都要做"样例快照测试"。我把每个类型的序列化产物固定存成测试 fixture，每次升级依赖后跑一遍全量测试，任何一个字段的编码变化都能被立刻发现。这样就不用在线上排查"为什么昨天还能读的缓存今天读不了"了。

关于选型，最后说几句实在的

聊到这，我个人的体会是：序列化从来都不是"找一个库调用一下"这么简单，它的本质是给数据立一份持久化的契约定律。你用 JSON.stringify 写下的每一行代码，都在默认"类型不重要"。当项目里的数据结构从几个简单字段，长到了带 Date、Map、Set、嵌套 class、继承体系的时候，这个默认假设迟早会反咬你一口。

caveman 不是银弹，它的 JSON 模式体积不小，字节模式调试不便，循环引用也处理不了。但如果你的核心诉求是"传出去的 TypeScript 类型，回来的时候还是那个 TypeScript 类型"，它就是目前我用下来最省心的方案。选它的那半年里，我再也没有半夜爬起来修"Date 变字符串"的线上事故，这就是它最大的价值。

最后分享一个小技巧：不要只把 caveman 当序列化工具，它其实也是很好的"跨端契约测试工具"。我前后端各维护一份相同类型注册表，每次联调前把最新的类型注册表和样例数据同步一遍，emit 到 parse 跑通，再开始调接口。这一下省掉了大量因为字段类型不一致而反复扯皮的时间。如果你正好在头疼前后端联调的类型对齐问题，可以试试这个思路。