枚举和记录

相关源文件

• README.md
• README_ZH.md
• deno/lib/README.md
• deno/lib/__tests__/enum.test.ts
• deno/lib/__tests__/record.test.ts
• src/__tests__/anyunknown.test.ts
• src/__tests__/enum.test.ts
• src/__tests__/record.test.ts

本页面介绍了 Zod 中两种强大的 schema 类型：枚举（Enums）和记录（Records）。这些 schema 分别提供了验证和类型化枚举值以及键值对的方法。两者都是创建复杂数据验证 schema 的基本构建块。

枚举

Zod 的枚举 schema 验证器允许你针对一组固定的字符串字面量值进行验证。它还会生成与这些值对应的 TypeScript 类型。

创建枚举

你可以通过调用 z.enum() 并传入一个字符串字面量数组来创建枚举 schema。

如果你需要在数组声明中获得类型安全，可以使用 as const。

来源: src/__tests__/enum.test.ts7-12 src/__tests__/enum.test.ts25-32

枚举属性

Zod 枚举 schema 暴露了几个属性来访问枚举值

来源: src/__tests__/enum.test.ts7-12 src/__tests__/enum.test.ts20-22

类型推断

Zod 的优点之一是它能够从 schema 中推断 TypeScript 类型。

这会创建一个字符串字面量联合类型，TypeScript 可以用它进行类型检查。

来源: src/__tests__/enum.test.ts14-18

枚举图示

来源: src/__tests__/enum.test.ts7-18

提取和排除

Zod 枚举提供了通过包含或排除特定值来创建新枚举的方法

这些方法默认保留原始枚举的错误映射，但你可以提供自定义错误映射。

来源: src/__tests__/enum.test.ts44-84

自定义错误消息

你可以自定义枚举验证错误消息。

来源: src/__tests__/enum.test.ts34-42

记录（Records）

Zod 中的记录表示键值对，其中键和值都符合特定的 schema。它们对于建模字典状对象特别有用。

创建记录

最基本的记录具有字符串键和特定类型的值。

第一个例子使用了简写语法，其中键 schema 默认为 z.string()。第二个例子明确指定了键和值 schema。

来源: src/__tests__/record.test.ts7-8 src/__tests__/record.test.ts130-135

键 schema 选项

虽然最常见的键 schema 是 z.string()，但你可以使用枚举或字面量联合类型来限制键为特定值。

这两种方法都会创建一个记录，其中只有 "Tuna" 和 "Salmon" 是有效键，每个键都具有字符串值。

来源: src/__tests__/record.test.ts10-17 src/__tests__/record.test.ts73-123

记录属性

记录 schema 暴露了用于访问其组成 schema 的属性。

来源: src/__tests__/record.test.ts130-135

记录图示

来源: src/__tests__/record.test.ts7-31 src/__tests__/record.test.ts130-135

记录的类型推断

记录的类型推断取决于键 schema。

1. 使用字符串键时，你会得到一个标准的 TypeScript Record<string, V>。

2. 使用枚举或字面量键时，你会得到一个 Partial<Record<K, V>>。

Partial 意味着并非所有键都需要存在。

来源: src/__tests__/record.test.ts19-31

记录方法

记录具有与其他 Zod schema 相同的链式方法。

来源: src/__tests__/record.test.ts33-36

验证示例

记录根据其各自的 schema 验证键和值。

来源: src/__tests__/record.test.ts38-54 src/__tests__/record.test.ts73-123

安全考量

Zod 记录被设计成能够安全地防御原型污染攻击。

来源: src/__tests__/record.test.ts137-172

比较和使用案例

以下是何时使用每种 schema 类型的比较：

功能	枚举（Enum）	记录（Record）
目的	针对固定字符串值集进行验证	验证具有动态键的对象
键验证	不适用	可选（默认：任意字符串）
值验证	仅限固定字符串字面量	任何 Zod schema
TypeScript 输出	字符串字面量联合类型	Record<K, V> 或 Partial<Record<K, V>>
常见用例	状态码、选项选择	字典、查找表、元数据

与其他 Schema 集成

枚举和记录都可以作为大型 schema 的构建块。

集成图示

来源: README.md96-98 README.md120-122

本维基页面全面概述了 Zod 的枚举和记录 schema，展示了如何单独使用它们以及如何结合使用它们来创建功能强大的验证 schema，并实现精确的 TypeScript 类型推断。