核心架构

相关源文件

• deno/lib/ZodError.ts
• deno/lib/__tests__/string.test.ts
• deno/lib/types.ts
• src/ZodError.ts
• src/__tests__/string.test.ts
• src/index.ts
• src/types.ts

本文档概述了 Zod 的核心架构，解释了其基本组件、它们之间的关系以及验证期间的数据流。有关单个模式类型的具体详细信息，请参阅模式类型；有关验证管道的信息，请参阅验证管道。

基础设计

Zod 围绕 TypeScript 优先的理念构建，该理念在提供运行时验证的同时实现强大的类型推断。其核心架构遵循以下几个关键原则：

1. 组合式设计：所有模式类型都派生自一个抽象基类
2. 不可变模式：对模式的操作返回新实例，而不是修改现有实例
3. 统一验证接口：所有模式类型的数据验证都采用一致的 API
4. 丰富的错误报告：提供全面且可定制格式的错误处理

来源：src/types.ts169-577 src/ZodError.ts200-323

类型系统层级

Zod 的核心是抽象类 ZodType，它定义了所有模式类型的接口和通用功能。此泛型类具有三个类型参数：

• Output：成功解析数据的 TypeScript 类型
• Def：类型定义（模式配置）
• Input：预期输入类型（默认为 Output）

来源：src/types.ts169-577 src/types.ts773-1065

解析上下文和状态管理

在验证过程中，Zod 通过 ParseContext 和 ParseStatus 类维护当前验证状态的上下文。ParseContext 包含有关正在验证的数据、其在对象结构中的路径以及一组验证问题的信息。ParseStatus 跟踪验证是否“已修改”或无效。

来源：src/types.ts92-115 src/types.ts209-226 src/helpers/parseUtil.ts

公共验证 API

Zod 提供了几种用于数据验证的方法：

方法	描述	成功返回	失败行为
parse(data)	同步验证	已验证的数据	抛出 ZodError
safeParse(data)	安全同步验证	{ success: true, data }	{ success: false, error }
parseAsync(data)	异步验证	已验证数据的 Promise	用 ZodError 拒绝
safeParseAsync(data)	安全异步验证	{ success: true, data } 的 Promise	{ success: false, error } 的 Promise

这些方法在 ZodType 基类中实现，并由所有模式类型继承。

来源：src/types.ts241-348

验证流程

当模式验证数据时，它遵循特定的顺序

对于 safeParse 操作，结果会被封装在一个成功/错误对象中，而不是抛出错误。

来源：src/types.ts228-266 src/ZodError.ts200-270

错误处理系统

Zod 拥有一个以 ZodError 类为中心的全面错误报告系统。验证问题在验证过程中收集，并可以以各种方式格式化：

来源：src/ZodError.ts200-323 src/helpers/parseUtil.ts

模式转换和细化

Zod 模式是不可变的，但可以通过各种返回新模式实例的方法进行转换和细化：

• 细化：refine(), superRefine() - 添加自定义验证规则
• 转换：transform() - 修改输出值
• 组合：optional(), nullable(), array(), or(), and() - 创建组合模式

来源：src/types.ts353-449 src/types.ts483-576

不可变性和方法链

所有模式转换方法都返回新的模式实例，而不是修改原始实例。这使得模式定义可以实现流畅的方法链式调用。

const UserSchema = z.object({
  email: z.string().email(),
  age: z.number().min(18).max(120),
  name: z.string().min(2).optional()
});

这种方法在整个模式定义过程中保持了不可变性。

来源：src/types.ts451-482

结论

Zod 的核心架构围绕组合式类型系统构建，以 ZodType 抽象类为基础。验证过程遵循所有模式类型的一致模式，并通过 ZodError 类提供全面的错误报告。该系统的不可变设计使得模式定义能够实现强大的方法链式调用，同时保持类型安全。

该架构支持广泛的模式组合和转换，使得 Zod 在 TypeScript 应用程序中验证数据时既灵活又健壮。