教程 zod tutorial

字符串

Zod 提供了多种字符串验证方法。

基本验证

ts
import { z } from "zod";

// 基本字符串验证
const stringSchema = z.string();

// 长度验证
z.string().min(5); // 最少5个字符
z.string().max(10); // 最多10个字符
z.string().length(5); // 正好5个字符

// 正则表达式验证
z.string().regex(/^[a-z]+$/); // 只允许小写字母

常用格式验证

ts
// 电子邮件
z.string().email(); // 验证电子邮件格式

// URL
z.string().url(); // 验证URL格式

// UUID
z.string().uuid(); // 验证UUID格式

// CUID
z.string().cuid(); // 验证CUID格式
z.string().cuid2(); // 验证CUID2格式

// 日期时间
z.string().datetime(); // 验证ISO 8601格式

// IP地址
z.string().ip(); // 验证IP地址(支持v4和v6)
z.string().ip({ version: "v4" }); // 仅验证IPv4
z.string().ip({ version: "v6" }); // 仅验证IPv6

字符串转换

ts
// 去除空白
z.string().trim(); // 去除首尾空白

// 大小写转换
z.string().toLowerCase(); // 转换为小写
z.string().toUpperCase(); // 转换为大写

自定义错误消息

ts
z.string().min(5, { message: "必须至少包含5个字符" });
z.string().max(10, { message: "不能超过10个字符" });
z.string().email({ message: "无效的电子邮件地址" });
z.string().url({ message: "无效的URL" });

组合验证

ts
const username = z.string()
  .min(3, { message: "用户名至少需要3个字符" })
  .max(20, { message: "用户名不能超过20个字符" })
  .regex(/^[a-zA-Z0-9_]+$/, { message: "用户名只能包含字母、数字和下划线" });

// 使用示例
username.parse("john_doe123"); // 通过
username.parse("jo"); // 抛出错误:用户名至少需要3个字符
username.parse("john@doe"); // 抛出错误:用户名只能包含字母、数字和下划线

日期时间选项

ts
// 允许时区偏移
z.string().datetime({ offset: true });

// 指定精度
z.string().datetime({ precision: 3 }); // 允许3位毫秒