Orval で組む型安全 API 統合 ── mutator 分離・Zod 二段防御・MSW 二層モックの実践
はじめに こんにちは。and factory フロントエンドエンジニアの青木です。 現在関わっているプロジェクトのフロントエンドで採用している、OpenAPI を Single Source of Truth とした型安全 API 統合パターン を紹介します。 Orvalでやっていることを並べると次のとおりです。 バックエンドの make openapi で生成されたYAMLをフロント側にコピー 1コマンドで 型定義 / TanStack Query Hook / Zodスキーマ / MSWモック までを一括生成 公開APIと認証APIで operationId 単位に mutator を切り替え、誤用を生成時点で防ぐ Zodの 二段防御 (coerce × transform) で unknown をコンポーネント層に到達させない 前提: Single Source of Truth とは Single Source of Truth (SSoT) は、ある情報の 「正しい定義を置く場所を 1 箇所に固定する」 設計原則です。日本語では「信頼できる唯一の情報源」と訳されます。 例えばAPIの「リクエスト/レスポンスの形」をプロジェクトのあちこちに書いていると、以下の問題が起きます。 バックエンドが型を変えたのにフロントのTypeScript型が古いまま動いてしまう ドキュメントとコードがズレて、新規参画者がどちらを信じればよいか分からなくなる 同じ情報を複数箇所で手書きするため、変更時の修正漏れが必ず発生する これを防ぐため、「APIの形」を openapi.yaml という1つのファイルに集約 しています。フロントの型・Hook・Zod・MSWモックは、すべてそこから自動生成する運用です。 flowchart TD A["openapi.yaml<br/>（唯一の「真実」）"]:::source A --> B[TypeScript 型] A --> C[TanStack Query Hook] A --> D[Zod 検証スキーマ] A --> E[MSW モックハンドラ] classDef source fill:#0ea5e9,color:#fff,stroke:#0369a1,stroke-width:2px これが「OpenAPIをSingle Source of Truthにする」の意味です。openapi.yaml を更新して pnpm run generate:api を実行すれば、全派生物が機械的に再生成されます。手作業の同期は不要です。 ...
