name: zod-validation-patterns description: 本技能提供在TypeScript应用中使用Zod验证库的全面模式。它确保在整个代码库中正确、安全且一致地完成输入验证。
Zod验证模式技能
在以下情况使用此技能： 处理用户输入验证、API请求验证、表单数据验证或Quetrex中的数据转换时。
目的
本技能提供在TypeScript应用中使用Zod验证库的全面模式。它确保在整个代码库中正确、安全且一致地完成输入验证。
涵盖内容
-
模式模式 - 所有Zod模式类型的完整指南
- 基本类型（字符串、数字、布尔值、日期）
- 集合类型（数组、对象、映射、集合、记录）
- 高级类型（联合、交集、可区分联合）
- 可选/可为空模式
- 品牌类型和递归模式
-
错误处理 - 稳健的错误管理
- 自定义错误消息
- 国际化（i18n）
- UI显示的错误格式化
- 安全解析模式
- 错误恢复策略
-
精炼验证 - 自定义验证逻辑
- 基本和链式精炼
- 跨字段验证
- 条件验证
- 业务逻辑验证
- 文件上传验证
-
转换 - 数据转换和规范化
- 类型强制转换
- 数据清理和规范化
- 计算字段
- 预处理模式
-
异步验证 - 异步验证模式
- 数据库唯一性检查
- API验证
- 并发异步验证
- 错误处理和超时
-
类型推断 - TypeScript类型提取
- z.infer模式
- 输入与输出类型
- 泛型模式类型
- 可区分联合推断
-
API集成 - Next.js集成模式
- API路由验证
- 服务器操作验证
- 表单数据和文件上传
- 错误响应格式化
-
通用模式 - 可重用模式库
- 电子邮件、密码、电话验证
- URL、UUID、日期模式
- 地址、信用卡验证
- 用户名、slug、颜色模式
快速开始
基本用法
import { z } from 'zod'
// 定义模式
const userSchema = z.object({
email: z.string().email(),
age: z.number().int().positive(),
role: z.enum(['admin', 'user'])
})
// 解析数据（错误时抛出异常）
const user = userSchema.parse(data)
// 安全解析（返回结果对象）
const result = userSchema.safeParse(data)
if (result.success) {
console.log(result.data)
} else {
console.error(result.error)
}
类型推断
// 从模式中提取TypeScript类型
type User = z.infer<typeof userSchema>
// { email: string; age: number; role: 'admin' | 'user' }
API路由示例
// src/app/api/users/route.ts
import { NextRequest, NextResponse } from 'next/server'
import { z } from 'zod'
const createUserSchema = z.object({
email: z.string().email(),
password: z.string().min(8)
})
export async function POST(request: NextRequest) {
const body = await request.json()
const result = createUserSchema.safeParse(body)
if (!result.success) {
return NextResponse.json(
{ error: '验证失败', details: result.error.format() },
{ status: 400 }
)
}
// 处理已验证数据
const { email, password } = result.data
// ...
}
何时使用此技能
应该用于：
- API请求验证 - 所有传入API路由的数据
- 表单提交验证 - 客户端和服务器端
- 数据库输入验证 - 在插入/更新之前
- 配置验证 - 环境变量、配置文件
- 文件上传验证 - 大小、类型、内容验证
- 外部API响应 - 验证第三方数据
不应该用于：
- 简单类型检查 - 当不需要验证时使用TypeScript类型
- 运行时性能关键路径 - 验证有开销
- 已验证的数据 - 不要重新验证受信任的内部数据
最佳实践
- 在边界处验证 - API路由、服务器操作、外部数据源
- 使用安全解析 - 优先使用
safeParse()而不是parse()以获得更好的错误处理 - 提供清晰的错误消息 - 为用户界面验证自定义消息
- 重用通用模式 - 使用
common-schemas.md中的模式 - 类型推断 - 始终使用
z.infer<typeof schema>获取TypeScript类型 - 测试边界情况 - 为验证逻辑编写测试
- 记录复杂模式 - 为业务规则添加JSDoc注释
常见模式
1. 带默认值的可选字段
const configSchema = z.object({
timeout: z.number().int().positive().default(30),
retries: z.number().int().min(0).default(3),
debug: z.boolean().optional()
})
2. 条件必填字段
const addressSchema = z.object({
country: z.string(),
state: z.string().optional()
}).refine(
data => data.country === 'US' ? !!data.state : true,
{ message: '美国地址需要填写州', path: ['state'] }
)
3. 转换和验证
const emailSchema = z.string()
.trim()
.toLowerCase()
.email()
4. 可区分联合
const eventSchema = z.discriminatedUnion('type', [
z.object({ type: z.literal('click'), x: z.number(), y: z.number() }),
z.object({ type: z.literal('keypress'), key: z.string() })
])
5. 异步数据库检查
const usernameSchema = z.string()
.min(3)
.max(20)
.regex(/^[a-zA-Z0-9_-]+$/)
.refine(async (username) => {
const existing = await db.user.findUnique({ where: { username } })
return !existing
}, { message: '用户名已被占用' })
与Quetrex集成
TypeScript严格模式合规性
所有模式必须与TypeScript严格模式配合使用：
- 无
any类型 - 无
@ts-ignore注释 - 使用
z.infer进行显式类型推断
测试要求
验证逻辑需要全面的测试：
- 正常路径 - 有效数据通过
- 边界情况 - 边界值、空字符串、null/undefined
- 错误情况 - 无效数据产生预期错误
- 自定义验证 - 所有精炼和转换都经过测试
服务器操作模式
'use server'
import { z } from 'zod'
const createProjectSchema = z.object({
name: z.string().min(1).max(100),
description: z.string().optional()
})
export async function createProject(formData: FormData) {
const result = createProjectSchema.safeParse({
name: formData.get('name'),
description: formData.get('description')
})
if (!result.success) {
return { error: result.error.format() }
}
// 处理已验证数据
return { success: true, data: result.data }
}
资源
- Zod文档: https://zod.dev/
- TypeScript手册: https://www.typescriptlang.org/docs/handbook/
- Next.js服务器操作: https://nextjs.org/docs/app/building-your-application/data-fetching/server-actions-and-mutations
导航
从以下开始：
然后探索：
最后更新：2025-11-23 | Zod v4.1.12