Zod TypeScript: 方法、示例、安装

Zod 简介：它是什么以及为什么需要它

在现代 TypeScript Web 开发中，关键问题之一是确保数据的完整性。即使有严格的类型检查，TypeScript 也无法保证来自外部来源（API、表单、localStorage、WebSocket）的数据确实符合声明的类型。TypeScript 编译器在开发阶段工作，但在程序运行时，类型会被擦除。正是在这里，Zod 派上了用场。

Zod 是一个用于 TypeScript 和 JavaScript 的声明式数据验证和类型化库。它允许您创建模式（schemas），这些模式同时充当运行时的数据验证器和 TypeScript 静态类型的真实来源。Zod 的核心哲学是“一个模式，两个用途”：您只需编写一次模式，即可获得验证和自动推断的类型。

Zod 的主要优势：

类型安全：从模式自动推断 TypeScript 类型。
声明式：可读且简洁的语法。
组合性：模式可以组合和扩展。
详细错误：清晰的验证错误消息。
零依赖：该库不需要额外的包。

安装 Zod

Zod 是一个 npm 包，因此通过 Node.js 包管理器进行安装。该库是用 TypeScript 编写的，并附带现成的类型声明文件，因此不需要额外安装 @types/zod。

# 通过 npm 安装npm install zod

# 通过 yarn 安装yarn add zod

# 通过 pnpm 安装pnpm add zod

安装后，您可以将 Zod 导入到您的项目中：

import { z } from "zod";

请注意：Zod 不能通过 pip 安装，因为它是用于 JavaScript/TypeScript 生态系统的库，而不是 Python。

快速入门与代码示例

让我们创建一个简单的模式来验证用户数据，并立即了解 Zod 如何将验证和类型化结合起来。

import { z } from "zod";

// 1. 定义模式const UserSchema = z.object({    id: z.number().positive(),    name: z.string().min(2, "名称必须至少包含 2 个字符"),    email: z.string().email("无效的电子邮件"),    age: z.number().int().min(18, "年龄必须至少为 18 岁").optional(),});

// 2. 从模式自动推断类型type User = z.infer<typeof UserSchema>;

// 3. 验证数据const validData = {    id: 1,    name: "安娜",    email: "anna@example.com",    age: 25,};

const result = UserSchema.safeParse(validData);

if (result.success) {    // result.data 的类型为 User    console.log("验证成功:", result.data);} else {    // result.error 包含详细的错误信息    console.log("验证错误:", result.error.errors);}

// 无效数据示例const invalidData = {    id: -1,    name: "A",    email: "not-email",};

const invalidResult = UserSchema.safeParse(invalidData);if (!invalidResult.success) {    console.log("错误:", invalidResult.error.errors);    // 将输出：    // - id: 必须为正数    // - name: 名称必须至少包含 2 个字符    // - email: 无效的电子邮件}