# 佐德 ## 概述 Zod 是一个 **TypeScript 优先的模式验证库**，具有 **静态类型推断**。定义一次模式；您可以获得运行时验证和 TypeScript 类型（通过“z.infer”）。零外部依赖；适用于 Node 和浏览器。非常适合表单（例如使用react-hook-form）、API 解析、环境变量和任何不受信任的输入。 **要求**：推荐使用 TypeScript 5.5+；在 `tsconfig.json` 中启用 **`strict`**。 **安装** : `npm install zod` ** ** ## 快速开始从“zod”导入{z}； const 用户 = z.object({ 名称： z.string(), 年龄：z.number().可选()， }); type User = z.infer<用户类型>; // { 名称：字符串；年龄？：数字 } const data = User.parse(输入); // 如果无效则抛出 ZodError const 结果 = User.safeParse(input); // { 成功: true, 数据 } | { 成功：错误，错误 } ** ** ## 原语和常见类型架构|类型 |注释 ---|---|--- `z.string()` |字符串| `z.number()` |数量 | `z.boolean()` |布尔 | `z.bigint()` |大整数 | `z.date()` |日期 | `z.undefined()` |未定义 | `z.null()` |空 | `z.void()` |无效| `z.any()` |任何| `z.unknown()` |未知 | `z.never()` |从来没有| `z.literal("x")` |字面意思| `z.enum(["a", "b"])` |文字联合| `z.string().email()` |字符串|电子邮件格式 `z.string().url()` |字符串|网址 `z.string().uuid()` |字符串|通用唯一标识符 `z.string().datetime()` |字符串| ISO 日期时间 `z.number().int()` |数量 |整数 `z.number().min(n).max(m)` |数量 |范围 `z.boolean()` / `z.string().transform(...)` |字符串布尔 | “真”/“假”强制可选：`.可选()`→`T |未定义`。可空： `.nullable()` → `T |空`。空： `.nullish()` → `T |空 |未定义`。默认值：`.default(值)`。 ** ** ## 对象 const 架构 = z.object({ 名称： z.string(), 年龄：z.number().可选()，标签： z.array(z.string()).default([]), }); 类型架构 = z.infer<架构类型>; * **.shape** ：`Schema.shape.name`（访问字段架构）。 * **.keyof()** : `Schema.keyof()` → 键的枚举。 * **.extend({ ... })** ：添加或覆盖键。 * **.pick({ name })** / **.omit({ Age })** ：键的子集。 * **.partial()** / **.required({ name })** ：可选或要求。 * **.strict()** ：没有额外的键（z.object 中的默认值）。 **z.strictObject** / **z.looseObject** 用于行为变体。 * **.catchall(z.string())** ：允许带有架构的额外键。 * **嵌套** : `z.object({ user: z.object({ name: z.string() }) })`。 * **递归** ：`z.lazy(() => Category)` 用于自引用结构。 ** ** ## 数组和元组 * **数组** ：`z.array(z.string())`、`z.string().array()`。 * **元组** : `z.tuple([z.string(), z.number()])` — 固定长度和类型。 * **非空** ： `.min(1)` 或专用助手（如果可用）。 ** ** ## 并集和交集 * **Union** : `z.union([z.string(), z.number()])` 或 `z.string().or(z.number())`。 * **歧视联合** ：使用公共键（例如 `type: "a"`）和 `z.discrimulatedUnion("type", [z.object({ type: z.literal("a"), ... }), ...])`。 * **交集** : `z.intersection(A, B)` 或 `A.and(B)`。 ** ** ## 细化和改造 * **.refine(fn, message?)** ：自定义验证；保持类型不变。 * **.superRefine** ：多个问题或异步；推送到“ctx”。 * **.transform(fn)** ：更改输出类型。输入和输出可以不同；使用“z.input”和“z.output”（或“z.infer”作为输出）。 * **.pipe(otherSchema)** ：链验证/转换（例如通过 `z.string().pipe(z.coerce.number())` 进行字符串 → 数字）。 ** ** ## 解析和错误 * **.parse(input)** ：返回数据或抛出 **ZodError**。 * **.safeParse(input)** ：返回 `{ success: true, data }` 或 `{ success: false, error: ZodError }`。 * **ZodError** ：`error.issues`（`{ path, message, code }`数组），嵌套形状的`error.format()`。 * **Async** ：`.parseAsync` / `.safeParseAsync` 用于具有异步细化或转换的模式。 ** ** ## 类型推断 * **z.infer** ：输出类型（转换/默认后）。 * **z.input** ：输入类型（转换之前；当输入≠输出时有用）。 * **z.output** ：与输出类型的“z.infer”相同。 const S = z.string().transform((s) => s.length); 输入 In = z.input; // 字符串 type Out = z.output; // 数量 ** ** ## 集成：React Hook 表单将 **@hookform/resolvers** 与 **zodResolver** 一起使用：从“@hookform/resolvers/zod”导入{zodResolver}；从“react-hook-form”导入{ useForm }；从“zod”导入{z}； const formSchema = z.object({ 电子邮件：z.string().email(), 密码：z.string().min(8), }); type FormValues = z.infer; const form = useForm({ 解析器：zodResolver(formSchema), 默认值：{ 电子邮件：“”，密码：“” }， }); ** ** ## 最佳实践 * 对于 API 边界，首选**严格**模式（无额外键）；仅当您需要转发未知密钥时才使用**.passthrough()**。 * 对具有默认值的可选字段使用**.default()**。 * 对于API/env解析，使用**safeParse**并处理错误；显示来自“error.issues”的用户友好消息。 * 对变体有效负载使用**可区分的联合**（例如按“类型”划分的事件）。 * 仅在安全时强制：`z.coerce.number()`、`z.coerce.boolean()`或自定义`.transform()`。 ** ** ## 常见错误 * **忘记严格** ：保留 TypeScript `strict: true`；佐德用它效果最好。 * **输入与输出** ：在 `.transform()` 之后，如果调用者看到的类型不同，请使用 `z.input<>` / `z.output<>`。 * **在热路径中解析**：更喜欢在边界（例如 API 处理程序、表单提交）验证一次，而不是在每次渲染时验证。 * **过于宽泛的模式**：当域有规则时，更喜欢特定类型（例如`.email()`、`.min()`）而不是普通的`z.string()`。 ** ** ## 其他资源 * [reference.md]() — Zod 官方文档链接、API 部分（基元、对象、字符串、数字、细化等）、Zod Mini、生态系统。 * **官方** ： — 简介、API、基础知识、生态系统。 * **API (Zod 4)** : — 完整的模式类型和方法。 * **LLM / 索引** : — 工具/代理的结构化文档。

佐德

包含技能