类型系统

相关源文件

• deno/lib/__tests__/nullable.test.ts
• deno/lib/__tests__/optional.test.ts
• deno/lib/__tests__/primitive.test.ts
• deno/lib/__tests__/string.test.ts
• deno/lib/__tests__/validations.test.ts
• deno/lib/types.ts
• src/__tests__/nullable.test.ts
• src/__tests__/primitive.test.ts
• src/__tests__/string.test.ts
• src/__tests__/validations.test.ts
• src/types.ts

本文档解释了 Zod 中的类型系统架构，重点介绍类型在验证和转换过程中如何定义、组织以及相互作用。有关验证管道和错误处理的信息，请参阅验证管道和错误处理。

核心类型结构

Zod 的类型系统围绕一个名为 ZodType 的核心抽象基类构建，所有具体的 Schema 类型都继承自它。这种架构为所有 Schema 类型提供了一致的验证、转换和错误处理接口。

来源：src/types.ts169-577 这展示了 ZodType 抽象基类及其主要派生类型。

类型定义和泛型参数

ZodType 抽象类使用 TypeScript 泛型来定义输入和输出类型，在使用 TypeScript 时提供强大的类型推断。

泛型类型参数的作用如下：

参数	描述
输出	成功验证后返回的类型
Def	包含 Schema 元数据的定义类型
输入	预期的输入类型（如果未指定，默认为 Output）

来源：src/types.ts169-177

类型验证过程

所有 Zod 类型都实现了一个核心的 _parse 方法，用于处理验证逻辑。公共的 parse 和 safeParse 方法是此内部实现的包装器。

来源：src/types.ts241-266 src/types.ts228-234

类型创建和自定义验证

Zod 提供了广泛的 API，用于创建具有自定义验证规则的 Schema。所有类型 Schema 都继承自 ZodType 并继承核心功能。

基本类型

原始类型 Schema（ZodString、ZodNumber 等）为其各自的类型提供特定的验证方法。

来源：src/__tests__/string.test.ts7-14 src/__tests__/validations.test.ts143-154

类型转换系统

Zod Schema 支持转换和精修，允许您在验证期间修改数据或应用额外的检查。

来源：src/types.ts353-446 src/types.ts484-492 src/types.ts508-516

细化

精修允许您向 Schema 添加自定义验证规则

来源：src/types.ts353-398 src/types.ts436-449

转换

转换允许您在验证期间修改数据

来源：src/types.ts508-517

类型组合

Zod 允许组合类型以创建更复杂的 Schema

来源：src/types.ts484-492 src/types.ts500-506

类型推断

Zod 提供了 TypeScript 类型辅助函数，用于从 Schema 中提取静态类型

来源：src/types.ts50-54

类型层级

Zod 的类型系统包含各种 Schema 类型，用于不同的数据结构和验证

类别	类型
基本类型（Primitives）	ZodString, ZodNumber, ZodBoolean, ZodBigInt, ZodDate, ZodSymbol, ZodUndefined, ZodNull, ZodAny, ZodUnknown, ZodVoid
字面量（Literals）	ZodLiteral（用于字面值，如 z.literal('hello')）
合集	ZodArray, ZodObject, ZodRecord, ZodMap, ZodSet
联合/交叉类型（Unions/Intersections）	ZodUnion, ZodIntersection, ZodDiscriminatedUnion
函数	ZodFunction, ZodPromise
特殊类型（Special）	ZodOptional, ZodNullable, ZodDefault, ZodEffects, ZodBranded, ZodPipeline

来源：src/types.ts579-773 deno/lib/types.ts579-773

实现细节

ZodType 抽象类提供了几个关键的内部方法，派生类必须实现或继承这些方法

• _parse: 核心解析逻辑（所有子类都必须实现）
• _getType: 确定输入数据的 JavaScript 类型
• _getOrReturnCtx: 管理解析上下文
• _processInputParams: 处理解析的输入参数
• _parseSync: 处理同步解析
• _parseAsync: 处理异步解析

来源：src/types.ts185-239

ZodType 提供的公共方法可供消费者使用

• parse: 验证数据并返回数据或抛出错误
• safeParse: 验证数据并返回成功/错误对象
• parseAsync: parse 的异步版本
• safeParseAsync: safeParse 的异步版本
• refine, superRefine: 添加自定义验证规则
• transform: 在验证期间应用转换
• 各种类型修饰符：optional(), nullable() 等。

来源：src/types.ts241-346 src/types.ts484-498

这种架构确保了所有 Schema 类型都具有一致的接口，同时允许为每种类型提供专门的验证逻辑。