前端TypeScript数据校验库Zod的快速上手指南

npm install zod
# 或 yarn/pnpm
pnpm add zod

// src/utils/validate.ts
import { z } from 'zod';

// 1. 定义校验规则（Schema）
const UserSchema = z.object({
  // 必选字符串，非空
  username: z.string().min(2, '用户名至少2个字符').max(20),
  // 可选数字，大于0
  age: z.number().optional().positive('年龄必须为正数'),
  // 邮箱格式校验
  email: z.string().email('请输入正确的邮箱格式'),
  // 枚举值限制
  role: z.enum(['admin', 'user', 'guest'], '角色只能是admin/user/guest'),
  // 嵌套对象
  address: z.object({
    city: z.string(),
    street: z.string().optional()
  })
});

// 2. 提取 TS 类型（无需手动写 interface）
type User = z.infer<typeof UserSchema>;

// 3. 校验数据
function validateUser(data: unknown) {
  try {
    // 严格校验：不符合规则会抛错
    const validData = UserSchema.parse(data);
    console.log('校验通过', validData);
    return { success: true, data: validData };
  } catch (error) {
    // 捕获错误并格式化
    if (error instanceof z.ZodError) {
      const errMsg = error.errors.map(item => ({
        field: item.path.join('.'), // 错误字段（如 address.city）
        message: item.message       // 错误提示
      }));
      return { success: false, errors: errMsg };
    }
    return { success: false, errors: [{ field: 'unknown', message: '未知错误' }] };
  }
}

// 测试：校验合法数据
const validUser = {
  username: '张三',
  email: 'zhangsan@test.com',
  role: 'user',
  address: { city: '北京' }
};
console.log(validateUser(validUser)); // success: true

// 测试：校验非法数据
const invalidUser = {
  username: '张', // 长度不足
  email: '123',   // 邮箱格式错误
  role: 'super',  // 枚举值错误
  address: { city: 123 } // 类型错误
};
console.log(validateUser(invalidUser)); 
// success: false，errors 包含所有错误字段和提示

<!-- src/components/LoginForm.vue -->
<template>
  <form @submit.prevent="submitForm">
    <input v-model="form.email" placeholder="邮箱" />
    <div v-if="errors.email">{{ errors.email }}</div>
    
    <input v-model="form.password" placeholder="密码" />
    <div v-if="errors.password">{{ errors.password }}</div>
    
    <button type="submit">提交</button>
  </form>
</template>

<script setup lang="ts">
import { ref } from 'vue';
import { z } from 'zod';

// 定义表单校验规则
const LoginSchema = z.object({
  email: z.string().email('请输入正确的邮箱'),
  password: z.string().min(6, '密码至少6位')
});
type LoginForm = z.infer<typeof LoginSchema>;

// 表单数据
const form = ref<LoginForm>({ email: '', password: '' });
const errors = ref<Record<string, string>>({});

// 提交表单
const submitForm = () => {
  // 清空之前的错误
  errors.value = {};
  
  // 校验数据（safeParse 不抛错，返回结果）
  const result = LoginSchema.safeParse(form.value);
  if (!result.success) {
    // 格式化错误信息
    result.error.errors.forEach(item => {
      errors.value[item.path[0]] = item.message;
    });
    return;
  }
  
  // 校验通过，调用接口
  console.log('表单数据合法', result.data);
};
</script>

// src/api/user.ts
import { z } from 'zod';
import axios from 'axios';
// 定义 API 响应规则
const UserListSchema = z.array(
  z.object({
    id: z.number(),
    name: z.string(),
    avatar: z.string().url().optional() // 可选URL
  })
);
// 请求接口并校验响应
async function getUserList() {
  const res = await axios.get('/api/users');
  // 校验响应数据，确保符合预期
  const validData = UserListSchema.parse(res.data);
  return validData;
}

// src/utils/env.ts
import { z } from 'zod';

// 定义环境变量规则
const EnvSchema = z.object({
  VITE_API_BASE: z.string().url('API地址必须是合法URL'),
  VITE_GA_ID: z.string().optional()
});

// 校验 Vite 环境变量
const env = EnvSchema.parse(import.meta.env);
// 导出类型安全的环境变量
export default env;