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 を介して react-hook-form と Zod を使用します
• フォームの構造に合ったフォームスキーマを定義します
• UI で検証エラーを適切に処理します
• 更新フォームで入力項目を省略可能にするには .partial() を使用します

API の検証

• API ルートでリクエストボディを検証します
• クエリパラメーターとパスパラメーターを検証します
• 構造化されたエラーレスポンスを返します
• さまざまなレスポンスタイプには判別可能なユニオンを使用します

エラー処理

• UX の向上のためにカスタムエラーメッセージを実装します
• 構造化されたエラー出力には .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() は意図的に使用します
• 大きなオブジェクトには部分検証を検討します