Zod — TypeScript 数据验证

什么是 Zod？

Zod 是一个用 TypeScript 编写的声明式数据验证和解析库。它允许你描述数据模式（模式是严格的类型描述），并检查任何对象、字符串、数字等是否符合这些模式。Zod 的主要特点是完全集成 TypeScript：基于模式自动推断类型，从而避免重复定义。

为什么需要数据验证？

在实际应用中，数据通常来自外部来源（API、表单、配置文件、localStorage）。没有验证，很容易出现 bug、XSS 攻击或意外行为。Zod 确保数据符合预期的结构，并在出现问题时抛出清晰的错误信息。

安装

npm install zod

该库无需额外配置，既可在 Node.js 中运行，也可在浏览器中（配合 bundler）使用。

主要功能

创建模式：z.string()、z.number()、z.object()、z.array() 等。
解析和验证：.parse() 方法返回数据或抛出错误；.safeParse() 返回包含 success/data/error 字段的对象。
转换：.transform() 允许在成功验证后修改数据。
Refine：通过 .refine() 进行自定义检查。
类型推断：z.infer<typeof schema> 生成 TypeScript 类型。

TypeScript 代码示例

import { z } from 'zod';

// 定义用户模式const UserSchema = z.object({  id: z.number().int().positive(),  name: z.string().min(2).max(50),  email: z.string().email(),  age: z.number().min(18).max(120).optional(),  role: z.enum(['admin', 'user', 'guest'])});

// 基于模式推断类型type User = z.infer<typeof UserSchema>;

// 使用 safeParse 进行安全验证const rawData = {  id: 1,  name: '安娜',  email: 'anna@example.com',  age: 25,  role: 'admin'};

const result = UserSchema.safeParse(rawData);if (result.success) {  console.log('数据有效:', result.data);} else {  console.error('错误:', result.error.errors);}