Schema 转换

相关源文件

• README.md
• README_ZH.md
• deno/lib/README.md
• deno/lib/__tests__/refine.test.ts
• deno/lib/__tests__/transformer.test.ts
• src/__tests__/refine.test.ts
• src/__tests__/transformer.test.ts

此页面介绍了 Zod 的模式转换功能，这些功能允许您在验证期间修改数据、添加自定义验证规则以及操作模式结构。模式转换是一项强大的功能，使您能够创建复杂的验证管道，同时保持类型安全。

有关基本模式类型的信息，请参阅模式类型。有关与转换无关的模式方法的详细信息，请参阅模式方法。

模式转换概述

Zod 提供了多种转换和细化模式的方式

1. 细化（Refinements） - 为模式添加自定义验证规则
2. 转换（Transformations） - 在验证期间转换数据
3. 对象操作（Object Manipulations） - 使用 .pick()、.omit() 和 .partial() 等方法修改对象模式

来源：README.md, src/tests/transformer.test.ts, src/tests/refine.test.ts

细化

细化允许您为模式添加自定义验证规则。这些规则在基本类型验证之后应用。

基本细化

使用 .refine() 方法为任何模式添加验证规则

来源：src/tests/refine.test.ts

.refine() 方法接受一个谓词函数，如果验证通过则返回 true，如果失败则返回 false

示例

您可以提供自定义错误消息并指定错误适用的路径

来源：src/tests/refine.test.ts:86-98

使用细化进行类型收窄

细化还可以使用类型谓词来收窄模式的类型

来源：src/tests/refine.test.ts:52-64

链式细化

您可以将多个细化链接在一起。每个细化都将按顺序执行

如果多个细化失败，Zod 将收集所有错误。

来源：src/tests/refine.test.ts:252-279

超级细化（SuperRefine）

对于更复杂的验证，Zod 提供了 .superRefine() 方法，该方法使您能够访问上下文对象，从而更好地控制错误报告

来源：src/tests/refine.test.ts:129-156

示例

ctx.addIssue() 方法允许您添加具有特定错误代码和消息的自定义问题。

来源：src/tests/refine.test.ts:129-156

异步细化

.refine() 和 .superRefine() 都支持异步验证

来源：src/tests/refine.test.ts:66-85, src/tests/refine.test.ts:159-186

转换

转换允许您在验证期间修改数据。它们在所有验证检查通过后运行。

基本转换

使用 .transform() 方法转换模式的输出

来源：src/tests/transformer.test.ts:95-101

示例

此示例将字符串转换为数字。推断的输入类型是 string，输出类型是 number。

来源：src/tests/transformer.test.ts:7-8, src/tests/transformer.test.ts:95-101

类型强制转换

转换对于不同类型之间的类型强制转换很有用

来源：src/tests/transformer.test.ts:103-112

异步转换

与细化类似，转换也可以是异步的

来源：src/tests/transformer.test.ts:12, src/tests/transformer.test.ts:115-123

链式转换

您可以将多个转换链接起来，以创建复杂的数据管道

来源：src/tests/transformer.test.ts:192-198

转换中的错误处理

您可以在转换中使用上下文参数来添加自定义错误

特殊的 z.NEVER 值可用于中止转换并指示错误情况。这有助于保持正确的类型推断。

来源：src/tests/transformer.test.ts:13-42, src/tests/transformer.test.ts:76-93

对象模式操作

Zod 提供了各种实用方法来操作对象模式。

来源：README.md:100-112

Pick 和 Omit

.pick() 和 .omit() 允许您从对象模式中选择或排除特定键

来源：README.md:103-105

Partial 和 DeepPartial

.partial() 使所有属性变为可选

.deepPartial() 递归地使所有属性变为可选，这对于嵌套对象很有用

来源：README.md:106-107

Extend 和 Merge

.extend() 允许向对象模式添加新属性

.merge() 结合两个对象模式

来源：README.md:103-104

默认值

Zod 提供了 .default() 方法来为模式设置默认值。当输入为 undefined 时，默认值会被应用

您也可以使用函数来生成动态默认值

默认值仅在输入为 undefined 时应用，而不是在为 null 或其他虚假值时应用。

来源：src/tests/transformer.test.ts:136-170

预处理

Zod 允许您使用 z.preprocess() 在验证之前预处理数据

来源: README.md

预处理对于在验证前处理数据类型转换特别有用

高级技巧

结合细化和转换

您可以将细化和转换链式结合，以创建复杂的验证管道

顺序很重要！在转换之前添加的细化作用于输入类型，而在转换之后添加的细化作用于转换后的类型。

来源：src/tests/transformer.test.ts:199-233

转换中的类型推断

使用转换时，您可以利用 Zod 的类型推断来获取正确的输入和输出类型

这使您即使在转换数据时也能在整个应用程序中保持类型安全。

来源：src/tests/transformer.test.ts:172-182

结论

Zod 中的模式转换提供了一种强大的方法，可以在完全类型安全的情况下验证、转换和操作数据。通过结合细化、转换和对象操作，您可以创建根据应用程序需求量身定制的复杂验证管道。

有关更多信息，请参阅

• 添加自定义验证逻辑，请参阅细化（Refinements）
• 在验证期间转换数据，请参阅转换（Transformations）
• 操作对象模式，请参阅组合和操作（Composition and Manipulation）