参数校验设计

// src/index.ts
app.post('/api/users', async (c) => {
  const body = await c.req.json()
  const user = await db.user.create({
    data: {
      name: body.name,
      email: body.email,
      age: body.age,
    },
  })
  return c.json(user, 201)
})

// src/index.ts
// 中间件的顺序很重要
app.post(
  '/api/users',
  authMiddleware,      // 1. 先确认请求者身份
  rateLimiter,         // 2. 再检查频率限制
  zValidator('json', createUserSchema),  // 3. 校验数据合法性
  (c) => {
    // 4. 到这里，数据一定是合法的
    const data = c.req.valid('json')
    return c.json(createUser(data), 201)
  }
)

// src/schemas/article.ts
import { z } from 'zod'
 
export const createArticleSchema = z.object({
  // 存在性：字段必须出现
  title: z.string()
    .min(1, '标题不能为空')       // 非空
    .max(200, '标题不超过 200 字符'), // 范围
  // 格式：必须符合特定模式
  slug: z.string()
    .regex(/^[a-z0-9-]+$/, 'slug 只能包含小写字母、数字和连字符'),
  // 类型 + 范围
  wordCount: z.number()
    .int()
    .min(0)
    .max(1000000),
  // 枚举：只接受特定值
  status: z.enum(['draft', 'published', 'archived']),
  // 可选字段
  summary: z.string().max(500).optional(),
  // 数组
  tags: z.array(z.string().min(1)).max(10),
})

// src/schemas/event.ts
const eventSchema = z.object({
  startDate: z.string().datetime(),
  endDate: z.string().datetime(),
}).refine(
  (data) => new Date(data.endDate) > new Date(data.startDate),
  { message: '结束时间必须晚于开始时间', path: ['endDate'] }
)

// src/index.ts
// Zod 默认行为：safeParse 遇到错误后继续解析全部字段
// 但 zValidator 中间件在第一个目标校验失败时就拦截请求
app.post('/api/users', zValidator('json', schema), (c) => {
  // ...
})

// src/index.ts
app.post(
  '/api/users',
  zValidator('json', createUserSchema, (result, c) => {
    if (!result.success) {
      // flatten() 会把所有字段的错误整理成 { field: [messages] } 的结构
      return c.json(
        {
          code: 'VALIDATION_ERROR',
          errors: result.error.flatten().fieldErrors,
        },
        400
      )
    }
  }),
  (c) => {
    return c.json(c.req.valid('json'), 201)
  }
)

{
  "code": "VALIDATION_ERROR",
  "errors": {
    "name": ["String must contain at least 1 character(s)"],
    "email": ["Invalid email"],
    "age": ["Expected number, received string"]
  }
}

// src/index.ts
// 服务端校验不能因为「前端已经校验了」就省略或放宽
app.post('/api/users', zValidator('json', createUserSchema), (c) => {
  const data = c.req.valid('json')
  return c.json(createUser(data), 201)
})

// src/index.ts
// 只接受这三个值，其他全部拒绝
const statusSchema = z.enum(['draft', 'published', 'archived'])
 
// 只允许这些字段通过，多余的字段会被 strip
const createUserSchema = z.object({
  name: z.string(),
  email: z.string().email(),
})
// Zod 默认行为：strip 掉 schema 中没有定义的字段
// createUserSchema.parse({ name: 'Alice', email: '[email protected]', admin: true })
// → { name: 'Alice', email: '[email protected]' }（admin 字段被丢弃）

// src/index.ts
// 只排除了几个特定值，其他字符串都能通过
const nameSchema = z.string().refine(
  (val) => !['admin', 'root', 'system'].includes(val.toLowerCase()),
  { message: '不能使用保留名称' }
)

// src/index.ts
// 白名单方式：只允许合法字符
const usernameSchema = z.string().regex(/^[a-zA-Z0-9_]{3,20}$/)
// 不管攻击者传什么，不匹配这个模式就一律拒绝

// src/schemas/user.ts
const strictSchema = z.object({
  name: z.string(),
  email: z.string().email(),
}).strict() // 传入未声明字段时直接报错，而不是静默丢弃
 
// strictSchema.safeParse({ name: 'Alice', email: '[email protected]', extra: 1 })
// → { success: false, error: { issues: [{ message: 'Unrecognized key(s)...' }] } }

// src/index.ts
const querySchema = z.object({
  // 接收字符串 '2'，自动转成数字 2
  page: z.coerce.number().int().positive().default(1),
  limit: z.coerce.number().int().positive().max(100).default(20),
})
 
app.get('/posts', zValidator('query', querySchema), (c) => {
  const { page, limit } = c.req.valid('query')
  // page: number, limit: number
  return c.json({ page, limit })
})

// src/schemas/user.ts
const createUserSchema = z.object({
  // 转成小写，去掉首尾空格
  email: z.string().email().transform((val) => val.trim().toLowerCase()),
  // 去掉手机号中的空格和连字符
  phone: z.string().regex(/^[\d\s-]+$/).transform((val) => val.replace(/[\s-]/g, '')),
  // 统一日期格式
  birthday: z.string().transform((val) => new Date(val).toISOString().split('T')[0]),
})

// src/index.ts
// TypeScript 认为 body 的类型是 Request 的 JSON 解析结果
// 但运行时 body 里实际有什么字段、什么类型，TypeScript 管不了
app.post('/api/users', async (c) => {
  const body = await c.req.json()
  // body.name — TypeScript 不知道这里有没有 name，也不知道它是不是 string
  // body 的类型实际上是 any（或 unknown）
})

// src/index.ts
const createUserSchema = z.object({
  name: z.string(),
  email: z.string().email(),
})
 
type CreateUserInput = z.infer<typeof createUserSchema>
// { name: string; email: string }
 
app.post('/api/users', zValidator('json', createUserSchema), (c) => {
  const data = c.req.valid('json')
  // data 的类型是 CreateUserInput
  // 这里既有运行时的校验保证（数据确实符合 schema）
  // 也有编译期的类型信息（TypeScript 知道 data 有哪些字段）
  return c.json(data, 201)
})

// src/schemas/user-v2.ts
// v1 → v2：新增 phone 字段，但标记为 optional
const createUserSchemaV2 = z.object({
  name: z.string().min(1),
  email: z.string().email(),
  phone: z.string().optional(), // 旧客户端不传这个字段也不会报错
})

// src/routes/users-v1.ts
const createUserSchemaV1 = z.object({
  name: z.string(),
  email: z.string(), // 宽松校验
})
 
// src/routes/users-v2.ts
const createUserSchemaV2 = z.object({
  name: z.string().min(1).max(100),
  email: z.string().email(), // 严格校验
})
 
// 不同版本走不同的路由
app.post('/api/v1/users', zValidator('json', createUserSchemaV1), handler)
app.post('/api/v2/users', zValidator('json', createUserSchemaV2), handler)