Zod 项目中的模式定义完全指南

什么是 Zod 模式定义？

Zod 是一个强大的 TypeScript 模式验证库，它允许开发者定义数据结构并验证输入数据是否符合预期格式。模式定义是 Zod 的核心概念，它代表从简单原始值到复杂嵌套对象和数组的各种类型。

原始类型模式

Zod 支持所有 JavaScript 原始类型的模式定义：

// 基本原始类型
z.string();    // 字符串
z.number();    // 数字
z.bigint();    // 大整数
z.boolean();   // 布尔值
z.symbol();    // 符号
z.undefined(); // undefined
z.null();      // null

类型强制转换

当需要将输入数据强制转换为特定类型时，可以使用 z.coerce 方法：

z.coerce.string();    // 转换为字符串
z.coerce.number();    // 转换为数字
z.coerce.boolean();   // 转换为布尔值
z.coerce.bigint();    // 转换为大整数

强制转换会尝试将输入值转换为目标类型：

const schema = z.coerce.string();

schema.parse("tuna");    // => "tuna"
schema.parse(42);        // => "42"
schema.parse(true);      // => "true"
schema.parse(null);      // => "null"

字面量模式

字面量模式用于表示特定的字面量值：

const tuna = z.literal("tuna");     // 字符串字面量
const twelve = z.literal(12);       // 数字字面量
const twobig = z.literal(2n);       // 大整数字面量
const tru = z.literal(true);        // 布尔字面量

字符串验证

Zod 提供了丰富的字符串验证和转换 API：

基本验证

z.string().max(5);      // 最大长度
z.string().min(5);      // 最小长度
z.string().length(5);   // 精确长度
z.string().regex(/^[a-z]+$/);  // 正则匹配

字符串转换

z.string().trim();       // 去除空白字符
z.string().toLowerCase(); // 转换为小写
z.string().toUpperCase(); // 转换为大写

特殊字符串格式

Zod 支持多种常见字符串格式验证：

z.email();    // 电子邮件
z.uuid();     // UUID
z.url();      // URL
z.emoji();    // 单个表情符号
z.ipv4();     // IPv4地址
z.ipv6();     // IPv6地址

电子邮件验证

默认情况下，Zod 使用较为严格的电子邮件正则表达式：

z.email();  // 使用默认验证规则

也可以自定义验证规则：

z.email({ pattern: /your regex here/ });

URL 验证

验证 WHATWG 兼容的 URL：

const schema = z.url();

schema.parse("https://example.com"); // 通过
schema.parse("sup"); // 失败

可以限制主机名和协议：

const schema = z.url({ 
  hostname: /^example\.com$/,
  protocol: /^https$/
});

数字验证

Zod 提供了多种数字验证方法：

z.number().gt(5);       // 大于5
z.number().gte(5);      // 大于等于5
z.number().lt(5);       // 小于5
z.number().lte(5);      // 小于等于5
z.number().positive();  // 正数
z.number().multipleOf(5); // 5的倍数

日期验证

验证 Date 实例：

z.date().safeParse(new Date()); // 通过
z.date().safeParse("2022-01-12"); // 失败

日期范围验证：

z.date().min(new Date("1900-01-01")); // 最小日期
z.date().max(new Date());             // 最大日期

枚举类型

使用 z.enum 验证固定字符串集合：

const FishEnum = z.enum(["Salmon", "Tuna", "Trout"]);

FishEnum.parse("Salmon"); // 通过
FishEnum.parse("Swordfish"); // 失败

总结

Zod 的模式定义功能强大且灵活，从简单的原始类型到复杂的验证规则都能轻松应对。通过本文介绍的各种模式定义方法，开发者可以构建出健壮的数据验证逻辑，确保应用程序接收的数据始终符合预期格式。

无论是字符串格式验证、数字范围限制，还是日期时间验证，Zod 都提供了简洁直观的 API。这些验证规则可以与 TypeScript 类型系统完美配合，为你的项目提供类型安全和运行时验证的双重保障。