# Zod：TypeScript-First 模式验证 ## 概述 Zod 是一个 TypeScript 优先的验证库，使开发人员能够定义用于在运行时验证数据的模式，同时自动推断静态 TypeScript 类型。 Zod 具有零依赖性和 2kb 核心包（压缩），提供不可变、可组合的验证和全面的错误处理。 ## 安装面包加佐德 # 或面包加佐德 # 或面包加佐德 # 或纱线添加zod **要求**： * TypeScript v5.5+ 在 `tsconfig.json` 中带有 `"strict": true` * 佐德 4.x (4.1.12+) **重要**：此技能记录了 **Zod 4.x** 功能。以下 API 需要 Zod 4，在 Zod 3.x 中不可用： * `z.codec()` \- 双向转换 * `z.iso.date()`、`z.iso.time()`、`z.iso.datetime()`、`z.iso.duration()` \- ISO 格式验证器 * `z.toJSONSchema()` \- JSON 模式生成 * `z.treeifyError()`、`z.prettifyError()`、`z.flattenError()` \- 新的错误格式化助手 * `.meta()` \- 增强元数据（Zod 3.x 仅具有 `.describe()`） * 统一 `error` 参数 - 替换 `message`、`invalid_type_error`、`required_error`、`errorMap` 有关 Zod 3.x 兼容性或迁移指南，请参阅 ## 从 Zod v3 迁移到 v4 **加载 `references/migration-guide.md` 以获取完整的 v3 到 v4 迁移文档。** ### 快速总结 Zod v4 引入了重大更改以提高性能： * **错误定制** : 使用统一的 `error` 参数（替换 `message`、`invalid_type_error`、`required_error`） * **数字验证**：更严格 - 拒绝“无穷大”和不安全的整数 * **字符串格式** ：现在是顶级函数（`z.email()` vs `z.string().email()`） * **对象默认值**：即使在可选字段中也适用 * **已弃用的 API** ：使用 `.extend()` （不是 `.merge()`）、`z.treeifyError()` （不是 `error.format()`） * **函数验证** : 使用 `.implement()` 方法 * **UUID 验证**：更严格的 RFC 9562/4122 合规性 **→ 加载 `references/migration-guide.md` 用于：** 完成重大更改、迁移清单、逐步迁移策略、回滚说明 ## 核心概念 ### 基本使用模式从“zod”导入{z}； // 定义模式 const UserSchema = z.object({ 用户名：z.string(), 年龄：z.number().int().positive(), 电子邮件：z.string().email(), }); // 推断 TypeScript 类型 type User = z.infer; // 验证数据（出错时抛出） const user = UserSchema.parse(data); // 验证数据（返回结果对象） const 结果 = UserSchema.safeParse(data); if (结果.成功) { console.log(结果.数据); // 已输入！ } 否则{ 控制台.错误(结果.错误); // 佐德错误 } ### 解析方法根据错误处理需要使用适当的解析方法： * **`.parse(data)`** \- 无效输入时抛出 `ZodError`；成功时返回强类型数据 * **`.safeParse(data)`** \- 返回 `{ success: true, data }` 或 `{ success: false, error }` （无例外） * **`.parseAsync(data)`** \- 对于具有异步细化/转换的模式 * **`.safeParseAsync(data)`** \- 不会抛出异常的异步版本 **最佳实践**：使用 `.safeParse()` 来避免 try-catch 块并利用可区分的联合。 ## 原始类型 ### 字符串 z.string() // 基本字符串 z.string().min(5) // 最小长度 z.string().max(100) // 最大长度 z.string().length(10) // 精确长度 z.string().email() // 电子邮件验证 z.string().url() // URL 验证 z.string().uuid() // UUID 格式 z.string().regex(/^\d+$/) // 自定义模式 z.string().startsWith("pre") // 前缀检查 z.string().endsWith("suf") // 后缀检查 z.string().trim() // 自动修剪空格 z.string().toLowerCase() // 自动小写 z.string().toUpperCase() // 自动大写 // ISO 格式 (Zod 4+) z.iso.date() // YYYY-MM-DD z.iso.time() // 时:分:秒 z.iso.datetime() // ISO 8601 日期时间 z.iso.duration() // ISO 8601 持续时间 // 网络格式 z.ipv4() // IPv4 地址 z.ipv6() // IPv6 地址 z.cidrv4() // IPv4 CIDR 表示法 z.cidrv6() // IPv6 CIDR 表示法 // 其他格式 z.jwt() // JWT 令牌 z.nanoid() // 纳米机器人 z.cuid() // CUID z.cuid2() // CUID2 z.ulid() // ULID z.base64() // Base64编码 z.hex() // 十六进制 ### 数字 z.number() // 基本数字 z.number().int() // 仅限整数 z.number().positive() // > 0 z.number().nonnegative() // >= 0 z.number().负数() // < 0 z.number().nonpositive() // <= 0 z.number().min(0) // 最小值 z.number().max(100) // 最大值 z.number().gt(0) // 大于 z.number().gte(0) // 大于或等于 z.number().lt(100) // 小于 z.number().lte(100) // 小于或等于 z.number().multipleOf(5) // 必须是 5 的倍数 z.int() // z.number().int() 的简写 z.int32() // 32位整数 z.nan() // NaN 值 ### 强制（类型转换） z.coerce.string() // 转换为字符串 z.coerce.number() // 转换为数字 z.coerce.boolean() // 转换为布尔值 z.coerce.bigint() // 转换为bigint z.coerce.date() // 转换为日期 // 示例：解析查询参数 const QuerySchema = z.object({ 页面：z.coerce.number().int().positive(), 限制：z.coerce.number().int().max(100).default(10), }); // "?page=5&limit=20" -> { 页数: 5, 限制: 20 } ### 其他原语 z.boolean() // 布尔值 z.date() // 日期对象 z.date().min(new Date("2020-01-01")) z.date().max(new Date("2030-12-31")) z.bigint() // BigInt z.symbol() // 符号 z.null() // 空 z.undefined() // 未定义 z.void() // 无效（未定义） ## 复杂类型 ### 对象 const PersonSchema = z.object({ 名称： z.string(), 年龄：z.number(), 地址：z.object({ 街道：z.string(), 城市: z.string(), 国家: z.string(), }), }); type Person = z.infer; // 对象方法 PersonSchema.shape // 访问形状 PersonSchema.keyof() // 获取键的并集 PersonSchema.extend({ role: z.string() }) // 添加字段 PersonSchema.pick({ name: true }) // 选择特定字段 PersonSchema.omit({age: true }) // 省略字段 PersonSchema.partial() // 使所有字段可选 PersonSchema.required() // 使所有字段为必填项 PersonSchema.deepPartial() // 递归可选 // 严格对象与松散对象 z.strictObject({ ... }) // 不允许使用额外的键（抛出） z.object({ ... }) // 删除额外的键（默认） z.looseObject({ ... }) // 允许额外的键 ### 数组 z.array(z.string()) // 字符串数组 z.array(z.number()).min(1) // 至少 1 个元素 z.array(z.number()).max(10) // 最多 10 个元素 z.array(z.number()).length(5) // 正好 5 个元素 z.array(z.number()).nonempty() // 至少 1 个元素 // 嵌套数组 z.array(z.array(z.number())) // 数字[][] ### 元组 z.tuple([z.string(), z.number()]) // [字符串, 数字] z.tuple([z.string(), z.number()]).rest(z.boolean()) // [字符串, 数字, ...boolean[]] ### 枚举和文字 // 枚举 const RoleEnum = z.enum(["admin", "user", "guest"]); type Role = z.infer; //“管理员”| “用户”| “客人” // 文字值 z.literal("精确值") z.literal(42) z.literal(true) // 原生 TypeScript 枚举枚举水果 { 苹果，香蕉， } z.nativeEnum(水果) // 枚举方法 RoleEnum.enum.admin //“管理员” RoleEnum.exclude(["guest"]) // 排除值 RoleEnum.extract(["admin", "user"]) // 仅包含 ### 工会 // 基本联合 z.union([z.string(), z.number()]) // 可区分联合（更好的性能和类型推断） const ResponseSchema = z.discriminatedUnion("状态", [ z.object({ status: z.literal("success"), data: z.any() }), z.object({ status: z.literal("error"), message: z.string() }), ]); 类型响应 = z.infer<响应模式类型>; // { 状态：“成功”，数据：任意 } | { 状态：“错误”，消息：字符串 } ### 十字路口 const BaseSchema = z.object({ id: z.string() }); const ExtendedSchema = z.object({ name: z.string() }); const 组合 = z.intersection(BaseSchema, ExtendedSchema); // 等价于：z.object({ id: z.string(), name: z.string() }) ### 记录和地图 // 记录：具有键入键和值的对象 z.record(z.string()) // { [key: string]: string } z.record(z.string(), z.number()) // { [key: string]: number } // 部分记录（部分键可选） z.partialRecord(z.enum(["a", "b"]), z.string()) // 地图 z.map(z.string(), z.number()) // Map<字符串, 数字> z.set(z.string()) // 设置<字符串> ## 高级模式 **加载`references/advanced-patterns.md`以获取完整的高级验证和转换模式。** ### 快速参考 **改进**（自定义验证）： z.string().refine((val) => val.length >= 8, "太短"); z.object({ 密码, 确认密码 }).superRefine((data, ctx) => { /* ... */ }); **转换**（修改数据）： z.string().transform((val) => val.trim()); z.string().pipe(z.coerce.number()); **编解码器**（双向转换 - v4.1 中的新增功能）： const DateCodec = z.codec( z.iso.datetime(), z.日期(), { 解码：(str) => 新日期(str)，编码：(日期) => date.toISOString(), } ）； **递归类型**： const CategorySchema: z.ZodType = z.lazy(() => z.object({ 名称: z.string(), 子类别: z.array(CategorySchema) }) ）； **可选/可为空** ： z.string().可选() // 字符串 |未定义 z.string().nullable() // 字符串 |空 z.string().default("default") // 如果未定义则提供默认值 **只读和品牌**： z.object({ ... }).readonly() // 只读属性 z.string().brand<"UserId">() // 名义输入 **→ 加载 `references/advanced-patterns.md` 用于：** 完整的细化模式、异步验证、编解码器示例、可组合模式、条件验证、性能优化 ## 错误处理 **加载`references/error-handling.md`以获取完整的错误格式和自定义指南。** ### 快速参考 **错误格式化方法**： // 对于表单 const { fieldErrors } = z.flattenError(错误); // 对于嵌套数据 const tree = z.treeifyError(错误); const nameError = tree.properties?.user?.properties?.name?.errors?.[0]; // 用于调试 console.log(z.prettifyError(错误)); **自定义错误消息**（三个级别）： // 1. 模式级（最高优先级） z.string({ error: "自定义消息" }); z.string().min(5, "太短"); // 2. 每个解析级别 schema.parse(data, { 错误: (问题) => ({ 消息: "..." }) }); // 3.全局级别 z.config({ customError: (issue) => ({ message: "..." }) }); **本地化**（40 多种语言）： z.config(z.locales.es()); // 西班牙语 z.config(z.locales.fr()); // 法语 **→ 加载 `references/error-handling.md` 用于：** 完整的错误格式示例、自定义错误模式、本地化设置、错误代码参考 ## 类型推断 **加载`references/type-inference.md`以获取完整的类型推断和元数据文档。** ### 快速参考 **基本类型推断**： const UserSchema = z.object({ name: z.string() }); type User = z.infer; // { 名称: 字符串 } **输入与输出**（用于转换）： const TransformSchema = z.string().transform((s) => s.length); 输入类型 = z.input; // 字符串类型输出 = z.output; // 数量 **JSON 模式转换**： const jsonSchema = z.toJSONSchema(UserSchema, { 目标：“openapi-3.0”，元数据：真实， }); **元数据**： // 添加元数据 const EmailSchema = z.string().email().meta({ 标题：“电子邮件地址”，描述：“用户的电子邮件地址”， }); // 创建自定义注册表 const formRegistry = z.registry(); **→ 加载 `references/type-inference.md` 用于：** 完整的类型推断模式、JSON 模式选项、元数据系统、自定义注册表、品牌类型 ## 函数验证函数输入和输出： const AddFunction = z.function() .args(z.number(), z.number()) // 参数 .returns(z.number()); // 返回类型 // 实现类型化函数 const add = AddFunction.implement((a, b) => { 返回a+b； // 类型检查！ }); // 异步函数 const FetchFunction = z.function() .args(z.string()) .returns(z.promise(z.object({ data: z.any() }))) .implementAsync(异步(url) => { const 响应 = 等待 fetch(url); 返回response.json(); }); ## 常见模式 ### 环境变量 const EnvSchema = z.object({ NODE_ENV: z.enum(["开发", "生产", "测试"]), DATABASE_URL: z.string().url(), 端口: z.coerce.number().int().positive().default(3000), API_KEY: z.string().min(32), }); // 启动时验证 const env = EnvSchema.parse(process.env); // 现在使用类型化环境 console.log(env.PORT); // 数量 ### API 请求验证 const CreateUserRequest = z.object({ 用户名：z.string().min(3).max(20), 电子邮件：z.string().email(), 密码：z.string().min(8), 年龄：z.number().int().positive().Optional(), }); // 表达示例 app.post("/users", async (req, res) => { const 结果 = CreateUserRequest.safeParse(req.body); 如果（！结果。成功）{ 返回 res.status(400).json({ 错误：z.flattenError(result.error).fieldErrors, }); } const user =等待createUser(结果.data); res.json(用户); }); ### 表单验证 const FormSchema = z.object({ firstName: z.string().min(1, "需要名字"), lastName: z.string().min(1, "需要姓氏"), 电子邮件: z.string().email("无效电子邮件"), 年龄： z.coerce.number().int().min(18, "必须年满 18 岁"), 同意条款： z.literal(true, { errorMap: () => ({ message: "必须接受条款" }), }), }); type FormData = z.infer; ### 部分更新 const UserSchema = z.object({ id: z.string(), 名称： z.string(), 电子邮件：z.string().email(), }); // 对于 PATCH 请求：将除 id 之外的所有内容设为可选 const UpdateUserSchema = UserSchema.partial().required({ id: true }); 类型 UpdateUser = z.infer; // { id: 字符串;名称？：字符串；电子邮件？：字符串} ### 可组合模式 // 基本模式 const TimestampSchema = z.object({ 创建时间：z.date(), 更新时间：z.date(), }); const AuthorSchema = z.object({ 作者Id: z.string(), 作者姓名：z.string(), }); // 组合成更大的模式 const PostSchema = z.object({ id: z.string(), 标题: z.string(), 内容：z.string(), }).merge(TimestampSchema).merge(AuthorSchema); ## 生态系统整合 **加载`references/ecosystem-integrations.md`以获得完整的框架和工具集成指南。** ### 快速参考 **ESLint 插件**： * `eslint-plugin-zod-x` \- 强制执行最佳实践 * `eslint-plugin-import-zod` \- 强制导入样式 **框架集成**： * **tRPC** \- 端到端类型安全 API * **React Hook Form** \- 表单验证（参见 `react-hook-form-zod` 技巧） * **Prisma** \- 从数据库模型生成 Zod * **NestJS** \- DTO 和验证管道 **代码生成**： * **orval** \- OpenAPI → Zod * **Hey API** \- OpenAPI 到 TypeScript + Zod * **kubb** \- 带 codegen 的 API 工具包 **→ 加载`references/ecosystem-integrations.md`：** 设置说明、集成示例、Hono 中间件、Drizzle ORM 模式 ## 故障排除 **加载`references/troubleshooting.md`以获取完整的故障排除指南、性能提示和最佳实践。** ### 快速参考 **常见问题**： 1. 需要 TypeScript 严格模式 → 在 `tsconfig.json` 中启用 2. 大包大小 → 使用 `z.lazy()` 进行代码分割 3. 缓慢的异步改进 → 缓存或反跳 4. 循环依赖 → 使用 `z.lazy()` 5. 联合速度慢 → 使用 `z.discriminatedUnion()` 6. Transform 与 Refine 混淆 → 使用 `.refine()` 进行验证，使用 `.transform()` 进行修改 **性能提示**： * 使用 `.discriminatedUnion()` （比 `.union()` 快 5-10 倍） * 缓存模式实例 * 使用 `.safeParse()` （避免 try-catch 开销） * 延迟加载大型模式 **最佳实践**： * 在模块级别定义模式 * 使用类型推断（`z.infer`） * 添加自定义错误信息 * 在系统边界进行验证 * 构建小模式 * 带有`.meta()`的文档 **→ 加载`references/troubleshooting.md`：**详细的解决方案、性能优化、最佳实践、测试模式 ## 快速参考 // 基元 z.string()、z.number()、z.boolean()、z.date()、z.bigint() // 集合 z.array()、z.tuple()、z.object()、z.record()、z.map()、z.set() // 特殊类型 z.enum()、z.union()、z.discriminatedUnion()、z.intersection() z.literal()、z.any()、z.unknown()、z.never() // 修饰符 .可选（），.nullable（），.nullish（），.default（），.catch（） .readonly(), .brand() // 验证 .min()、.max()、.length()、.regex()、.email()、.url()、.uuid() .refine(), .superRefine() // 转换 .transform()、.pipe()、.codec() // 解析 .parse()、.safeParse()、.parseAsync()、.safeParseAsync() // 类型推断 z.infer<架构类型>、z.input<架构类型>、z.output<架构类型> // 错误处理 z.flattenError()、z.treeifyError()、z.prettifyError() // JSON 架构 z.toJSONSchema（模式，选项） // 元数据 .meta(), .describe() // 对象方法 .extend()、.pick()、.omit()、.partial()、.required()、.merge() ## 何时加载参考文献 **在以下情况下加载`references/migration-guide.md`：** * 从 Zod v3 升级到 v4 * 有关重大变更的问题 * 需要迁移清单或回滚策略 * 与已弃用的 API 相关的错误（`.merge()`、`error.format()` 等） * “Infinity”或不安全整数的数字验证问题 **在以下情况下加载`references/error-handling.md`：** * 需要格式化表单或UI的错误 * 实现自定义错误消息 * 关于 `z.flattenError()`、`z.treeifyError()` 或 `z.prettifyError()` 的问题 * 设置错误消息的本地化 * 需要错误代码参考或模式示例 **加载`references/advanced-patterns.md`时：** * 实施自定义改进或异步验证 * 需要双向转换（编解码器） * 使用递归类型或自引用数据 * 关于 `.refine()`、`.transform()` 或 `.codec()` 的问题 * 需要性能优化模式 * 实施条件验证 **加载`references/type-inference.md`时：** * 关于 TypeScript 类型推断的问题 * 需要为OpenAPI或AI生成JSON Schema * 实施表格或文档的元数据系统 * 需要类型安全元数据的自定义注册表 * 关于 `z.infer`、`z.input`、`z.output` 的问题 * 使用品牌类型确保 ID 安全 **加载`references/ecosystem-integrations.md`时：** * 与 tRPC、React Hook Form、Prisma 或 NestJS 集成 * 设置 ESLint 插件以获得最佳实践 * 从 OpenAPI（orval、Hey API、kubb）生成 Zod 模式 * 关于 Hono 中间件或 Drizzle ORM 的问题 * 需要特定于框架的集成示例 **在以下情况下加载`references/troubleshooting.md`：** * 遇到TypeScript严格模式错误 * 捆绑包大小问题或延迟加载需求 * 大型联合或异步改进的性能问题 * 关于循环依赖的问题 * 需要最佳实践或测试模式 * `.refine()` 和 `.transform()` 之间的混淆 ## 其他资源 * **官方文档**： * **GitHub**： * **TypeScript Playground** ： * **ESLint 插件（最佳实践）** ： * **tRPC 集成** : * **生态系统**： ** ** **生产说明**： * 软件包版本：4.1.12+（Zod 4.x 稳定版） * 零依赖 * 捆绑包大小：2kb（gzip 压缩） * 需要 TypeScript 5.5+ * 需要严格模式 * 最后验证: 2025-11-17 * 技能版本：2.0.0（更新了v4.1增强功能） **此版本的新增功能**： * ✨ 全面的 v3 到 v4 迁移指南，其中包含重大更改 * ✨ 通过三级系统增强错误定制 * ✨ 扩展元数据 API 和注册表系统 * ✨ 通过实际示例改进了错误格式 * ✨ 对 40 多个语言环境的内置本地化支持 * ✨ 具有真实模式的详细编解码器文档 * ✨ 解释了性能改进和架构变化

佐德

包含技能