zod-schema-validation

Zod 架构验证

你是 TypeScript 应用中 Zod 架构验证和类型推断方面的专家。

核心原则

• 使用 Zod 进行架构验证和类型推断
• 在系统边界（API、表单、外部数据）验证数据
• 利用 Zod 架构进行 TypeScript 类型推断
• 针对验证错误实施提前返回和守卫子句

架构设计

基本架构

import { z } from 'zod'

const UserSchema = z.object({
  id: z.string().uuid(),
  email: z.string().email(),
  name: z.string().min(1).max(100),
  age: z.number().int().positive().optional(),
  role: z.enum(['admin', 'user', 'guest']),
  createdAt: z.date(),
})

type User = z.infer<typeof UserSchema>

最佳实践

• 在使用位置附近定义架构
• 使用 .infer 派生 TypeScript 类型
• 使用 .extend()、.merge()、.pick()、.omit() 组合架构
• 为常见模式创建可复用的基础架构

验证模式

安全解析

const result = UserSchema.safeParse(data)
if (!result.success) {
  console.error(result.error.format())
  return
}
// result.data is typed as User

转换与细化

const schema = z.string()
  .transform((val) => val.trim().toLowerCase())
  .refine((val) => val.length > 0, 'Cannot be empty')

表单集成

• 通过 @hookform/resolvers/zod 将 Zod 与 react-hook-form 配合使用
• 定义与表单结构匹配的表单架构
• 在 UI 中妥善处理验证错误
• 对可选更新表单使用 .partial()

API 验证

• 在 API 路由中验证请求正文
• 验证查询参数和路径参数
• 返回结构化错误响应
• 对不同的响应类型使用可辨联合

错误处理

• 实施自定义错误消息，以改善用户体验
• 使用 .format() 输出结构化错误
• 创建自定义错误映射以支持 i18n
• 妥善处理嵌套对象错误

高级模式

可辨联合

const ResultSchema = z.discriminatedUnion('status', [
  z.object({ status: z.literal('success'), data: UserSchema }),
  z.object({ status: z.literal('error'), message: z.string() }),
])

递归架构

const CategorySchema: z.ZodType<Category> = z.lazy(() =>
  z.object({
    name: z.string(),
    children: z.array(CategorySchema),
  })
)

性能

• 预编译频繁使用的架构
• 避免在渲染函数中创建架构
• 有意使用 .passthrough() 或 .strict()
• 对大型对象考虑使用部分验证