Orval × Feature-Sliced Design で実現するルールベースなスキーマ駆動開発

openapi: 3.1.0
paths:
  /posts:
    get:
      summary: 投稿一覧を取得
      parameters:
        - name: page
          in: query
          schema:
            type: integer
      responses:
        "200":
          description: Success
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/GetPostsResponse"
    post:
      summary: 投稿を作成
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CreatePostRequest"
      responses:
        "201":
          description: Created
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/CreatePostResponse"
  /posts/{postId}:
    put:
      summary: 投稿を更新
      parameters:
        - name: postId
          in: path
          required: true
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/UpdatePostRequest"
      responses:
        "200":
          description: Success
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Post"
    delete:
      summary: 投稿を削除
      parameters:
        - name: postId
          in: path
          required: true
          schema:
            type: string
      responses:
        "204":
          description: No Content
components:
  schemas:
    Post:
      type: object
      required: [id, title, createdAt, updatedAt, status]
      properties:
        id:
          type: string
        title:
          type: string
        body:
          type: string
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
        status:
          type: string
          enum: [draft, published, archived]
    GetPostsResponse:
      type: object
      properties:
        items:
          type: array
          items:
            $ref: "#/components/schemas/Post"
        total:
          type: integer
        page:
          type: integer
    CreatePostRequest:
      type: object
      required: [title]
      properties:
        title:
          type: string
        body:
          type: string
    CreatePostResponse:
      allOf:
        - $ref: "#/components/schemas/Post"
        - type: object
          properties:
            createdBy:
              type: string
    UpdatePostRequest:
      type: object
      properties:
        title:
          type: string
        body:
          type: string
        status:
          type: string
          enum: [draft, published, archived]

// 手動で型定義を書く
type Post = {
  id: string;
  title: string;
  body?: string;
  createdAt: string;
  updatedAt: string;
  status: "draft" | "published" | "archived";
};

// API 呼び出しも手で書く
const getPost = async (id: string): Promise<Post> => {
  const response = await fetch(`/api/posts/${id}`);
  return response.json();
};

従来：実装 → ドキュメント（後付け） → 仕様との齟齬

スキーマ駆動：スキーマ定義 → 自動生成 → 実装 → 完了
              （実装 = ドキュメント、常に同期）

OpenAPI（信頼できる唯一の情報源）
    ↓
Orval によるコードの自動生成で、 型定義 + TanStack Query フックを常に同期
    ↓
低コストで型安全な開発が可能

src/
├── features/          ← レイヤー
│   ├── auth/          ← スライス
│   │   ├── ui/        ← セグメント
│   │   ├── model/     ← セグメント
│   │   └── index.ts

workspaces/typescript/src/
├── app/               ← ① アプリケーション層：ルーティング、グローバル設定
│   ├── layouts/         全体的なページで利用するレイアウト
│   ├── routes/          ルーティング定義
│   └── App.tsx          ルートとなるtsxファイル
│
├── pages/             ← ② ページ層：各ページコンポーネント（URLに対応）
│   ├── users/
│   └── login/
│
├── features/          ← ③ 機能層：再利用可能なビジネスロジック
│   ├── {slice}/           ドメインごとにスライスという単位で分割 (例:user, auth)
│   │   ├── {component}/   ドメインに属するコンポーネント
│   │   │   ├── model/       ロジック部分
│   │   │   ├── ui/          UI部分
│   │   │   └── index.ts     公開API（バレルファイル）
│   │   ...
│   ...
│
├── entities/          ← ④ エンティティ層：ビジネスドメインの定義
│   ├── user/            各種ドメイン
│   │   ├── @x             クロスインポート記法 ※後述
│   │   ├── api/           shared/ の自動生成ファイルを import して利用（ファサード）
│   │   │   ├── hooks.ts     apiフック
│   │   │   └── index.ts     公開API（バレルファイル）
│   │   ├── model/       ドメインロジック
│   │   ├── ui/          ドメイン内にとどまる最小レベルのUI
│   │   └── index.ts     公開API（バレルファイル）
│   ...
│
└── shared/            ← ⑤ 共有層：プロジェクト非依存のユーティリティ
    ├── api/
    │   └── generated/   Orval による自動生成ファイル（修正禁止）
    │       ├── types.ts
    │       ├── hooks.ts
    │       └── client.ts
    ├── config/          設定定数
    ├── errors/          共通利用エラー関数
    ├── lib/             ユーティリティ関数
    └── ui/              汎用UIコンポーネント

app ← 最上位（抽象度が高い）
  ↓ import可能
pages
  ↓
features
  ↓
entities

※ shared はどのレイヤーからもインポート可能

entities/
├── user/
│   ├── @x/
│   │   └── post.ts       # 外部スライス向けに公開する型・関数
│   ├── model/
│   │   └── types.ts      # 内部で使用する型定義
│   ├── ui/
│   └── index.ts          # 通常の公開API
│
└── post/
    ├── model/
    │   └── usePost.ts    # ここから user の型を参照したい
    └── index.ts

// entities/post/model/usePost.ts から entities/user を使用する場合

// ❌ 通常のインポート（Feature-Sliced Design違反：同一レイヤー間のインポート）
import type { User } from "@/entities/user";

// ✅ @x を使ったクロスインポート（許可）
import type { User } from "@/entities/user/@x/post";

// @x ディレクトリは「このスライスが外部に公開する、クロスインポート専用のAPI」を表します。

# Orval のインストール
pnpm add -D orval

// orval.config.ts
import { defineConfig } from "orval";

const API_DIR = "./src/shared/api";
const INPUT_DIR = "../../docs/api";
const GENERATED_DIR = `${API_DIR}/generated`;

export default defineConfig({
  postApi: {
    hooks: {
      afterAllFilesWrite: "pnpm format:write:generate",
    },
    input: {
      target: `${INPUT_DIR}/openapi.yaml`,
    },
    output: {
      clean: true,
      biome: true,
      client: "react-query",
      override: {
        mutator: {
          path: `${API_DIR}/customInstance.ts`,
          name: "useCustomInstance",
        },
        query: {
          useSuspenseQuery: true,
          version: 5,
        },
      },
      schemas: `${GENERATED_DIR}/model`,
      target: `${GENERATED_DIR}/hooks/index.ts`,
    },
  },
});

// src/shared/api/customInstance.ts

import { ApiHttpError, type ErrorDetail } from "../errors";
import { getAccessToken } from "../lib";

const BASE_URL = import.meta.env.VITE_API_BASE_URL || "";

// リクエスト設定の型定義
export type RequestConfig = {
  url: string;
  method: "GET" | "POST" | "PUT" | "DELETE" | "PATCH";
  headers?: Record<string, string>;
  params?: Record<string, unknown>;
  data?: unknown;
  signal?: AbortSignal;
};

// Fetch API を使用したリクエスト関数
const fetchApi = async <T>(config: RequestConfig): Promise<T> => {
  const { url, method, headers = {}, params, data, signal } = config;

  // 認証トークンを取得
  const token = getAccessToken();

  // クエリパラメータの構築
  const queryString = params
    ? `?${new URLSearchParams(params as Record<string, string>).toString()}`
    : "";
  const fullUrl = `${BASE_URL}${url}${queryString}`;

  // ヘッダーの構築
  const requestHeaders: Record<string, string> = {
    "Content-Type": "application/json",
    ...headers,
  };

  if (token) {
    requestHeaders.Authorization = `Bearer ${token}`;
  }

  // リクエストオプションの構築
  const options: RequestInit = {
    method,
    headers: requestHeaders,
    signal,
  };

  if (data && ["POST", "PUT", "PATCH"].includes(method)) {
    options.body = JSON.stringify(data);
  }

  const response = await fetch(fullUrl, options);

  // エラーハンドリング
  if (!response.ok) {
    let errorMessage = `API error: ${response.status}`;
    let errorDetails: ErrorDetail[] = [];

    try {
      const errorData = await response.json();
      errorDetails = errorData?.errors?.details ?? [];
      if (typeof errorData.message === "string") {
        errorMessage = errorData.message;
      }
    } catch {
      // JSONパースに失敗した場合はデフォルトメッセージを使用
    }

    throw new ApiHttpError({
      status: response.status,
      message: errorMessage,
      details: errorDetails,
    });
  }

  // 204 No Content の場合
  if (response.status === 204) {
    return null as T;
  }

  return response.json();
};

// Orval で使用するカスタムインスタンス関数
export const useCustomInstance = <T>(config: RequestConfig): Promise<T> => {
  const controller = new AbortController();

  const promise = fetchApi<T>({
    ...config,
    signal: controller.signal,
  });

  // TanStack Query のキャンセル機能用
  // @ts-expect-error cancel プロパティを動的に追加
  promise.cancel = () => controller.abort();

  return promise;
};

export default useCustomInstance;

# コード生成実行
pnpm orval

// src/shared/api/generated/types.ts
// ↓ OpenAPIから自動生成される

export type Post = {
  id: string;
  title: string;
  body?: string;
  createdAt: string; // ISO 8601形式
  updatedAt: string;
  status: "draft" | "published" | "archived";
};

export type GetPostsResponse = {
  items: Post[];
  total: number;
  page: number;
};

export type CreatePostRequest = {
  title: string;
  body?: string;
};

export type CreatePostResponse = Post & {
  createdBy: string;
};

export type UpdatePostRequest = {
  title?: string;
  body?: string;
  status?: "draft" | "published" | "archived";
};

// src/shared/api/generated/hooks.ts
// ↓ Orval が TanStack Query のフックを生成（簡略化した例）

import { useSuspenseQuery, useMutation } from "@tanstack/react-query";
import type {
  UseSuspenseQueryOptions,
  UseMutationOptions,
} from "@tanstack/react-query";
import type {
  Post,
  GetPostsResponse,
  CreatePostRequest,
  CreatePostResponse,
  UpdatePostRequest,
} from "./model";
import { useCustomInstance } from "../customInstance";

type SecondParameter<T extends (...args: never) => unknown> = Parameters<T>[1];

// GET リクエスト → useSuspenseQuery フック
export const useGetPosts = <
  TData = Awaited<ReturnType<ReturnType<typeof useCustomInstance<GetPostsResponse>>>>,
  TError = Error,
>(
  options?: {
    query?: Partial<UseSuspenseQueryOptions<GetPostsResponse, TError, TData>>;
    request?: SecondParameter<ReturnType<typeof useCustomInstance>>;
  }
) => {
  const customInstance = useCustomInstance<GetPostsResponse>();

  return useSuspenseQuery({
    queryKey: ["posts"],
    queryFn: () => customInstance({ url: `/api/posts`, method: "GET" }),
    ...options?.query,
  });
};

// POST リクエスト → useMutation フック
export const useCreatePost = <TError = Error, TContext = unknown>(
  options?: {
    mutation?: UseMutationOptions<CreatePostResponse, TError, CreatePostRequest, TContext>;
    request?: SecondParameter<ReturnType<typeof useCustomInstance>>;
  }
) => {
  const customInstance = useCustomInstance<CreatePostResponse>();

  return useMutation({
    mutationFn: (data: CreatePostRequest) =>
      customInstance({
        url: `/api/posts`,
        method: "POST",
        data,
      }),
    ...options?.mutation,
  });
};

// PUT リクエスト
export const useUpdatePost = <TError = Error, TContext = unknown>(
  postId: string,
  options?: {
    mutation?: UseMutationOptions<Post, TError, UpdatePostRequest, TContext>;
    request?: SecondParameter<ReturnType<typeof useCustomInstance>>;
  }
) => {
  const customInstance = useCustomInstance<Post>();

  return useMutation({
    mutationFn: (data: UpdatePostRequest) =>
      customInstance({
        url: `/api/posts/${postId}`,
        method: "PUT",
        data,
      }),
    ...options?.mutation,
  });
};

// DELETE リクエスト
export const useDeletePost = <TError = Error, TContext = unknown>(
  postId: string,
  options?: {
    mutation?: UseMutationOptions<void, TError, void, TContext>;
    request?: SecondParameter<ReturnType<typeof useCustomInstance>>;
  }
) => {
  const customInstance = useCustomInstance<void>();

  return useMutation({
    mutationFn: () =>
      customInstance({
        url: `/api/posts/${postId}`,
        method: "DELETE",
      }),
    ...options?.mutation,
  });
};

// ❌ こうやって直接修正してはいけない
// src/shared/api/generated/hooks.ts

export const useGetPosts = () => {
  // ↓ このコードは Orval の再実行で上書きされる
  return useSuspenseQuery({
    // ...
  });
};

// src/entities/post/api/hooks.ts

import { useGetPosts as useGetPostsGenerated } from "@/shared/api/generated";

/**
 * 利用側に使いやすいインターフェースを提供
 * - Orval 生成コードの詳細を隠蔽
 * - 戻り値を整理して返す
 */
export const usePosts = () => {
  const { data, isLoading, error } = useGetPostsGenerated();

  return {
    posts: data?.items ?? [],
    isLoading,
    hasError: !!error,
  };
};

// src/entities/post/api/hooks.ts

import { useGetPosts as useGetPostsGenerated } from "@/shared/api/generated";

/**
 * 投稿一覧を取得するカスタムフック
 * shared/api/generated への依存を entities層に隔離
 */
export const usePosts = () => {
  const { data, isLoading, error } = useGetPostsGenerated();

  return {
    posts: data?.items ?? [],
    isLoading,
    hasError: !!error,
  };
};

// src/entities/post/api/index.ts

export { usePosts } from "./hooks";

// src/features/PostManagement/ui/PostList.tsx

import { usePosts } from "@/entities/post/api";

function PostList() {
  const { posts, isLoading } = usePosts();

  if (isLoading) return <div>読み込み中...</div>;

  return (
    <ul>
      {posts.map((post) => (
        <li key={post.id}>{post.title}</li>
      ))}
    </ul>
  );
}

// src/entities/post/api/hooks.ts

import {
  useGetPosts as useGetPostsGenerated,
  useGetPostDetails as useGetPostDetailsGenerated,
} from "@/shared/api/generated";

/**
 * 複数のAPI呼び出しを組み合わせる
 * 呼び出し側はこの複雑性を意識しない
 */
export const usePostWithDetails = (postId: string) => {
  const { data: posts, isLoading: postsLoading } =
    useGetPostsGenerated();

  const { data: details, isLoading: detailsLoading } =
    useGetPostDetailsGenerated(postId);

  return {
    posts: posts?.items ?? [],
    details: details ?? null,
    isLoading: postsLoading || detailsLoading,
    // 便利な導出データも提供
    hasDetails: !!details,
  };
};

// src/features/PostManagement/ui/PostDetail.tsx

import { usePostWithDetails } from "@/entities/post/api";

function PostDetail({ postId }: Props) {
  const { posts, details, isLoading, hasDetails } = usePostWithDetails(postId);

  // 複雑さは entities層に隠蔽！
  return <div>{hasDetails && <PostInfo details={details} />}</div>;
}

// src/entities/post/api/hooks.ts

export type ApiError = {
  message: string;
  code: "NETWORK_ERROR" | "NOT_FOUND" | "UNAUTHORIZED" | "SERVER_ERROR";
  details?: unknown;
};

export type UsePostsResult = {
  posts: Post[];
  isLoading: boolean;
  error: ApiError | null;
  retry: () => void;
};

export const usePosts = (): UsePostsResult => {
  const { data, isLoading, error, refetch } = useGetPostsGenerated();

  // Orval生成のエラー型を独自のエラー型に変換
  const mappedError: ApiError | null = error
    ? {
        message: error.message || "エラーが発生しました",
        code: mapErrorCode(error),
        details: error,
      }
    : null;

  return {
    posts: data?.items ?? [],
    isLoading,
    error: mappedError,
    retry: () => refetch(),
  };
};

// ヘルパー関数
// TanStack Query の error は Error 型として扱われる
// カスタムインスタンス側でステータスコードを含めた Error を throw する想定
type ApiErrorWithStatus = Error & { status?: number };

function mapErrorCode(error: unknown): ApiError["code"] {
  if (!navigator.onLine) return "NETWORK_ERROR";

  const apiError = error as ApiErrorWithStatus;
  if (apiError.status === 404) return "NOT_FOUND";
  if (apiError.status === 401) return "UNAUTHORIZED";

  return "SERVER_ERROR";
}

// src/features/PostManagement/ui/PostList.tsx

import { usePosts } from "@/entities/post/api";

function PostList() {
  const { posts, isLoading, error, retry } = usePosts();

  if (error) {
    return (
      <div>
        <p>エラー: {error.message}</p>
        <button onClick={retry}>再試行</button>
      </div>
    );
  }

  // ... 以下、通常の処理
}

shared/api/generated/  ← Orvalの生成物（修正禁止）
  ├─ useGetPosts
  ├─ useCreatePost
  ├─ useGetPostDetails
  └─ types.ts
       ↓
    [境界線]
       ↓
entities/post/api/     ← Orvalの生成物をラッピングする層（修正可能）
  ├─ usePosts（カスタマイズ版）
  ├─ usePostWithDetails（複数API組み合わせ）
  ├─ ApiError型
  └─ index.ts（公開API）
       ↓
features/              ← 機能層
  ├─ PostManagement/
  │   ├─ ui/PostList.tsx
  │   ├─ ui/PostDetail.tsx
  │   ├─ lib/...
  │   └─ index.ts
  ...
       ↓
pages/                 ← ページ層
  └─ PostPage/
       ↓
app/                   ← アプリケーション層
  ├─ routes/
  └─ ...