zod教程

一、简介

Zod 是一个 TypeScript 首选的模式声明和验证库，具有以下特点：

零依赖
体积小（8kb）
与 TypeScript 完美集成
链式 API
支持同步和异步验证

二、安装

bash
1npm install zod
2# 或
3yarn add zod
4# 或
5pnpm add zod

typescript
1import { z } from 'zod';

三、基础数据类型验证

3.1 原始类型

typescript
1z.string()      // 字符串
2z.number()      // 数字
3z.boolean()     // 布尔值
4z.bigint()      // 大整数
5z.symbol()      // 符号
6z.null()        // null
7z.undefined()   // undefined
8z.void()        // void
9z.any()         // 任意类型
10z.unknown()     // 未知类型
11z.never()       // 永不存在的值
12z.date()        // 日期

3.2 可选和可为空

typescript
1// 可选
2z.string().optional()        // string | undefined
3z.string().optional().null() // string | undefined | null
4
5// 可为空
6z.string().nullable()        // string | null
7
8// 默认值
9z.string().default("默认值")

四、对象验证

4.1 基础对象验证

typescript
1const userSchema = z.object({
2  username: z.string().min(3).max(20),
3  email: z.string().email(),
4  age: z.number().int().positive().optional(),
5  isAdmin: z.boolean().default(false),
6});

4.2 验证方法

typescript
1// 严格验证（抛出异常）
2const user = userSchema.parse(data);
3
4// 安全验证（不抛出异常）
5const result = userSchema.safeParse(data);
6if (result.success) {
7  console.log(result.data);
8} else {
9  console.log(result.error.errors);
10}
11
12// 部分验证
13userSchema.partial().parse(data); // 所有字段变为可选
14userSchema.deepPartial().parse(data); // 深度可选
15
16// 忽略未知字段
17userSchema.strict().parse(data); // 不允许未知字段
18userSchema.strip().parse(data); // 移除未知字段
19userSchema.passthrough().parse(data); // 保留未知字段

五、数组和元组

5.1 数组

typescript
1// 基础数组
2z.array(z.string())          // string[]
3z.string().array()           // 另一种写法
4
5// 带约束的数组
6z.array(z.string())
7  .min(3, "至少需要3个元素")
8  .max(10, "最多10个元素")
9  .length(5, "必须正好5个元素")
10
11// 非空数组
12z.string().array().nonempty()

5.2 元组

typescript
1// 固定长度和类型的元组
2z.tuple([
3  z.string(),           // 第一个元素：字符串
4  z.number(),          // 第二个元素：数字
5  z.boolean().optional() // 第三个元素：可选布尔值
6]);

六、字面量、枚举和联合类型

6.1 字面量

typescript
1z.literal("hello")     // 字符串字面量
2z.literal(42)          // 数字字面量
3z.literal(true)        // 布尔字面量

6.2 枚举

typescript
1// Zod 枚举
2const statusEnum = z.enum(["pending", "active", "inactive"]);
3
4// 从 TypeScript 枚举导入
5enum UserRole {
6  ADMIN = "admin",
7  USER = "user",
8  GUEST = "guest"
9}
10const roleSchema = z.nativeEnum(UserRole);

6.3 联合类型

typescript
1// 基础联合类型
2const idSchema = z.union([
3  z.string().uuid(),
4  z.number().int().positive(),
5]);
6
7// 可辨识联合（Discriminated Union）
8const eventSchema = z.discriminatedUnion("type", [
9  z.object({
10    type: z.literal("click"),
11    x: z.number(),
12    y: z.number(),
13  }),
14  z.object({
15    type: z.literal("keypress"),
16    key: z.string(),
17    ctrlKey: z.boolean().optional(),
18  }),
19]);

七、字符串和数字验证

7.1 字符串验证方法

方法	描述	示例
`min()`	最小长度	`.min(3)`
`max()`	最大长度	`.max(20)`
`length()`	精确长度	`.length(10)`
`email()`	邮箱格式	`.email()`
`url()`	URL 格式	`.url()`
`uuid()`	UUID 格式	`.uuid()`
`regex()`	正则匹配

7.2 数字验证方法

方法	描述	示例
`min()`	最小值	`.min(0)`
`max()`	最大值	`.max(100)`
`int()`	必须是整数	`.int()`
`positive()`	正数	`.positive()`
`nonnegative()`	非负数	`.nonnegative()`
`negative()`	负数	`.negative()`
`nonpositive()`

八、转换和预处理

8.1 类型转换

typescript
1// 强制类型转换
2z.coerce.string()   // 尝试转换为字符串
3z.coerce.number()   // 尝试转换为数字
4z.coerce.boolean()  // 尝试转换为布尔值
5z.coerce.bigint()   // 尝试转换为大整数
6z.coerce.date()     // 尝试转换为日期
7
8// 示例
9z.coerce.number().parse("123");    // 123 (数字)
10z.coerce.boolean().parse("true");  // true (布尔值)

8.2 预处理

typescript
1// 预处理数据
2const trimSchema = z.preprocess(
3  (val) => (typeof val === "string" ? val.trim() : val),
4  z.string()
5);
6
7// 转换后验证
8const dateStringSchema = z.string()
9  .refine((val) => !isNaN(Date.parse(val)), {
10    message: "无效的日期格式"
11  })
12  .transform((val) => new Date(val));

九、自定义验证

9.1 使用 `refine()`

typescript
1// 简单验证
2const evenSchema = z.number()
3  .refine((n) => n % 2 === 0, {
4    message: "必须是偶数",
5  });
6
7// 异步验证
8const uniqueEmailSchema = z.string()
9  .email()
10  .refine(async (email) => {
11    const exists = await checkEmailExists(email);
12    return !exists;
13  }, {
14    message: "邮箱已被注册",
15  });
16
17// 跨字段验证
18const passwordSchema = z.object({
19  password: z.string().min(6),
20  confirmPassword: z.string().min(6),
21})
22.refine((data) => data.password === data.confirmPassword, {
23  message: "两次输入的密码不一致",
24  path: ["confirmPassword"], // 指定错误路径
25});

9.2 使用 `superRefine()`

typescript
1// 更细粒度的控制
2const userSchema = z.object({
3  username: z.string(),
4  email: z.string(),
5})
6.superRefine((data, ctx) => {
7  if (data.username === data.email) {
8    ctx.addIssue({
9      code: z.ZodIssueCode.custom,
10      message: "用户名和邮箱不能相同",
11      path: ["email"],
12    });
13  }
14});

十、错误处理

10.1 错误结构

typescript
1try {
2  schema.parse(data);
3} catch (error) {
4  if (error instanceof z.ZodError) {
5    error.errors.forEach((err) => {
6      console.log({
7        path: err.path.join('.'),  // 错误字段路径
8        message: err.message,       // 错误信息
9        code: err.code,            // 错误代码
10      });
11    });
12  }
13}

10.2 错误代码

代码	描述
`invalid_type`	类型不匹配
`invalid_literal`	字面量不匹配
`custom`	自定义错误
`invalid_union`	联合类型匹配失败
`invalid_union_discriminator`	可辨识联合识别失败
`invalid_enum_value`	枚举值无效
`unrecognized_keys`	未知的键
`invalid_arguments`	函数参数无效
`invalid_return_type`	函数返回值无效
`invalid_date`	无效日期
`invalid_string`	字符串验证失败
`too_small`

10.3 自定义错误信息

typescript
1const schema = z.object({
2  email: z.string({
3    required_error: "邮箱是必填项",
4    invalid_type_error: "邮箱必须是字符串",
5  }).email({
6    message: "请输入有效的邮箱地址",
7  }).min(5, {
8    message: "邮箱至少需要5个字符",
9  }),
10});

十一、类型推断

11.1 基础类型推断

typescript
1const userSchema = z.object({
2  name: z.string(),
3  age: z.number(),
4  email: z.string().email().optional(),
5});
6
7// 推断 TypeScript 类型
8type User = z.infer<typeof userSchema>;
9// 等价于: type User = { name: string; age: number; email?: string }

11.2 实用类型操作

typescript
1// 部分类型
2type PartialUser = z.infer<typeof userSchema.partial()>;
3// { name?: string; age?: number; email?: string }
4
5// 必需类型
6type RequiredUser = z.infer<typeof userSchema.required()>;
7// { name: string; age: number; email: string }
8
9// 选择字段
10type NameOnly = z.infer<typeof userSchema.pick({ name: true })>;
11// { name: string }
12
13// 忽略字段
14type WithoutAge = z.infer<typeof userSchema.omit({ age: true })>;
15// { name: string; email?: string }

十二、模式操作

12.1 模式组合

typescript
1// 扩展模式
2const baseSchema = z.object({
3  id: z.string().uuid(),
4  createdAt: z.date(),
5});
6
7const userSchema = baseSchema.extend({
8  name: z.string(),
9  email: z.string().email(),
10});
11
12// 合并模式
13const schemaA = z.object({ a: z.string() });
14const schemaB = z.object({ b: z.number() });
15const mergedSchema = schemaA.merge(schemaB); // { a: string; b: number }
16
17// 交集
18const personSchema = z.object({ name: z.string() });
19const employeeSchema = z.object({ id: z.number() });
20const personEmployeeSchema = personSchema.and(employeeSchema);

12.2 递归模式

typescript
1// 定义递归类型
2const categorySchema: z.ZodType<Category> = z.lazy(() =>
3  z.object({
4    name: z.string(),
5    subcategories: z.array(categorySchema).optional(),
6  })
7);
8
9// 或使用函数
10const createCategorySchema = (): z.ZodType<Category> =>
11  z.object({
12    name: z.string(),
13    subcategories: z.array(createCategorySchema()).optional(),
14  });

十三、实用示例

13.1 表单验证

typescript
1const loginSchema = z.object({
2  email: z.string().email("请输入有效的邮箱"),
3  password: z.string()
4    .min(6, "密码至少6位")
5    .max(20, "密码最多20位")
6    .regex(/[A-Za-z]/, "必须包含字母")
7    .regex(/\d/, "必须包含数字"),
8  rememberMe: z.boolean().optional(),
9  captcha: z.string().length(4, "验证码必须是4位"),
10});
11
12const registerSchema = z.object({
13  username: z.string()
14    .min(3, "用户名至少3位")
15    .max(20, "用户名最多20位")
16    .regex(/^[a-zA-Z0-9_]+$/, "只能包含字母、数字和下划线"),
17  email: z.string().email(),
18  password: z.string().min(6),
19  confirmPassword: z.string(),
20  acceptTerms: z.boolean().refine((val) => val === true, {
21    message: "必须接受条款",
22  }),
23}).refine((data) => data.password === data.confirmPassword, {
24  message: "密码不匹配",
25  path: ["confirmPassword"],
26});

13.2 API 验证

typescript
1// 请求参数验证
2const paginationSchema = z.object({
3  page: z.coerce.number().int().positive().default(1),
4  limit: z.coerce.number().int().min(1).max(100).default(20),
5  sort: z.string().optional(),
6  order: z.enum(["asc", "desc"]).default("desc"),
7  search: z.string().optional(),
8});
9
10// API 响应验证
11const apiResponseSchema = <T extends z.ZodTypeAny>(dataSchema: T) =>
12  z.object({
13    success: z.boolean(),
14    message: z.string().optional(),
15    data: dataSchema.optional(),
16    error: z.string().optional(),
17    timestamp: z.string().datetime(),
18  });
19
20// 分页响应
21const paginatedSchema = <T extends z.ZodTypeAny>(itemSchema: T) =>
22  z.object({
23    items: z.array(itemSchema),
24    total: z.number(),
25    page: z.number(),
26    limit: z.number(),
27    totalPages: z.number(),
28    hasNext: z.boolean(),
29    hasPrev: z.boolean(),
30  });

13.3 配置验证

typescript
1const configSchema = z.object({
2  // 环境变量
3  NODE_ENV: z.enum(["development", "production", "test"]),
4  PORT: z.coerce.number().int().positive().default(3000),
5  
6  // 数据库配置
7  DATABASE_URL: z.string().url(),
8  DB_POOL_SIZE: z.coerce.number().int().positive().default(10),
9  
10  // Redis 配置
11  REDIS_URL: z.string().url().optional(),
12  REDIS_TTL: z.coerce.number().int().positive().default(3600),
13  
14  // JWT 配置
15  JWT_SECRET: z.string().min(32),
16  JWT_EXPIRES_IN: z.string().default("7d"),
17  
18  // 第三方服务
19  AWS_ACCESS_KEY_ID: z.string().optional(),
20  AWS_SECRET_ACCESS_KEY: z.string().optional(),
21})
22.strict(); // 不允许额外字段

十四、最佳实践

14.1 代码组织

typescript
1// schemas/user.schema.ts
2import { z } from 'zod';
3
4// 基础模式
5export const baseUserSchema = z.object({
6  id: z.string().uuid(),
7  createdAt: z.date(),
8  updatedAt: z.date(),
9});
10
11// 创建用户模式
12export const createUserSchema = z.object({
13  username: z.string().min(3).max(20),
14  email: z.string().email(),
15  password: z.string().min(6),
16});
17
18// 更新用户模式
19export const updateUserSchema = createUserSchema.partial();
20
21// 用户响应模式
22export const userResponseSchema = baseUserSchema.merge(
23  z.object({
24    username: z.string(),
25    email: z.string().email(),
26  })
27);
28
29// 类型导出
30export type CreateUserInput = z.infer<typeof createUserSchema>;
31export type UpdateUserInput = z.infer<typeof updateUserSchema>;
32export type UserResponse = z.infer<typeof userResponseSchema>;

14.2 验证中间件

typescript
1// middleware/validate.ts
2import { Request, Response, NextFunction } from 'express';
3import { AnyZodObject, ZodError } from 'zod';
4
5export const validate = (schema: AnyZodObject) => 
6  async (req: Request, res: Response, next: NextFunction) => {
7    try {
8      // 合并所有请求数据
9      const data = {
10        body: req.body,
11        query: req.query,
12        params: req.params,
13      };
14      
15      const validatedData = await schema.parseAsync(data);
16      
17      // 将验证后的数据挂载到请求对象
18      req.validatedData = validatedData;
19      
20      next();
21    } catch (error) {
22      if (error instanceof ZodError) {
23        return res.status(400).json({
24          success: false,
25          errors: error.errors.map(err => ({
26            path: err.path.join('.'),
27            message: err.message,
28          })),
29        });
30      }
31      next(error);
32    }
33  };
34
35// 使用示例
36router.post('/users', 
37  validate(createUserSchema), 
38  userController.create
39);

14.3 性能优化

缓存模式实例：避免重复创建模式
使用 z.lazy() 处理递归类型
避免深度嵌套：简化模式结构
使用 preprocess() 减少转换开销

十五、常见问题

15.1 如何处理可选字段？

typescript
1// 正确的做法
2const schema = z.object({
3  name: z.string().optional(), // 可选
4  age: z.number().optional(),  // 可选
5});
6
7// 所有字段可选
8const partialSchema = schema.partial();

15.2 如何处理文件上传？

typescript
1// 前端：使用 FormData
2const fileSchema = z.object({
3  file: z.instanceof(File)
4    .refine((file) => file.size <= 5 * 1024 * 1024, {
5      message: "文件大小不能超过5MB",
6    })
7    .refine((file) => ['image/jpeg', 'image/png'].includes(file.type), {
8      message: "只支持 JPEG 和 PNG 格式",
9    }),
10});

15.3 如何处理动态键？

typescript
1// 记录类型
2const recordSchema = z.record(
3  z.string().uuid(), // 键的类型
4  z.number()         // 值的类型
5);
6
7// 动态对象
8const dynamicSchema = z.object({}).catchall(z.string());
9// 允许任意键，值必须是字符串

十六、与其他库集成

16.1 与 React Hook Form

typescript
1import { useForm } from 'react-hook-form';
2import { zodResolver } from '@hookform/resolvers/zod';
3
4const schema = z.object({
5  name: z.string().min(2),
6  email: z.string().email(),
7});
8
9const {
10  register,
11  handleSubmit,
12  formState: { errors },
13} = useForm({
14  resolver: zodResolver(schema),
15});

16.2 与 Express

typescript
1import express from 'express';
2import { z } from 'zod';
3
4const app = express();
5
6app.post('/api/users', async (req, res) => {
7  const schema = z.object({
8    name: z.string(),
9    email: z.string().email(),
10  });
11  
12  const result = schema.safeParse(req.body);
13  if (!result.success) {
14    return res.status(400).json({
15      errors: result.error.errors,
16    });
17  }
18  
19  // 使用验证后的数据
20  const userData = result.data;
21  // ... 处理业务逻辑
22});

快速参考表

操作	Zod 方法	示例
创建模式	`z.object()`	`z.object({ name: z.string() })`
验证	`.parse()`	`schema.parse(data)`
安全验证	`.safeParse()`	`schema.safeParse(data)`
可选字段	`.optional()`	`z.string().optional()`
默认值	`.default()`	`z.string().default("hi")`
数组	`.array()`	`z.string().array()`
转换

加载中...

目录

zod教程

一、简介

二、安装

三、基础数据类型验证

3.1 原始类型

3.2 可选和可为空

四、对象验证

4.1 基础对象验证

4.2 验证方法

五、数组和元组

5.1 数组

5.2 元组

六、字面量、枚举和联合类型

6.1 字面量

6.2 枚举

6.3 联合类型

七、字符串和数字验证

7.1 字符串验证方法

7.2 数字验证方法

八、转换和预处理

8.1 类型转换

8.2 预处理

九、自定义验证

9.1 使用 refine()

9.2 使用 superRefine()

十、错误处理

10.1 错误结构

10.2 错误代码

10.3 自定义错误信息

十一、类型推断

11.1 基础类型推断

11.2 实用类型操作

十二、模式操作

12.1 模式组合

12.2 递归模式

十三、实用示例

13.1 表单验证

13.2 API 验证

13.3 配置验证

十四、最佳实践

14.1 代码组织

14.2 验证中间件

14.3 性能优化

十五、常见问题

15.1 如何处理可选字段？

15.2 如何处理文件上传？

15.3 如何处理动态键？

十六、与其他库集成

16.1 与 React Hook Form

16.2 与 Express

快速参考表

9.1 使用 `refine()`

9.2 使用 `superRefine()`