基本用法示例

相关源文件

• README.md
• README_ZH.md
• deno/lib/README.md
• deno/lib/__tests__/nullable.test.ts
• deno/lib/__tests__/optional.test.ts
• deno/lib/__tests__/primitive.test.ts
• deno/lib/__tests__/validations.test.ts
• deno/lib/helpers/util.ts
• playground.ts
• src/__tests__/nullable.test.ts
• src/__tests__/primitive.test.ts
• src/__tests__/validations.test.ts
• src/helpers/util.ts

本页演示了 Zod（一个 TypeScript 优先的 schema 声明和验证库）的基本用法模式。它提供了创建 schema、验证数据以及利用 TypeScript 类型推断功能的实用示例。有关高级转换和精炼，请参阅Schema 转换。

验证工作流

Zod 的核心是遵循“解析，而非仅验证”的方法，其中输入数据通过 schema 进行处理，这些 schema 既验证又转换数据。

来源：README.md:667-684

基本类型

Zod 为所有 JavaScript 原始类型提供了内置验证方法的 schema。

字符串 Schema

字符串 schema 验证输入是否为字符串，并可包含额外约束

来源：README.md:674-684, src/tests/primitive.test.ts:14-24, src/tests/validations.test.ts:44-80

数字 Schema

数字 schema 验证数值，并可包含可选约束，如最小值/最大值

来源：README.md:710-715, src/tests/primitive.test.ts:15-25, src/tests/validations.test.ts:82-140

布尔 Schema

布尔 schema 验证输入为 true 或 false

来源：README.md:717, src/tests/primitive.test.ts:17-27

字面量 Schema

字面量 schema 验证输入是否与精确值匹配

来源：README.md:794-807, src/tests/primitive.test.ts:8-13

对象 Schema

对象 schema 验证具有特定类型属性的对象的结构。

基本对象 schema 示例

来源：README.md:686-700, playground.ts:5-10

数组 Schema

数组 schema 验证数组并带有元素特定的验证规则。

数组验证示例

来源：README.md:113-116, src/tests/validations.test.ts:6-41

联合类型

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

联合 schema 示例

来源：README.md:118-121, README.md:872-889

可选和可空类型

Zod 提供了使 schema 接受 undefined 或 null 的方法。

示例

来源：README.md:98-99, src/tests/optional.test.ts:21-37, src/tests/nullable.test.ts:20-37

Schema 方法

所有 Zod schema 都提供核心的验证和转换方法。

解析方法

这些方法根据 schema 验证输入

方法	描述	返回值	错误处理
parse()	验证输入	有效值（已类型化）	抛出 ZodError
safeParse()	安全验证输入	{success: true, data: value} 或 {success: false, error: ZodError}	返回对象
parseAsync()	异步验证	有效值的 Promise	拒绝并抛出 ZodError
safeParseAsync()	异步安全验证	结果对象的 Promise	解析为结果

使用示例

来源：README.md:674-684, README.md:134-139

类型推断

Zod 的主要特性之一是自动类型推断。

示例

来源：README.md:686-700

常见 Schema 创建模式

以下是创建和组合 schema 的一些常见模式

带约束的验证

大多数 schema 类型都有约束方法

来源：README.md:815-850, README.md:91-92, src/tests/validations.test.ts:142-155

类型强制转换

Zod 提供了类型强制转换方法，可以自动将输入转换为所需的类型

来源：README.md:734-756

默认值

可以为 schema 提供默认值

来源：playground.ts:5-9

错误处理

当验证失败时，Zod 通过 ZodError 对象提供详细的错误信息。

错误示例

来源：src/tests/validations.test.ts:62-69, src/tests/validations.test.ts:82-89

使用技巧

1. 类型推断：始终使用 z.infer<typeof schema> 从您的 schema 中获取 TypeScript 类型
2. 错误处理：当您希望优雅地处理验证错误时，请使用 safeParse()
3. 组合：通过组合更简单的 schema 来构建复杂的 schema
4. 不变性：Schema 方法返回新的 schema 而非修改现有 schema

来源：README.md:185-196