zod教程
一、简介
Zod 是一个 TypeScript 首选的模式声明和验证库,具有以下特点:
- 零依赖
- 体积小(8kb)
- 与 TypeScript 完美集成
- 链式 API
- 支持同步和异步验证
二、安装
三、基础数据类型验证
3.1 原始类型
3.2 可选和可为空
四、对象验证
4.1 基础对象验证
4.2 验证方法
五、数组和元组
5.1 数组
5.2 元组
六、字面量、枚举和联合类型
6.1 字面量
6.2 枚举
6.3 联合类型
七、字符串和数字验证
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 类型转换
8.2 预处理
九、自定义验证
9.1 使用 refine()
9.2 使用 superRefine()
十、错误处理
10.1 错误结构
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 自定义错误信息
十一、类型推断
11.1 基础类型推断
11.2 实用类型操作
十二、模式操作
12.1 模式组合
12.2 递归模式
十三、实用示例
13.1 表单验证
13.2 API 验证
13.3 配置验证
十四、最佳实践
14.1 代码组织
14.2 验证中间件
14.3 性能优化
- 缓存模式实例:避免重复创建模式
- 使用
z.lazy() 处理递归类型
- 避免深度嵌套:简化模式结构
- 使用
preprocess() 减少转换开销
十五、常见问题
15.1 如何处理可选字段?
15.2 如何处理文件上传?
15.3 如何处理动态键?
十六、与其他库集成
16.1 与 React Hook Form
16.2 与 Express
快速参考表
| 操作 | 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() |
| 转换 |
加载中...