本文档涵盖了 Zod 中的原始 schema 类型，它们是输入验证和类型安全的基础构建块。原始 schema 处理字符串、数字、布尔值和其他 JavaScript 原始类型等基本数据类型。有关对象和数组等更复杂 schema 类型的信息，请参阅对象 Schema 和 数组和元组 Schema。
Zod 中的原始 schema 为 JavaScript 的原始数据类型提供验证。每个 schema 都包含用于创建、验证和转换其类型值的方法。
来源: src/types.ts50-54 README.md706-730
所有原始 schema 均通过调用 z 命名空间中对应的工厂函数来创建。
来源: README.md706-730 src/types.ts773-778 src/__tests__/primitive.test.ts14-20
原始 schema 继承自抽象的 ZodType 类，该类为所有 schema 类型提供通用方法。
字符串 schema 验证输入是否为字符串，并提供特定于字符串的附加验证方法。
字符串 schema 提供多种验证方法
| 方法 | 描述 | 示例 |
|---|---|---|
min(length) | 最小长度 | z.string().min(5) |
max(length) | 最大长度 | z.string().max(10) |
length(length) | 精确长度 | z.string().length(8) |
email() | 有效电子邮件格式 | z.string().email() |
url() | 有效 URL 格式 | z.string().url() |
emoji() | 仅包含表情符号 | z.string().emoji() |
uuid() | 有效 UUID 格式 | z.string().uuid() |
regex(pattern) | 匹配正则表达式 | z.string().regex(/^\d+$/) |
includes(string) | 包含子字符串 | z.string().includes("test") |
startsWith(string) | 以子字符串开头 | z.string().startsWith("https://") |
endsWith(string) | 以子字符串结尾 | z.string().endsWith(".com") |
datetime() | ISO 8601 日期时间 | z.string().datetime() |
ip() | IP 地址 | z.string().ip() |
nonempty() | 非空字符串 | z.string().nonempty() |
来源: README.md814-854 src/types.ts774-854 src/__tests__/string.test.ts7-14
字符串 schema 还提供转换输入字符串的方法
来源: README.md839-841
数字 schema 验证输入是否为数字，并提供附加验证方法。
| 方法 | 描述 | 示例 |
|---|---|---|
min(value) | 最小值（包含） | z.number().min(5) |
max(value) | 最大值（包含） | z.number().max(10) |
positive() | 大于 0 | z.number().positive() |
negative() | 小于 0 | z.number().negative() |
nonpositive() | 小于或等于 0 | z.number().nonpositive() |
nonnegative() | 大于或等于 0 | z.number().nonnegative() |
int() | 整数（无小数） | z.number().int() |
gt(value) | 大于 | z.number().gt(5) |
gte(value) | 大于或等于 | z.number().gte(5) |
lt(value) | 小于 | z.number().lt(5) |
lte(value) | 小于或等于 | z.number().lte(5) |
step(step) | 步长的倍数 | z.number().step(0.1) |
来源: src/__tests__/validations.test.ts82-131 README.md91-95
布尔值 schema 验证输入是否为布尔值（true 或 false）。
来源: src/__tests__/primitive.test.ts18 README.md94
BigInt schema 验证输入是否为 BigInt。
来源: src/__tests__/primitive.test.ts17 README.md92
日期 schema 验证输入是否为 JavaScript Date 对象。
来源: src/__tests__/primitive.test.ts19 README.md95
Symbol schema 验证输入是否为 JavaScript Symbol。
来源: src/__tests__/primitive.test.ts20 README.md96
Zod 提供用于验证 null 和 undefined 值的 schema。
来源: src/__tests__/primitive.test.ts22-23 README.md718-720
Zod 提供两种处理无类型或未知数据的 schema
主要区别在于，z.any() 允许您直接使用值，而 z.unknown() 则在使用前需要进一步验证，使其更安全。
来源: README.md723-726
never schema 不允许任何值，并在验证期间始终抛出错误
这主要用于泛型类型或明确标记不应到达的 schema 分支。
来源: README.md727-730
Zod 提供了一种方便的方式将值强制转换为原始类型
强制转换通过将输入传递给 JavaScript 的内置构造函数（如 String()、Number()、Boolean() 和 new Date()）来完成。
来源: README.md735-789
除了验证类型的原始 schema 外，Zod 还提供验证特定值的字面量 schema。
可以为字符串、数字、布尔值和 BigInt 创建字面量 schema。
来源: README.md792-810 src/__tests__/primitive.test.ts8-13
所有原始 schema 都继承自 ZodType 类中的通用方法
| 方法 | 描述 |
|---|---|
parse(data) | 验证数据并返回，否则抛出错误 |
safeParse(data) | 验证数据并返回结果对象 |
optional() | 使 schema 接受 undefined |
nullable() | 使 schema 接受 null |
nullish() | 使 schema 同时接受 null 和 undefined |
refine(check) | 添加自定义验证逻辑 |
transform(fn) | 验证后转换数据 |
来源: src/types.ts241-576 src/__tests__/optional.test.ts21-38 src/__tests__/nullable.test.ts20-37
Zod 最强大的功能之一是自动类型推断。TypeScript 可以从 schema 自动推断输出类型
这使得您的运行时验证和静态类型能够自动保持同步。
来源: README.md697-700