validation-schema

Validation Schema Skill — Schema 校验

何时使用

• API 边界校验请求 body / query / params
• 解析外部数据（JSON file / 第三方 API 响应 / env vars）
• 表单提交校验
• 配置文件校验启动时崩溃
• 想从一份 schema 同时拿到运行时校验 + TS 类型 + OpenAPI 文档

一、为什么需要 Schema 库

// ❌ 仅 TS 类型
interface User { id: string; email: string; age: number }
const user: User = JSON.parse(rawJSON)
// 编译通过 — 但运行时 rawJSON 可能根本不是 User 形状
user.email.toLowerCase()    // 💥 cannot read of undefined

// ✅ 运行时校验 + 类型派生
import { z } from 'zod'
const User = z.object({
  id: z.string(),
  email: z.string().email(),
  age: z.number().int().min(0),
})
type User = z.infer<typeof User>          // 自动派生
const user = User.parse(rawJSON)           // 失败抛

核心诉求：边界处一次定义，类型 + 运行时校验 + 错误信息一起拿。

二、TS 生态主流库对比

库	大小	性能	特色
Zod	~12KB	中	业界标准，生态最大
Valibot	~1KB	高	模块化，tree-shakable，体积小 90%
ArkType	~30KB	极高	TS 字面量语法，类型推导极强
Yup	~50KB	中	老牌，Formik 集成好
Joi	~150KB	中	Node 后端老牌，类型推导弱
typia	编译时	极高	TS 转译时生成校验代码

Zod 示例

import { z } from 'zod'

const Order = z.object({
  id:        z.string().uuid(),
  userId:    z.string().min(1),
  items:     z.array(z.object({
    sku: z.string(),
    qty: z.number().int().positive(),
  })).min(1),
  total:     z.number().nonnegative(),
  createdAt: z.coerce.date(),         // 字符串 → Date
  status:    z.enum(['pending','paid','shipped']),
  metadata:  z.record(z.string()).optional(),
})

type Order = z.infer<typeof Order>

// 严格 parse（失败抛）
const order = Order.parse(rawData)

// 软 parse（不抛）
const result = Order.safeParse(rawData)
if (!result.success) {
  console.log(result.error.issues)    // 详细错误数组
}

Valibot 示例（pipe-friendly）

import * as v from 'valibot'

const Order = v.object({
  id: v.pipe(v.string(), v.uuid()),
  total: v.pipe(v.number(), v.minValue(0)),
})

const result = v.safeParse(Order, rawData)

体积优势：bundle 只含用到的 validator（tree-shaking）。

ArkType 示例（TS 字面量）