当前位置：首页 > news >正文

【Zod 】数据校验新范式：Zod 在 TypeScript 项目中的实战指南

news 2025/9/22 17:10:02

一、背景指南

参考： Zod 官网

在 TypeScript 项目中，开发者常常陷入这样的困境：接口返回的 id 字段时而为字符串、时而为数字，用户提交的表单数据中邮箱字段可能混入特殊字符，甚至后端返回的 JSON 数据结构与文档描述完全不符。

这些动态数据的不可控性，让 TypeScript 的静态类型优势在运行时变得脆弱不堪。

直到 Zod 的出现，这座连接运行时验证与静态类型系统的桥梁，彻底改变了数据校验的游戏规则。

zod 是一个存粹的 TypeScrip库, 它不依赖于任何的前端框架。

二、安装使用

eg：以 pnpm 为例进行安装使用

pnpm add zod

安装要求

Zod 在 TypeScript v5.5 及更高版本中进行了测试。较旧的版本可能也能运行，但不提供官方支持。

strict 配置：查找 tsconfig.json 或者 tsconfig.app.json 文件

// 必须在 tsconfig.json 文件中启用严格模式。这是适用于所有 TypeScript 项目的最佳实践。
{// ..."compilerOptions": {// ..."strict": true}
}

三、Zod 的核心价值：一次定义，双重保障

传统数据校验方案存在三大痛点：

重复劳动：需同时维护 TypeScript 类型声明和校验逻辑
运行时盲区：TypeScript 无法拦截 null 或格式错误的动态数据
错误信息模糊：校验失败时难以快速定位问题字段

Zod 通过独特的机制实现「定义即真理」：

import { z } from 'zod';// Schema 
const UserSchema = z.object({id: z.string().uuid({ message: "ID 必须是 UUID 格式" }),username: z.string().min(3, "用户名至少3个字符"),email: z.string().email("无效的邮箱格式"),age: z.number().int().positive().optional(),hobbies: z.array(z.string()).nonempty("至少有一个爱好"),role: z.enum(["user", "admin"]).default("user")
});// 自动生成 TypeScript 类型（通过定义的 Schema 反推 TypeScript 类型）
type User = z.infer<typeof UserSchema>;

这段代码不仅定义了数据结构，还同时获得了：

精确的 TypeScript 类型推断
详细的运行时校验规则
自定义错误消息系统
默认值处理能力

四、实战场景：构建健壮的 Web 应用

1. 数据校验

基础使用

import { useState } from 'react';
import { z } from 'zod';// 定义用户 Schema
const UserSchema = z.object({id: z.string().uuid({ message: "ID 必须是 UUID 格式" }),username: z.string().min(3, "用户名至少3个字符"),email: z.string().email("无效的邮箱格式"),age: z.number().int().positive().optional(),hobbies: z.array(z.string()).nonempty("至少有一个爱好"),role: z.enum(["user", "admin"]).default("user")
});// 通过 Schema 反推用户类型，便于类型检查和自动补全
type User = z.infer<typeof UserSchema>;const App = () => {// 初始化待验证的人员数据const [person] = useState<User>({id: '00000000-0000-0000-0000-000000000000',username: '王老七',age: 25,email: 'zhangsan@example.com',hobbies: ['篮球', '足球', '游泳'],role: 'user',
});// 使用 safeParse 方法对数据进行校验，返回 success 和 data/error
const result = UserSchema.safeParse(person);return (<><h1>Zod 验证示例</h1><pre>{// 根据校验结果展示不同的信息result.success? '验证通过: ' + JSON.stringify(result.data, null, 2): '验证失败: ' + JSON.stringify(result.error.issues, null, 2)}</pre></>
);
};export default App;

2. 嵌套验证：复杂数据结构处理

const AddressSchema = z.object({street: z.string(),city: z.string(),zipCode: z.string().regex(/^\d{5}(-\d{4})?$/)
});const OrderSchema = z.object({id: z.string().uuid(),items: z.array(z.object({productId: z.string().uuid(),quantity: z.number().min(1)})).min(1),shippingAddress: AddressSchema,billingAddress: AddressSchema.optional(),status: z.enum(["pending", "shipped", "delivered", "cancelled"])
});

3.条件验证：动态规则应用

const SubscriptionSchema = z.object({plan: z.enum(["free", "pro", "enterprise"]),features: z.array(z.string()),billing: z.object({interval: z.enum(["monthly", "annual"]),amount: z.number().positive()}).optional()
}).refine((data) => data.plan !== "free" || !data.billing,{ message: "免费套餐不应包含账单信息" }
);