Zod Codecs完全教程：用两行代码实现数据的双向编码解码（encode/decode）

Zod Codecs完全教程用两行代码实现数据的双向编码解码encode/decode【免费下载链接】zodTypeScript-first schema validation with static type inference项目地址: https://gitcode.com/GitHub_Trending/zo/zodZod是 TypeScript 生态中最流行的 schema 校验库而Zod Codecs自zod4.1引入是它最实用的新特性之一用一行z.codec()就能定义数据的双向转换decode把外部数据解码成你喜欢的类型encode再编码回去轻松搞定网络请求里 JSON 字符串与 JavaScript 对象之间的来回转换。为什么需要 Zod Codecs做前后端开发时你一定遇到过这种尴尬服务器发来的是 ISO 时间字符串2024-01-15T10:30:00.000Z代码里却想直接用Date对象表单提交来的数字是字符串42.5业务逻辑需要的是number发请求前又得把它们老老实实转回字符串传统做法是两头各写一堆new Date(...)和.toISOString()转换代码枯燥且容易漏。Zod Codecs 的解决方案是把校验和双向转换合并进同一个 schema客户端和服务器共享一份定义decode/encode各管一个方向。两行核心代码z.codec() 基础用法创建一个 Codec 只需三步输入 schema、输出 schema、转换函数。以ISO 字符串 ↔ Date 对象为例const stringToDate z.codec( z.iso.datetime(), // 输入 schemaISO 日期字符串 z.date(), // 输出 schemaDate 对象 { decode: (isoString) new Date(isoString), // 解码字符串 → Date encode: (date) date.toISOString(), // 编码Date → 字符串 } );使用极其清爽stringToDate.decode(2024-01-15T10:30:00.000Z); // Date 对象 stringToDate.encode(new Date(2024-01-15T10:30:00.000Z)); // 字符串 实现细节z.codec()本质上是 packages/zod/src/v4/classic/schemas.ts 中的codec函数内部把decode/encode分别挂成管道pipe的正向与反向转换函数。parse 与 decode 的区别类型签名不同.parse()和.decode()在运行时行为完全相同但类型检查强度不同parse()接受unknown输入 —— 传错类型编译器不报错运行时才失败decode()/encode()输入强类型—— 传个数字进去TypeScript 直接标红stringToDate.parse(12345); // ✅ 编译通过运行时才炸 stringToDate.decode(12345); // ❌ 编译报错number 不能赋给 string正因为 encode/decode 隐含转换语义输入通常已是强类型Zod 选择把错误提前暴露到编译期。进阶技巧让 Codec 融入复杂结构1. 可组合性嵌套到对象和数组里Codec 就是普通 schema想放哪放哪const payloadSchema z.object({ startDate: stringToDate }); payloadSchema.decode({ startDate: 2024-01-15T10:30:00.000Z }); // { startDate: Date }一个对象 schema 就能让整包数据自动完成双向转换这是网络边界场景API 请求/响应最大的价值点。2. z.invertCodec()一键反转方向有了stringToDate想要反方向的dateToString不用重写const dateToString z.invertCodec(stringToDate);⚠️ 注意它只反转你传入的那一层 codec不会递归反转嵌套在其他 schema 里的 codec嵌套层需要在使用处分别反转。3. 异步与安全变体和.transform()一样支持异步转换函数也有一整套安全APIstringToDate.decodeAsync(2024-01-15T10:30:00.000Z); // PromiseDate stringToDate.safeDecode(2024-01-15T10:30:00.000Z); // { success: true, data: Date } | { success: false, error: ZodError }4. 内置的 stringbool现成的双向转换器z.stringbool()早于 Codecs 存在如今内部已用 codec 重新实现可把true/false/yes/no与布尔值互相转换const sb z.stringbool({ truthy: [yes, y], falsy: [no, n] }); sb.decode(yes); // true sb.encode(false); // no取数组第一个元素避坑指南encode 方向的规则细节这是新手最容易踩坑的部分规则可以总结为特性decode正向encode反向.refine()/.min()等校验✅ 执行✅ 执行两遍校验.default()/.prefault()✅ 应用❌ 不应用.catch()✅ 应用❌ 不应用.transform()✅ 执行❌直接抛运行时错误几个关键细节default 只在正向生效。z.string().default(hello)对decode(undefined)返回hello但encode(undefined)会报错——因为加了默认值后输入类型才变成| undefined而 encode 的入参是强类型的输出侧。transform 是单向的。schema 里任何.transform()都会让encode()抛出运行时错误不是 ZodError看到Encountered unidirectional transform during encode就该去查是谁加了 transform。refine 是双向的。比如stringToDate.refine(date date.getFullYear() 2000)encode 一个 1999 年的日期同样会触发校验失败。常用 Codec 配方直接抄作业官方文档整理了一批经过测试的现成实现建议你复制到自己的项目里按需修改完整清单见 packages/docs/content/codecs.mdxstringToNumber/stringToInt字符串转数字如decode(42.5) 42.5epochSecondsToDateUnix 时间戳秒与Date互转json(schema)把 JSON 字符串解析成结构化数据并反序列化回去出错时通过ctx.issues抛出带路径的invalid_format错误base64ToBytes/hexToBytesbase64、十六进制字符串与Uint8Array互转stringToURLURL 字符串与URL对象互转uriComponent基于encodeURIComponent/decodeURIComponent的组件编码一个最典型的 JSON codecconst jsonCodec (schema: any) z.codec(z.string(), schema, { decode: (jsonString, ctx) { try { return JSON.parse(jsonString); } catch (err: any) { ctx.issues.push({ code: invalid_format, format: json, message: err.message }); return z.NEVER; } }, encode: (value) JSON.stringify(value), });总结需求用这个数据进来时转换 校验decode()等价于parse()数据出去时序列化encode()反向 codecz.invertCodec()不想抛异常safeDecode()/safeEncode()字符串布尔值z.stringbool()Zod Codecs 的核心理念一份 schema双向转换客户端和服务器共用。掌握z.codec()的两行基本语法 encode 方向的规则细节就能覆盖 90% 的场景。更多 API 细节可查阅官方文档 packages/docs/content/codecs.mdx核心实现位于 packages/zod/src/v4/core/schemas.ts。【免费下载链接】zodTypeScript-first schema validation with static type inference项目地址: https://gitcode.com/GitHub_Trending/zo/zod创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考