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

2024-04-02 19:04:59 701人浏览安东尼

摘要

目录引言什么是类型验证，为什么需要它？为什么要使用zod？使用 Zod 进行类型验证的示例Primitives对象类型推断组合类型注意事项安全解析无法识别的Key被删除其他事项Zod

引言

这篇文章将描述如何使用Zod 为您的项目设置类型验证。Zod 是一个用于类型声明和验证的开源 typescript 库。我们将研究为什么使用 Zod 进行类型验证，提供如何使用它的示例，并将其与其他库进行比较。

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

类型验证是验证数据结构是否符合特定类型的过程。您可以使用它来确保输入数据的有效性，以及记录和执行代码的数据结构。

使用类型验证有两个主要好处：

运行时的数据完整性：确保数据以正确的格式输入您的系统有助于避免错误并保持数据一致性。虽然 TypeScript 可以帮助您在编译时确保类型安全，但当您处理来自未知数据（例如服务器或用户输入）的数据时，类型验证在运行时会大放异彩。
文档：一个好的类型验证库将为您使用的数据结构提供准确的类型定义。类型定义可用于为您的项目生成静态文档。

为什么要使用zod？

虽然有许多 TypeScript 类型校验库，但个人认为 Zod 是比较好的之一。在为您的项目选择库时，除了其功能集外，您还应考虑其实现细节。

Zod 具有零依赖性，这意味着您可以在没有任何其他库的情况下安装和使用 Zod，它将帮助您保持更小的包大小。
Zod 适用于 node.js 和所有主流浏览器（包括 IE 11）。这使其成为需要支持各种平台的项目的不错选择。
Zod 被设计为 TypeScript 优先，这意味着该库将自动为您的数据结构推断静态 TypeScript 类型。这消除了两次声明类型的需要——一次在 Zod 中，一次在 TypeScript 中。它将为您节省大量输入，并帮助您保持代码更改同步。
Zod 的 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都将被忽略。

如果您想通过无法识别的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 可以满足您的需求。