细化

相关源文件

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

细化功能是 Zod 中一项强大的功能，它允许您向模式添加自定义验证逻辑。虽然 Zod 的内置验证器处理基本的类型检查，但细化功能使您能够表达超越简单类型验证的复杂、领域特定的验证规则。本页面介绍了如何使用细化功能来增强您的模式验证。有关验证期间数据转换的信息，请参阅转换。

细化功能概述

细化功能为现有模式添加约束，而不改变其输出类型（除非使用类型谓词）。它们允许您在值通过基本类型检查后，仍能验证其是否符合特定条件。

来源：src/types.ts353-398 README.md139-143

使用 .refine() 添加细化功能

添加细化功能的最常见方式是通过 .refine() 方法，该方法适用于所有 Zod 模式。

基本语法

checkFunction 接收验证过的值，如果值通过细化则应返回 true，如果失败则返回 false。当细化失败时，Zod 会在结果中添加一个自定义验证错误。

来源：src/types.ts353-398 src/__tests__/refine.test.ts8-29

示例：基本用法

这是一个向对象模式添加细化功能的简单示例

此细化功能确保 password 和 confirmPassword 字段具有相同的值。如果它们不匹配，Zod 将抛出错误，并显示消息“密码不匹配”。

来源：src/__tests__/refine.test.ts31-50

自定义错误消息和路径

错误消息

您可以提供一个简单的字符串作为错误消息，也可以使用一个对象来指定更多细节

自定义错误路径

默认情况下，细化错误与整个模式关联。但是，您可以指定错误应附加到哪个路径

这对于表单验证特别有用，您希望在特定输入字段旁边显示错误。

来源：src/__tests__/refine.test.ts86-98 src/types.ts353-398

使用细化功能进行类型收窄

细化功能的一个强大特性是它们能够使用 TypeScript 的类型谓词来收窄类型

在此示例中，细化功能将类型从 string 收窄为字面量 "a"。从该模式推断出的 TypeScript 类型将是字面量 "a"，而不是 string。

细化功能也可用于更复杂的类型收窄

这使您能够创建具有精确类型定义的模式，以反映真实的运行时约束。

来源：src/__tests__/refine.test.ts52-64 src/__tests__/refine.test.ts187-212

使用 .superRefine() 进行高级细化

对于更复杂的验证场景，Zod 提供了 .superRefine() 方法，通过上下文对象提供更大的控制力

ctx 对象包含

• addIssue：添加自定义验证问题的函数
• path：当前验证路径

通过 .superRefine()，您可以

• 在单个细化中添加多个问题
• 自定义问题代码和参数
• 访问验证路径
• 添加致命错误以停止验证

来源：src/types.ts436-449 src/__tests__/refine.test.ts129-156

示例：使用 .superRefine() 进行高级验证

此示例展示了如何使用 .superRefine() 在单个细化中执行多个验证并添加特定问题类型。

来源：src/__tests__/refine.test.ts129-156

异步细化

.refine() 和 .superRefine() 都通过返回 Promise 支持异步验证

使用异步细化时，您必须使用异步解析方法

• .parseAsync()
• .safeParseAsync()

来源：src/__tests__/refine.test.ts66-84 src/__tests__/refine.test.ts158-185

链式多个细化功能

您可以链式调用多个细化功能来应用多个验证规则

每个细化功能接收上一个验证步骤的输出。如果多个细化功能失败，Zod 将所有问题收集到一个错误对象中。

来源：src/__tests__/refine.test.ts252-279

细化功能内部工作原理

在内部，当您向模式添加细化功能时，Zod 会创建一个 ZodEffects 实例，该实例包装原始模式。这与用于转换的机制相同，但效果类型不同。

细化函数存储在 ZodEffects 实例的 effect 属性中，并在基本模式验证完成后，在验证过程中执行。

来源：src/types.ts425-434

与转换的关系

细化功能与转换密切相关，但用途不同

• 细化功能：验证数据而不改变其形状或类型（类型谓词除外）
• 转换功能：将数据从一种形状或类型转换为另一种

这两个功能在内部都使用 ZodEffects 类，但

• 细化功能使用 "refinement" 效果类型
• 转换功能使用 "transform" 效果类型

有关转换的更多信息，请参阅转换。

来源：src/types.ts425-434 src/types.ts508-517

总结

细化功能扩展了 Zod 的验证能力，允许您定义超出简单类型检查的自定义验证规则。要记住的关键点：

1. 使用 .refine() 进行简单验证规则
2. 使用 .superRefine() 进行具有完全控制权的高级验证
3. 指定自定义错误消息和路径，以获得更好的错误报告
4. 使用类型谓词来收窄输出类型
5. 链式调用多个细化功能以实现复杂验证逻辑
6. 支持使用返回 Promise 的细化功能进行异步验证

这项强大的功能使您能够创建精确且富有表达力的验证模式，以处理复杂的业务规则和领域特定约束。