对象 Schema

相关源文件

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

Zod 中的对象模式提供了一种验证和类型化 JavaScript/TypeScript 对象功能的强大方式。它们允许您定义对象的结构，包括必需和可选属性，并通过各种策略处理未知属性。本页将介绍 Zod 中对象模式的创建、配置和操作。

有关验证字符串或数字等原始值的信息，请参阅 原始模式。有关数组验证，请参阅 数组和元组模式。

创建对象模式

要创建对象模式，请使用 z.object() 函数，并提供一个将属性名称映射到其各自模式类型的结构定义。

来源： README.md686-700 src/__tests__/object.test.ts7-13

对象模式验证

创建对象模式后，您可以使用 .parse() 或 .safeParse() 方法来验证对象

来源： README.md667-684 src/__tests__/object.test.ts43-64

结构属性

对象模式的 shape 属性让您可以访问各个属性的模式。这对于创建派生模式或访问特定属性的验证规则非常有用。

来源： src/__tests__/object.test.ts31-41

对象模式方法

处理未知键

默认情况下，Zod 对象模式是非严格的，这意味着它们允许存在模式中未定义的属性。处理未知键有三种策略：

来源： README.md100-112 src/__tests__/object.test.ts70-115

您可以链式调用这些方法来覆盖之前的行为。

来源： src/__tests__/object.test.ts87-96

Catchall 验证

.catchall() 方法允许您为所有未知属性定义一个模式。

Catchall 验证会覆盖严格模式，这意味着只要未知键通过 catchall 模式验证，它们就是允许的。

来源： README.md112 src/__tests__/object.test.ts117-193

修改对象模式

扩展对象

.extend() 方法为现有对象模式添加新属性。

来源： README.md104

合并对象

.merge() 方法将两个对象模式组合在一起。如果两个模式具有同名属性，则第二个模式的属性会覆盖第一个模式的属性。

如果存在冲突的属性，则以第二个模式的属性类型为准。

来源： README.md105 src/__tests__/object.test.ts220-224

Pick 和 Omit

.pick() 和 .omit() 方法创建新的模式，只包含选定的属性或移除指定的属性。

来源： README.md106 src/__tests__/object.test.ts272-278

Partial 和 DeepPartial

.partial() 方法使所有属性都变成可选的。

对于嵌套对象，请使用 .deepPartial() 以递归方式使任何级别的所有属性都变成可选的。

来源： README.md106-107 src/__tests__/object.test.ts264-270

对象模式层级

下图展示了 ZodObject 在 Zod 类型系统层级中的位置。

来源： src/types.ts45-53

通过对象模式进行类型推断

Zod 的一个关键特性是自动类型推断。当您定义一个对象模式时，TypeScript 可以自动推断出相应的静态类型。

类型推断适用于所有对象模式方法。

来源： README.md700 src/__tests__/object.test.ts15-24 src/__tests__/object.test.ts226-246

对象模式验证流程

下图展示了对象模式如何验证输入数据。

来源： src/types.ts169-577

处理可选属性

当对象包含可选属性时，它们可能存在也可能不存在于验证后的输出中。

Zod 保留了显式设置的 undefined 值与省略的属性之间的区别。

来源： src/__tests__/object.test.ts165-177

使用 .keyof() 提取键

.keyof() 方法创建一个包含对象模式键的 ZodEnum。

这对于创建可处理对象属性子集的动态验证器很有用。

来源： README.md102 src/__tests__/object.test.ts248-261

最佳实践

1. 开始时严格：从严格的模式开始，然后根据需要放宽约束，而不是从宽松的验证开始。

2. 类型复用：利用类型推断，避免在 TypeScript 和 Zod 之间重复类型定义。

3. 提取通用模式：对于模式中可重用的部分，创建单独的模式常量来组合更大的模式。

4. 处理未知数据：根据您的用例选择正确的未知键策略。

   • 使用 .strict() 来处理内部数据，您需要捕获拼写错误和意外属性。
   • 使用 .strip()（默认）来处理外部数据，此时您只关心已定义的属性。
   • 使用 .passthrough() 来保留所有传入数据。

5. 复杂对象：对于深度嵌套的对象，请考虑增量构建模式。

来源： README.md100-113

总结

对象模式是 Zod 最强大的功能之一，它允许您为 JavaScript/TypeScript 对象定义复杂的验证规则。主要功能包括：

• 具有必需和可选属性的对象形状定义
• 对未知属性处理的控制（strict、strip、passthrough）
• 模式操作（extend、merge、pick、omit、partial）
• 自动 TypeScript 类型推断
• 嵌套对象的深度验证
• 动态属性的 catchall 验证

这些功能使得 Zod 对象模式成为验证 API 请求、配置对象、表单数据以及应用程序中其他结构化信息的理想选择。