Keyv自定义序列化教程：超越JSON，支持更多数据类型-编程实验室

Keyv自定义序列化教程：超越JSON，支持更多数据类型

【免费下载链接】keyvjaredwray/keyv: 这是一个分布式键值存储库，用于在多个节点上存储数据。适合用于需要分布式存储和访问的场景。特点：易于使用，支持多种数据存储和访问方式，具有高性能和可扩展性。项目地址: https://gitcode.com/gh_mirrors/ke/keyv

Keyv是一个强大的分布式键值存储库，专为需要高性能、可扩展存储的场景设计。作为现代化的键值存储解决方案，Keyv提供了灵活的自定义序列化功能，让你超越传统的JSON限制，支持更多JavaScript原生数据类型。无论是Date对象、Map、Set还是BigInt，Keyv的自定义序列化都能完美处理。

为什么需要自定义序列化？ 🤔

默认情况下，大多数键值存储库使用JSON作为序列化格式。但JSON有其局限性——它无法正确处理JavaScript中的许多原生类型。当你存储一个Date对象时，JSON会将其转换为字符串；当你存储一个Map或Set时，JSON会将其转换为普通对象，丢失了原始结构。

Keyv通过可插拔的序列化系统解决了这个问题。你可以选择适合你需求的序列化器，或者创建自己的序列化器来支持特定的数据类型。

Keyv内置序列化器对比 📊

1. 默认JSON序列化器 (KeyvJsonSerializer)

Keyv内置的JSON序列化器已经比标准JSON.stringify/parse更强大。它支持：

Buffer/Uint8Array- 自动转换为base64编码字符串
BigInt- 保留大整数类型
嵌套对象和数组- 完全支持

import Keyv from 'keyv'; const keyv = new Keyv(); // 默认使用KeyvJsonSerializer // 存储Buffer数据 await keyv.set('buffer', Buffer.from('hello')); const buffer = await keyv.get('buffer'); console.log(buffer instanceof Buffer); // true // 存储BigInt await keyv.set('bigint', 9007199254740993n); const bigint = await keyv.get('bigint'); console.log(typeof bigint); // 'bigint'

2. SuperJSON序列化器 (@keyv/serialize-superjson)

SuperJSON提供了更全面的类型支持，特别适合需要保留复杂JavaScript类型的场景：

npm install @keyv/serialize-superjson

支持的数据类型：

✅ Date对象（保留为Date，不是字符串）
✅ RegExp正则表达式
✅ Map和Set集合
✅ BigInt大整数
✅ undefined值
✅ Error对象
✅ URL对象

import Keyv from 'keyv'; import { superJsonSerializer } from '@keyv/serialize-superjson'; const keyv = new Keyv({ serialization: superJsonSerializer }); // 存储Date对象 const now = new Date(); await keyv.set('currentDate', now); const retrievedDate = await keyv.get('currentDate'); console.log(retrievedDate instanceof Date); // true console.log(retrievedDate.getTime() === now.getTime()); // true // 存储Map集合 const userMap = new Map([ ['id', 123], ['name', 'Alice'], ['active', true] ]); await keyv.set('userMap', userMap); const retrievedMap = await keyv.get('userMap'); console.log(retrievedMap instanceof Map); // true console.log(retrievedMap.get('name')); // 'Alice'

3. MessagePack序列化器 (@keyv/serialize-msgpackr)

MessagePack是一种高效的二进制序列化格式，比JSON更紧凑、解析更快：

npm install @keyv/serialize-msgpackr

支持的数据类型：

✅ Date对象
✅ RegExp正则表达式
✅ Map和Set集合
✅ Error对象
✅ undefined值
✅ NaN、Infinity、-Infinity特殊值

import Keyv from 'keyv'; import { msgpackrSerializer } from '@keyv/serialize-msgpackr'; const keyv = new Keyv({ serialization: msgpackrSerializer }); // 存储特殊数值 await keyv.set('specialNumbers', { nan: NaN, infinity: Infinity, negativeInfinity: -Infinity }); const numbers = await keyv.get('specialNumbers'); console.log(Number.isNaN(numbers.nan)); // true console.log(numbers.infinity === Infinity); // true

Keyv项目的垂直Logo，展示了其现代化的设计风格

如何选择适合的序列化器？ 🎯

性能考虑

msgpackr：二进制格式，序列化/反序列化速度最快，数据体积最小
SuperJSON：JSON格式扩展，性能接近原生JSON，但支持更多类型
内置JSON：性能良好，支持Buffer和BigInt

数据类型需求

需要支持Date、Map、Set：选择SuperJSON或msgpackr
需要支持BigInt：选择SuperJSON或内置JSON
需要支持NaN/Infinity：选择msgpackr
只需要Buffer和基本类型：内置JSON足够

兼容性考虑

需要与其他系统交互：SuperJSON（标准JSON格式）
纯JavaScript环境：msgpackr或SuperJSON
需要最小数据体积：msgpackr

创建自定义序列化器 🛠️

Keyv的序列化系统设计得非常灵活。你可以轻松创建自己的序列化器，只需要实现KeyvSerializationAdapter接口：

import Keyv from 'keyv'; // 自定义序列化器接口 const customSerializer = { stringify(object) { // 自定义序列化逻辑 return JSON.stringify({ data: object, timestamp: Date.now(), version: '1.0' }); }, parse(data) { // 自定义反序列化逻辑 const parsed = JSON.parse(data); return parsed.data; } }; // 使用自定义序列化器 const keyv = new Keyv({ serialization: customSerializer });

实际案例：支持自定义类

假设你有一个自定义的User类：

class User { constructor(id, name, email) { this.id = id; this.name = name; this.email = email; this.createdAt = new Date(); } get displayName() { return `${this.name} (${this.email})`; } } // 创建支持User类的序列化器 const userSerializer = { stringify(object) { if (object instanceof User) { return JSON.stringify({ __type: 'User', id: object.id, name: object.name, email: object.email, createdAt: object.createdAt.toISOString() }); } return JSON.stringify(object); }, parse(data) { const parsed = JSON.parse(data); if (parsed && parsed.__type === 'User') { const user = new User(parsed.id, parsed.name, parsed.email); user.createdAt = new Date(parsed.createdAt); return user; } return parsed; } }; // 使用自定义序列化器 const keyv = new Keyv({ serialization: userSerializer }); const user = new User(1, 'Alice', 'alice@example.com'); await keyv.set('user1', user); const retrievedUser = await keyv.get('user1'); console.log(retrievedUser instanceof User); // true console.log(retrievedUser.displayName); // 'Alice (alice@example.com)'

Keyv项目的水平Logo，适合在网站头部或文档中使用

序列化与压缩的结合使用 ⚡

Keyv支持序列化器和压缩器的链式使用。数据处理的顺序是：序列化 → 压缩 → 存储。读取时的顺序相反：解压 → 反序列化。

import Keyv from 'keyv'; import { superJsonSerializer } from '@keyv/serialize-superjson'; import { gzipCompression } from '@keyv/compress-gzip'; // 同时使用序列化和压缩 const keyv = new Keyv({ serialization: superJsonSerializer, compression: gzipCompression }); // 存储大量数据时自动压缩 const largeData = { users: Array.from({ length: 1000 }, (_, i) => ({ id: i, name: `User ${i}`, createdAt: new Date(), tags: new Set(['active', 'premium']) })), metadata: new Map([ ['total', 1000], ['lastUpdated', new Date()] ]) }; await keyv.set('largeDataset', largeData); const retrieved = await keyv.get('largeDataset'); console.log(retrieved.users[0].createdAt instanceof Date); // true

禁用序列化 🚫

在某些情况下，你可能希望完全禁用序列化。这对于内存存储特别有用，可以避免不必要的序列化开销：

const keyv = new Keyv({ serialization: false }); // 直接存储对象，不进行序列化 const complexObject = { date: new Date(), map: new Map([['key', 'value']]), set: new Set([1, 2, 3]) }; // 注意：这只适用于内存存储 // 对于需要持久化的存储后端，必须使用序列化器