# Zod v4 架构验证 ## 快速入门 pnpm 添加 zod@^4.3.5 从 'zod' 导入 { z }； // 定义模式 const 用户 = z.object({ 名称：z.string().min(1), 电子邮件：z.email(), 年龄：z.number().positive(), }); // 解析（出错时抛出） const user = User.parse({ 姓名: "Alice", 电子邮件: "alice@example.com", 年龄: 30 }); // 安全解析（返回结果） const 结果 = User.safeParse(data); if (结果.成功) { 结果.数据； // 已验证 } 否则{ console.log(z.prettifyError(结果.error)); } // 类型推断 type User = z.infer<用户类型>; ## 版本控制 + 导入 (v4.3.5) * 对 v4 使用 `import { z } from "zod"`（包根现在导出 v4）。 * 对于 Zod Mini 使用 `import * as z from "zod/mini"`。 * 仅当您必须保留在 v3 上时才使用“import * as z from "zod/v3"”。 ## 工作流程：确定任务类型 **设计新模式？** → 阅读 [API 参考]() **从 Zod 3 迁移？** → 阅读[迁移指南]() **使用编解码器、错误、JSON 架构或元数据？** → 阅读 [高级功能]() **与框架（RHF、tRPC、Hono、Next.js）集成？** → 阅读 [生态系统模式]() ** ** ## v4 关键概念 ### 顶级字符串格式 v4 将字符串验证器移至顶级函数： // v4 风格（首选） z.email() z.uuid() z.url() z.ipv4() z.ipv6() z.iso.date() z.iso.datetime() // v3 风格（已弃用但有效） z.string().email() ### 对象变体 z.object({}) // 允许未知键（默认） z.strictObject({}) // 拒绝未知键 z.looseObject({}) // 明确允许未知键 ### 统一错误参数 // 字符串消息 z.string().min(5, { 错误: "太短" }); // 动态消息函数 z. 字符串({ 错误：(iss) => iss.input === 未定义？ “必填”：“无效” }); ### 类型推断 const Schema = z.object({ name: z.string() }); 类型架构 = z.infer<架构类型>; // 对于变换，分别获取输入/输出 const Transformed = z.string().transform(s => s.length); 输入类型 = z.input<转换后的类型>; // 字符串 type Output = z.output<转换后的类型>; // 数量 ** ** ## 常见模式 ### 受歧视的工会 const Event = z.discriminatedUnion("类型", [ z.object({ type: z.literal("click"), x: z.number(), y: z.number() }), z.object({ 类型: z.literal("keypress"), key: z.string() }), ]); ### 详尽的记录 const Status = z.enum(["待处理", "活动", "完成"]); // 需要的所有键 z.record(Status, z.number()) // { 挂起: number;活跃：数量；完成：数量} // 按键可选 z.partialRecord(Status, z.number()) // { 待处理？: number;活跃？：数量；完成了吗？：数量} ### 递归模式 const 类别 = z.object({ 名称： z.string(), 获取子类别() { return z.array(Category) } }); ### 品牌类型 const UserId = z.string().brand<"UserId">(); const PostId = z.string().brand<"PostId">(); type UserId = z.infer; // 无法将 UserId 分配给 PostId ### 转换和管道 // 变换 z.string().transform(s => s.toUpperCase()) // 管道（链模式） z.管道（ z.string(), z.coerce.number(), z.number().positive() ） ### 默认值 // 输出默认值 (v4) z.string().default("客人") // 输入默认值（转换前） z.string().transform(s => s.toUpperCase()).prefault("你好") // 缺少=>“你好” ** ** ## 错误处理 ### 漂亮的印刷品 const 结果 = schema.safeParse(data); 如果（！结果。成功）{ console.log(z.prettifyError(结果.error)); // ✖ 无效的电子邮件 // → 通过电子邮件 } ### 扁平结构（表格） const flat = z.flattenError(结果.error); // { formErrors: [], fieldErrors: { email: ["无效的电子邮件"] } } ### 树结构（嵌套） const tree = z.treeifyError(结果.error); // { 属性：{ 电子邮件：{ 错误：[“无效电子邮件”] } } } ** ** ## JSON 架构/OpenAPI const 架构 = z.object({ 名称： z.string(), 电子邮件：z.email(), }).meta({ id: "用户", 标题: "用户" }); // 生成 JSON 模式 const jsonSchema = z.toJSONSchema(schema); // 对于 OpenAPI 3.0 z.toJSONSchema(schema, { target: "openapi-3.0" }); // 对多个模式使用注册表 z.globalRegistry.add(schema, schema.meta()); const allSchemas = z.toJSONSchema(z.globalRegistry); ** ** ## v3 到 v4 迁移快速参考 v3 | v4 ---|--- `z.string().email()` | `z.email()` `z.nativeEnum(MyEnum)` | `z.enum(MyEnum)` `{ 消息：“...” }` | `{错误：“...”}` `.strict()` | `z.strictObject({})` `.passthrough()` | `z.looseObject({})` `.merge(其他)` | `.extend(其他.shape)` `z.record(valueSchema)` | `z.record(z.string(), valueSchema)` `.deepPartial()` |手动嵌套 `.partial()` `error.format()` | `z.treeifyError(错误)` `error.flatten()` | `z.flattenError(错误)` ### 重大变化 * **数字**：没有“Infinity”，更严格的“.safe()”和“.int()” * **UUID** ：符合 RFC 4122（使用 `z.guid()` 表示许可） * **可选中的默认值**：`z.string().default("x").Optional()` 现在应用默认值 * **z.unknown()** ：不再隐式可选 * **错误优先级**：模式级别胜过全局运行 codemod：`npx zod-v3-to-v4` ** ** ## 框架集成快速入门 ### 反应钩子形式从 '@hookform/resolvers/zod' 导入 { zodResolver }； const { 注册、handleSubmit、formState: { 错误 } } = useForm({ 解析器：zodResolver（架构）， }); ### tRPC 公开程序 .input(z.object({ id: z.string() })) .query(({ 输入 }) => getById(input.id)) ### 霍诺从'@hono/zod-validator'导入{zValidator}； app.post('/users', zValidator('json', schema), (c) => { const data = c.req.valid('json'); }); ### Next.js 服务器操作 '使用服务器'； const 结果 = schema.safeParse(Object.fromEntries(formData)); 如果（！结果。成功）{ 返回 { 错误：z.flattenError(result.error).fieldErrors }; } ** ** ## 参考文件 * [API 参考]() \- 所有模式类型、方法和验证 API * [高级功能]() \- 编解码器、错误处理、元数据、JSON 架构 * [迁移指南]() \- 完整的 v3 到 v4 迁移参考 * [生态系统模式]() \- 框架集成和组织模式

佐德V4

包含技能