Zod 进行 TypeScript 类型验证使用详解

引言

本文旨在介绍如何在项目中利用 Zod 配置类型验证机制。Zod 是一款开源的 TypeScript 库，专注于类型声明与运行时验证。我们将探讨采用 Zod 进行类型验证的理由，提供具体的使用示例，并将其与其他同类库进行对比分析。

什么是类型验证，为什么需要它？

类型验证是指检查数据结构是否符合预设类型的过程。通过这种方式，可以确保输入数据的有效性，同时为代码提供清晰的数据结构文档和执行保障。

采用类型验证主要带来两大优势：

• 运行时数据完整性：确保数据以正确格式进入系统，有助于避免错误并维持数据一致性。尽管 TypeScript 能在编译阶段保证类型安全，但在处理来自服务器或用户输入等未知数据源时，运行时的类型验证显得尤为重要。
• 文档生成：优秀的类型验证库能为数据结构提供精确的类型定义。这些类型定义可用于为项目自动生成静态文档，提升代码的可维护性。

为什么要使用zod？

尽管市面上存在多种 TypeScript 类型校验库，但 Zod 因其特性表现优异。在选择库时，除了功能集，还需考量其实现细节。

• Zod 零依赖：安装和使用 Zod 无需引入其他库，这有助于保持项目包体积最小化。
• 跨平台兼容：Zod 支持 Node.js 及所有主流浏览器（包括 IE 11），非常适合需要兼容多平台的项目。
• TypeScript 优先设计：该库自动为数据结构推断静态 TypeScript 类型，无需在 Zod 和 TypeScript 中分别声明两次。这不仅节省了输入工作量，还能确保代码变更时的类型同步。
• API 简洁且可链式调用：这使得构建复杂数据类型变得简单，并能轻松将简单类型组合为复杂结构。

使用 Zod 进行类型验证的示例

基本类型（Primitives）

首先查看如何验证字符串。假设我们需要验证用户输入的密码，要求其为非空字符串，长度介于 8 到 32 个字符之间：

import { z } from "zod";
const stringSchema = z.string().nonempty().min(8).max(32);
stringSchema.parse("");
stringSchema.parse(""); // throws an exception
stringSchema.parse("I am a valid password"); // returns "I am a valid password"

运行上述代码时，parse 方法会抛出异常。异常对象数组中包含 ZodError 错误的详细描述：

    [
      {
      "code": "too_small",
      "minimum": 1,
      "type": "string",
      "inclusive": true,
      "message": "Should be at least 1 characters",
      "path": []
      },
      {
      "code": "too_small",
      "minimum": 8,
      "type": "string",
      "inclusive": true,
      "message": "Should be at least 8 characters",
      "path": []
      }
    ]

当尝试解析符合要求的字符串时，parse 方法将直接返回该值。

对象验证

接下来讨论对象验证。Zod 对嵌套对象结构的支持非常强大。

我们创建一个用于验证用户对象的类型，包含以下字段：

• 姓名
• 电子邮件
• 电话号码

声明类型时，使用 z.object() 方法：

    import { z } from "zod";
    const User = z.object({
      email: z.string().email(),
      name: z.string(),
      phoneNumber: z.number()
    });

尝试根据刚创建的类型验证示例对象：

    const result = User.parse({
      email: "hi@sample.com",
      name: "Hello World"
    });

parse 方法返回包含解析结果的对象。由于示例中遗漏了 phoneNumber 字段，Zod 将抛出异常，错误数组如下：

    [
      {
      "code": "invalid_type",
      "expected": "number",
      "received": "undefined",
      "inclusive": true,
      "message": "Required"
      "path": ["phoneNumber"]
      }
    ]

类型推断

我们还可以从对象中推断出类型。这是免费获取属性类型定义并在代码中使用的功能：

    type UserType = z.infer<typeof User>;

组合类型

Zod 允许像搭乐高积木一样轻松组合复杂类型。

为了演示，我们使用 User 上面的类型对象，构建一个包含爱好的更详细的用户对象：

    const User = z.object({
      email: z.string().email(),
      name: z.string(),
      phoneNumber: z.number()
    });
    const Hobby = z.object({
      hobbyName: z.string().min(1)
    });
    const Hobbyist = User.merge(Hobby);
    const result = Hobbyist.safeParse({
      email: "hi@sample.com",
      name: "Hello World",
      phoneNumber: 123
    });

通过组合两个类型对象，我们创建了新类型，可用于验证用户对象是否具备正确的爱好字段。

在现有对象基础上组合新对象是良好的实践，有助于保持数据结构中所有更改的同步。

注意事项

使用 Zod 进行验证时，需注意以下几点。

安全解析

若不希望 Zod 在解析失败时抛出异常，可改用 safeParse 方法。该方法返回包含解析结果的对象：

 mySchema.safeParse(""I am a valid password""); // => { success: true; data: "I am a valid password" }    
 mySchema.safeParse(""); // => { success: false; error: ZodError } 

无法识别的 Key 被删除

默认情况下，Zod 在解析过程中会移除无法识别的 key，即忽略任何未知键。

若希望保留无法识别的 key 而不丢失它们，可使用 .passthrough() 方法。

其他事项

.array() 方法返回新的 ZodArray 实例，因此调用顺序至关重要。切换链中调用顺序可能导致完全不同的结果：

z.string().optional().array(); // (string | undefined)[]  
z.string().array().optional(); // string[] | undefined

Zod 与其他库的比较

其他广泛使用的类型验证库也是不错的选择，例如 yup 和 io-ts。

以下是选择 Zod 的一些理由：

• TypeScript 原生支持。Zod 构建时即考虑 TypeScript，提供一流支持，包括自动完成和出色的 VsCode 支持。
• 无需额外工作即可获取类型。
• 易于组合的类型对象 - 通过组合不同类型的对象来构建复杂的验证规则。
• 强大的错误处理。Zod 具备丰富的 API 用于配置错误处理流程。
• 支持 Promise 和函数模式。如需验证函数或 Promise，Zod 可满足需求。

结论

本文介绍了如何使用 Zod 库进行 TypeScript 类型验证。我们探讨了创建类型并使用其验证数据结构的方法，以及使用 Zod 时的注意事项和相对于其他库的优势。

如需更多关于 Zod 的信息，可查阅其 Github 页面上的优秀文档。

更多关于 Zod TypeScript 类型验证的资料请关注本站其它相关文章！