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 类型验证的资料请关注本站其它相关文章！

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

引言