zod
的 parse
函数是用于 数据验证和类型安全解析 的核心方法,它根据预先定义的 schema 检查输入数据是否符合预期格式.
1. 核心功能
- 验证:检查输入数据是否匹配 schema 规则。
- 转换:将输入数据转换为符合 TypeScript 的类型。
- 错误处理:自动抛出详细的验证错误(
ZodError
)。
2. 基础用法
(1) 定义 Schema
import { z } from "zod";
// 定义用户数据schema
const UserSchema = z.object({
id: z.number().int().positive(),
name: z.string().min(2),
email: z.string().email(),
age: z.number().min(18).optional(),
});
(2) 使用 parse
验证
const rawData = { id: 1, name: "Alice", email: "alice@example.com" };
try {
const user = UserSchema.parse(rawData);
// user 类型被推断为:
// { id: number; name: string; email: string; age?: number }
console.log("验证通过:", user);
} catch (error) {
console.error("验证失败:", error.errors);
}
(3) 错误输出示例
如果 rawData = { id: "1", name: "A", email: "invalid" }
,会抛出:
{
"issues": [
{
"code": "invalid_type",
"expected": "number",
"received": "string",
"path": ["id"],
"message": "Expected number, received string"
},
{
"code": "too_small",
"minimum": 2,
"type": "string",
"path": ["name"],
"message": "String must contain at least 2 character(s)"
},
{
"code": "invalid_string",
"validation": "email",
"path": ["email"],
"message": "Invalid email"
}
]
}
3. 高级用法
(1) 安全解析(不抛出异常)
使用 safeParse
:
const result = UserSchema.safeParse(rawData);
if (result.success) {
console.log(result.data); // 验证通过的数据
} else {
console.log(result.error); // ZodError 对象
}
(2) 组合 Schema
const AddressSchema = z.object({
street: z.string(),
city: z.string(),
});
const UserWithAddressSchema = UserSchema.extend({
address: AddressSchema,
});
(3) 异步验证
const AsyncSchema = z.string().refine(async (val) => {
return await checkUsernameAvailability(val);
}, "用户名已存在");
const result = await AsyncSchema.safeParseAsync("alice");
(4) 自定义错误消息
const PasswordSchema = z
.string()
.min(8, "密码至少8位")
.regex(/[A-Z]/, "必须包含大写字母");
4. 实用场景
(1) API 请求验证
// 定义API响应schema
const ApiResponseSchema = z.object({
success: z.boolean(),
data: z.unknown().optional(),
error: z.string().optional(),
});
fetch("/api/user")
.then((res) => res.json())
.then((json) => ApiResponseSchema.parse(json))
.then((data) => {
/* 类型安全的数据 */
});
(2) 表单验证
// React Hook Form 集成示例
import { useForm } from "react-hook-form";
import { zodResolver } from "@hookform/resolvers/zod";
const form = useForm({
resolver: zodResolver(UserSchema),
defaultValues: { name: "", email: "" },
});
(3) 环境变量验证
const EnvSchema = z.object({
DATABASE_URL: z.string().url(),
API_KEY: z.string().min(32),
NODE_ENV: z.enum(["development", "production"]),
});
EnvSchema.parse(process.env); // 启动时验证环境变量
5. 性能优化
- 预编译 Schema:对高频调用的 schema 提前编译:
const validateUser = UserSchema.parse; // 后续直接调用 validateUser(data)
- 选择性校验:用
pick
/omit
创建子 schema 减少校验范围:const LoginSchema = UserSchema.pick({ email: true });
6. 错误处理最佳实践
try {
const data = schema.parse(input);
} catch (err) {
if (err instanceof z.ZodError) {
// 转换为前端友好格式
const errors = err.issues.map((issue) => ({
field: issue.path.join("."),
message: issue.message,
}));
showToast(errors);
}
}
总结
- 核心方法:
parse()
是 Zod 进行数据验证的入口。 - 核心价值:
- 将动态数据转换为静态类型
- 替代手动编写验证逻辑
- 适用场景:表单、API、配置验证等所有需要数据校验的场景。