Schema 类型

Schema 类型层级

Zod 构建于一个可扩展的类型系统之上，其中所有 schema 类型都继承自抽象类 ZodType。理解这个层级对于有效使用该库至关重要。

来源：src/types.ts169-577 README.md706-730

ZodType 基础类

Zod 中的所有 schema 类型都继承自抽象类 ZodType，它为验证和类型操作提供了一个通用接口。

抽象类 ZodType 提供了许多用于类型精炼、转换和组合的方法，使您能够从更简单的 schema 类型构建复杂的 schema 类型。

来源：src/types.ts169-577 README.md706-730

原始类型 Schema

Zod 提供了所有 JavaScript 原始类型的 schema。这些是创建更复杂 schema 的基本构建块。

字符串 Schema

字符串 schema 提供了额外的验证方法，例如 .email()、.url()、.uuid() 等，用于常见字符串格式。

来源：src/types.ts773-1087 README.md815-885

原始类型的类型转换

Zod 为原始类型提供了类型转换功能，允许在验证过程中自动转换字符串、数字和其他类型。

来源：README.md735-790

字面量 Schema

Literal schemas（字面量 schema）会验证输入是否与特定的字面量值完全匹配。

来源：README.md792-810 src/__tests__/primitive.test.ts8-13

对象 Schema

对象 schema 会验证 JavaScript 对象的形状，包括其属性和嵌套结构。

对象 schema 包含许多用于操作 schema 的方法

来源：README.md100-112 README.md1002-1163

数组 Schema

数组 schema 会验证特定元素类型的数组。

数组 schema 包含验证方法

来源：README.md113-117 README.md1164-1177

联合和交叉类型

联合类型

联合类型允许验证可能为多个类型之一的数据。

区分联合类型

交叉类型

交叉类型会验证数据是否匹配所有指定的 schema。

来源：README.md118-119 README.md1184-1225

可选和可空类型

可选和可空 schema 允许验证可能为 undefined 或 null 的数据。

来源： README.md98-99 README.md1226-1247 src/__tests__/optional.test.ts20-43 src/__tests__/nullable.test.ts20-42

Schema 类型验证流程

以下图表说明了数据通过 Zod 验证流程的流转情况

来源： src/types.ts241-348

类型转换流程

以下图表展示了 Zod schema 如何通过验证管道转换数据

来源： src/types.ts351-577

可用 Schema 类型参考表

下表提供了 Zod 中可用主要 schema 类型的快速参考

类别	Schema 类型	描述
基本类型（Primitives）	`z.string()`, `z.number()`, `z.boolean()`, `z.date()`, `z.bigint()`, `z.symbol()`	基本的 JavaScript 原始类型
空类型	`z.undefined()`, `z.null()`, `z.void()`	表示值缺失的类型
通配类型	`z.any()`, `z.unknown()`	接受任何值的类型
Never 类型	`z.never()`	从不验证的类型
字面量（Literals）	`z.literal('value')`	精确值验证
对象	`z.object({...})`	对象结构验证
数组	`z.array(schema)`	数组验证
元组	`z.tuple([...])`	具有特定类型的固定长度数组
联合类型	`z.union([...])`	几种可能类型中的一种
区分联合类型	`z.discriminatedUnion()`	带有区分符属性的联合类型
记录	`z.record(keySchema, valueSchema)`	具有动态键的对象
Map	`z.map(keySchema, valueSchema)`	JavaScript Map 验证
集合	`z.set(schema)`	JavaScript Set 验证
Promises	`z.promise(schema)`	Promise 验证
函数	`z.function()`	函数验证
Refined 类型	带有 `.refine()` 的原始 schema	添加自定义验证逻辑
Transformed 类型	带有 `.transform()` 的原始 schema	在验证过程中转换数据

来源： README.md82-133 README.md705-730

Schema 类型修改方法

所有 Zod schema 都包含一组用于修改或转换 schema 的方法

来源： src/types.ts483-576 README.md134-164

理解 ZodType 继承

Zod 实现了一种继承形式，其中每个 schema 类型都扩展了基础的 ZodType 类。通用操作在基础类中定义，而特定的验证逻辑则在每个子类的 _parse 方法中实现。

示例： ZodString 如何验证数据

来源： src/types.ts773-1087

创建自定义 Schema 类型

尽管 Zod 提供了丰富的内置 schema 类型，您也可以通过扩展 ZodType 类来创建自定义 schema 类型。至少，您需要实现 _parse 方法来定义您的验证逻辑。

自定义验证最常见的方法是使用现有 schema 类型的 .refine() 或 .superRefine() 方法，而不是创建全新的 schema 类型。

来源： src/types.ts169-186

Schema 类型组合

Zod 的一个关键优势在于能够将简单的 schema 组合成复杂的数据结构。这种组合通过 .merge() 等方法（用于对象 schema）或通过创建嵌套 schema 来实现。

来源： README.md1002-1163

总结

Zod 提供了一个全面的 schema 类型系统，可用于验证和转换数据。所有 schema 类型都继承自 ZodType 基础类，该类为验证和操作提供了通用接口。通过组合这些 schema 类型，您可以创建符合应用程序数据结构的复杂验证 schema。

有关如何转换和细化这些 schema 类型的更多信息，请参阅 Schema Transformations。