函数、Promise 和实例 Schema

相关源文件

• README.md
• README_ZH.md
• deno/lib/README.md
• deno/lib/__tests__/anyunknown.test.ts
• deno/lib/__tests__/instanceof.test.ts
• deno/lib/__tests__/promise.test.ts
• deno/lib/__tests__/string.test.ts
• deno/lib/types.ts
• src/__tests__/instanceof.test.ts
• src/__tests__/promise.test.ts
• src/__tests__/string.test.ts
• src/types.ts

本文档介绍了 Zod 中的三种特殊 Schema 类型：函数 Schema、Promise Schema 和实例 Schema。这些 Schema 允许您验证基本数据类型之外更复杂的 JavaScript 结构。有关原始数据验证的信息，请参阅 原始 Schema。

概述

函数、Promise 和实例 Schema 可让您验证

1. 函数 - 验证函数的输入参数和返回值
2. Promise - 验证 Promise 解析时返回的值
3. 类实例 - 验证一个值是否是特定类的实例

这些 Schema 扩展了基础的 ZodType 类，并与 Zod 的验证流程集成，允许它们与其他 Schema 类型组合使用。

来源： src/types.ts41-577 README.md129-131

函数 Schema

函数 Schema 验证函数的输入参数和返回值。它们在创建类型化的函数签名和确保函数契约一致性方面特别有用。

创建函数 Schema

函数 Schema 使用 z.function(args, returnType) 创建。

• args - 定义参数类型的元组 Schema
• returnType - 定义返回值的 Schema

来源： src/types.ts496-498 README.md131-132

函数实现

函数 Schema 最强大的功能是能够为函数包装运行时类型检查。

implement 方法将您的函数包装在验证逻辑中。

来源： src/__tests__/promise.test.ts67-83 README.md131-132

参数和返回值类型推断

Zod 将自动从您的函数 Schema 推断 TypeScript 类型。

来源： src/__tests__/promise.test.ts14-19 README.md131-132

Promise Schema

Promise Schema 验证一个值是否为 Promise，同时也会根据指定的 Schema 验证解析后的值。

创建 Promise Schema

Promise Schema 使用 z.promise(schema) 创建，其中 schema 定义了解析值的预期类型。

来源： src/__tests__/promise.test.ts8-13 README.md129-130

Promise 验证流程

Promise Schema 首先检查输入是否是 Promise 类对象（具有 then 和 catch 方法），然后返回一个新的 Promise，该 Promise 会：

1. 等待原始 Promise 解析。
2. 使用内部 Schema 验证解析后的值。
3. 返回已验证的值或抛出验证错误。

来源： src/__tests__/promise.test.ts21-60 README.md129-130

展开 Promise Schema

unwrap() 方法允许您访问 Promise Schema 的内部 Schema。

来源： src/__tests__/promise.test.ts90-95

实例 Schema

实例 Schema 使用 JavaScript 的 instanceof 操作符来验证一个值是否是特定类的实例。

创建实例 Schema

实例 Schema 使用 z.instanceof(Class) 创建。

来源： src/__tests__/instanceof.test.ts8-26 README.md130

类的继承支持

实例 Schema 遵循 JavaScript 的继承体系。如果类 B 继承自类 A，那么 B 的实例将可以通过 A 的实例 Schema 的验证。

例如

来源： src/__tests__/instanceof.test.ts8-36 README.md130

实例 Schema 的类型推断

实例 Schema 的推断 TypeScript 类型是类本身。

来源： src/__tests__/instanceof.test.ts35 README.md130

通用模式和集成

这些特殊的 Schema 可以相互组合，也可以与其他 Zod Schema 类型组合，以创建强大的验证模式。

具有已验证返回类型的异步函数

结合函数和 Promise Schema 可以验证异步函数。

来源： src/__tests__/promise.test.ts67-83

类实例方法的验证

结合实例和函数 Schema 可以验证类实例上的方法。

可空和可选的变体

这些 Schema 可以与 .nullable() 和 .optional() 修饰符组合使用。

来源： src/types.ts484-497

性能考量

• 函数 Schema：每次使用 implement() 调用函数时都会触发验证，这会增加开销。建议在 API 边界使用它们，而不是用于大量调用的内部函数。
• Promise Schema：验证仅在 Promise 解析时异步进行，为 Promise 链增加的开销极小。
• 实例 Schema：instanceof 检查速度非常快，这使得这些 Schema 即使在热路径中也具有高性能。

错误处理

所有三种 Schema 类型都与 Zod 的错误处理系统集成。

来源： src/__tests__/instanceof.test.ts38-42 src/__tests__/promise.test.ts42-60

---

这些专门的模式类型扩展了Zod的核心功能，以处理函数、Promise和类实例的复杂JavaScript构造，在TypeScript的静态类型检查结束的地方提供了类型安全和运行时验证。