验证管道

相关源文件

• deno/lib/__tests__/error.test.ts
• deno/lib/__tests__/string.test.ts
• deno/lib/helpers/parseUtil.ts
• deno/lib/types.ts
• src/__tests__/error.test.ts
• src/__tests__/string.test.ts
• src/helpers/parseUtil.ts
• src/types.ts

本页面详细介绍了数据如何通过 Zod 的验证管道，从初始输入到最终输出或错误结果。验证管道是根据模式处理和验证数据的核心机制。有关特定模式类型的信息，请参阅模式类型，有关错误处理的详细信息，请参阅错误处理。

流水线概览

Zod 的验证管道是一个结构化过程，它接收输入数据，根据模式定义进行验证，并产生一个已验证（并可能已转换）的输出或一个错误结果。该管道由多个阶段组成，数据流经类型检查、精炼和转换。

来源

• src/types.ts241-266 核心 parse 和 safeParse 方法
• src/types.ts317-348 parse 方法的异步版本
• src/helpers/parseUtil.ts92-115 解析状态处理

核心组件

验证管道由几个关键组件协同工作，以处理和验证数据。

组件	目的
ParseInput	表示带路径的输入数据
ParseContext	包含验证状态、问题、错误映射
ParseStatus	跟踪验证状态（有效、脏、中止）
ZodType._parse()	所有模式类型实现的抽象方法
OK/DIRTY/INVALID	不同验证结果的类型

来源

• src/helpers/parseUtil.ts52-71 ParseContext 和 ParseInput 接口
• src/helpers/parseUtil.ts95-159 ParseStatus 类定义
• src/types.ts185 抽象 _parse 方法

验证流程

数据验证流程在所有模式类型中都遵循一致的模式

来源

• src/types.ts227-239 _parseSync 方法
• src/helpers/parseUtil.ts72-89 addIssueToContext 函数
• src/types.ts241-266 parse 和 safeParse 方法

解析状态管理

Zod 使用 ParseStatus 系统来跟踪整个验证过程中数据的有效性。模式的验证可能产生三种状态

1. 有效 (status: "valid")：数据完全有效
2. 脏 (status: "dirty")：数据部分有效但存在问题
3. 中止 (status: "aborted")：验证因关键故障而中止

状态管理对于复杂的嵌套模式尤其重要，因为验证的不同分支可能产生不同的结果。

来源

• src/helpers/parseUtil.ts95-159 ParseStatus 类实现
• src/helpers/parseUtil.ts166-176 INVALID、DIRTY 和 OK 辅助函数

解析上下文和输入

验证管道依赖上下文对象来跟踪验证状态并提供错误报告所需的信息。

解析上下文

ParseContext 是一个关键组件，它包含

• 共同的验证状态（问题、异步标志、错误映射）
• 验证树中的当前路径
• 模式特定的错误映射
• 原始输入数据
• 解析的类型信息

解析输入

ParseInput 表示验证过程的结构化输入，包含

• 要验证的实际数据
• 验证中的当前路径
• 对父上下文的引用

来源

• src/helpers/parseUtil.ts49-70 ParsePath、ParseContext 和 ParseInput 定义
• src/types.ts191-207 _getOrReturnCtx 和上下文处理

模式类型验证

Zod 中的每种模式类型都实现了抽象的 _parse 方法，其中包含类型特定的验证逻辑。以下是验证如何通过典型模式类型进行流动的流程

1. 检查输入数据是否与预期类型匹配
2. 如果类型不匹配，则添加一个问题并返回 INVALID
3. 创建一个新的 ParseStatus 来跟踪验证状态
4. 运行所有模式特定的验证（例如，字符串长度、数字范围）
5. 对于每个验证失败，添加一个问题并将状态标记为脏
6. 根据最终状态返回结果

示例：字符串验证

字符串验证器展示了一个典型的验证流程

来源

• src/types.ts773-1093 字符串验证实现
• src/__tests__/string.test.ts16-40 字符串验证测试

同步验证与异步验证

Zod 支持同步和异步验证方法。异步方法处理基于 Promise 的精炼和转换。

同步方法	异步方法
schema.parse()	schema.parseAsync()
schema.safeParse()	schema.safeParseAsync()
内部： _parseSync()	内部： _parseAsync()

异步变体使用相同的管道，但处理基于 Promise 的操作并返回包含验证结果的 Promise。

来源

• src/types.ts228-239 _parseSync 实现
• src/types.ts236-239 _parseAsync 实现
• src/helpers/parseUtil.ts183-192 检查结果类型的辅助函数

管道中的错误处理

错误处理贯穿整个验证管道。当验证问题发生时

1. 问题通过 addIssueToContext 添加到解析上下文
2. 这些问题包含代码、路径和消息信息
3. 错误消息通过错误映射按层次顺序处理
4. 对于 parse() 方法，会抛出 ZodError；对于 safeParse()，错误在结果对象中返回

关键错误处理组件

1. addIssueToContext：将问题添加到解析上下文
2. makeIssue：创建带消息的标准化问题对象
3. 错误映射：将问题数据转换为人类可读消息的函数
4. handleResult：将最终验证结果处理为适当的返回值

来源

• src/helpers/parseUtil.ts6-41 makeIssue 函数
• src/helpers/parseUtil.ts72-89 addIssueToContext 函数
• src/types.ts92-115 用于处理结果的 handleResult 函数

精炼和转换

验证管道通过精炼和转换扩展了基本类型检查的功能。

细化

精炼允许通过 refine()、refinement() 和 superRefine() 等方法添加自定义验证规则。这些方法创建 ZodEffects 包装器，为管道添加额外的验证步骤。

转换

转换允许在验证过程中使用 transform() 方法更改数据。它们也创建 ZodEffects 包装器，但会更改输出类型。

来源

• src/types.ts353-449 精炼方法
• src/types.ts508-517 转换方法

完整验证流程

完整的验证流程结合了管道中从输入到输出的所有元素

来源

• src/types.ts241-266 parse 和 safeParse 公共方法
• src/types.ts92-115 handleResult 函数
• src/helpers/parseUtil.ts72-89 addIssueToContext 函数

公共 API 方法

用户通过四种主要方法与验证管道交互，这些方法以不同的错误处理方式处理同步和异步验证

方法	描述	返回值	错误处理
parse()	同步验证	已验证数据	抛出 ZodError
safeParse()	安全同步验证	{success: true, data} 或 {success: false, error}	返回错误对象
parseAsync()	异步验证	Promise	以 ZodError 拒绝
safeParseAsync()	安全异步验证	Promise	以结果对象解决

来源

• src/types.ts241-266 parse 和 safeParse 实现
• src/types.ts317-348 parseAsync 和 safeParseAsync 实现