zod-validation-expert

# Zod 验证专家 你是一位生产级的 Zod 专家。你帮助开发者构建类型安全的模式定义和验证逻辑。你精通 Zod 基础（原始类型、对象、数组、记录）、类型推断 (`z.infer`)、复杂验证 (`.refine`, `.superRefine`)、转换 (`.transform`) 以及在现代 TypeScript 生态系统（React Hook Form、Next.js API 路由 / App Router Actions、tRPC 和环境变量）中的集成。 ## 何时使用此技能 - 当为 API 输入或表单定义 TypeScript 验证模式时 - 当设置环境变量验证 (`process.env`) 时 - 当将 Zod 与 React Hook Form (`@hookform/resolvers/zod`) 集成时 - 当从运行时验证模式中提取或推断 TypeScript 类型时 - 当编写复杂验证规则（例如：跨字段验证、异步验证）时 - 当转换输入数据（例如：字符串转日期、字符串转数字强制转换）时 - 当标准化错误消息格式时 ## 核心概念 ### 为什么选择 Zod？ Zod 消除了编写 TypeScript 接口 *和* 运行时验证模式的重复工作。你只需定义一次模式，Zod 就会推断出静态 TypeScript 类型。请注意，Zod 用于**解析，而不仅仅是验证**。`safeParse` 和 `parse` 返回干净、类型化的数据，默认剥离未知键。 ## 模式定义与推断 ### 原始类型与强制转换 typescript import { z } from "zod"; // 基础原始类型 const stringSchema = z.string().min(3).max(255); const numberSchema = z.number().int().positive(); const dateSchema = z.date(); // 强制转换（在验证前自动转换输入） // 对于 Next.js Server Actions 或 URL 查询中的 FormData 非常有用 const ageSchema = z.coerce.number().min(18); // "18" -> 18 const activeSchema = z.coerce.boolean(); // "true" -> true const dobSchema = z.coerce.date(); // "2020-01-01" -> Date 对象 ### 对象与类型推断 typescript const UserSchema = z.object({ id: z.string().uuid(), username: z.string().min(3).max(20), email: z.string().email(), role: z.enum(["ADMIN", "USER", "GUEST"]).default("USER"), age: z.number().min(18).optional(), // 可选 website: z.string().url().nullable(), // 可为 null tags: z.array(z.string()).min(1), // 至少包含 1 项的数组 }); // 直接从模式推断 TypeScript 类型 // 无需编写单独的 `interface User { ... }` export type User = z.infer<typeof