ReactでOrval生成フックの使用方法メモ

Orvalで生成したフックは、
Query 系フック（GET）とMutation 系フック(POST/PUT/PATCH/DELETE)のフックに分かれて、それぞれ使用方法が異なる。

Orval生成フックの使用方法

1. Query 系フック（GET）

• React Hooks のルールにより、コンポーネント関数のトップレベルでしか呼び出せません。
• if 文や for 文、条件付きレンダリングの中では呼べません。
• つまり「コンポーネントの先頭部分で全て呼び出す」形になります。

2. Mutation 系フック（POST / PUT / PATCH / DELETE）

• これも同じく Hooks なのでトップレベルで呼び出す必要があります。
• ただし、Mutation 系は「実行（mutate / mutateAsync）」をどこで呼ぶかは自由です。
  • ボタンクリック時
  • フォーム送信時
  • 他のイベント内 など

Query 系フック

const { data, isLoading, isError, error, refetch } = 
  useGetProgressObjectivesTasksTaskId(
  taskId, // パスパラメータ
  {
    query: {
      enabled: true, 
      staleTime: 0,
      refetchOnWindowFocus: false 
    }, // React Query オプション
  });

返り値

• data: API レスポンスのデータ
• isLoading: ローディング状態（true / false）
• isError: エラー状態（true / false）
• error: エラー内容（AxiosError など）
• refetch: 再取得関数
• その他 React Query の戻り値（status, isFetching, dataUpdatedAt など）

名前の変更は{data:responseData}のような形で：で区切って変更する。
データは必要な物だけ記載する。

引数

• 第1引数: パスパラメータや必須の API パラメータ
• 第2引数: オプションオブジェクト
  params: クエリパラメータ（?page=1 など）
  query: React Query のオプション（enabled, staleTime, onSuccess など）

関数の引数は、そのまま呼び出し件数の引数を設定する。

Mutation 系

const { mutate, mutateAsync, isLoading, isError, error, data } = 
  usePostProgressObjectives({
    mutation: {
      onSuccess: () => console.log("成功"),
      onError: (err) => console.error(err),
   }
});

返り値

• mutate: 非同期呼び出し（Promise を返さない）
• mutateAsync: 非同期呼び出し（Promise を返す）
• isLoading / isError / error / data: Mutation 状態

名前の変更は{mutate:postProgressObjectives}のような形で：で区切って変更する。
データは必要な物だけ記載する。

引数

引数は基本的に mutation オプションのみ

• onSuccess
• onError
• onMutate　リクエスト送信前に呼ばれる
• onSettled など

1. mutate / mutateAsync 実行直後

• onMutate
  • リクエスト送信前に呼ばれる
  • 楽観的 UI 更新などに使う
  • 引数:
    • variables: mutate() に渡した引数
  • 戻り値を返すと、その値が context として onError や onSettled に渡される

---

2. API リクエスト成功時

• onSuccess
  • API が成功したときに呼ばれる
  • キャッシュ更新やトースト通知に使う
  • 引数:
    • data: API レスポンス
    • variables: mutate() に渡した引数
    • context: onMutate の戻り値

---

3. API リクエスト失敗時

• onError
  • API が失敗したときに呼ばれる
  • エラーメッセージ表示やロールバック処理に使う
  • 引数:
    • error: エラーオブジェクト（AxiosError など）
    • variables: mutate() に渡した引数
    • context: onMutate の戻り値

---

4. API 成否に関わらず最後に呼ばれる

• onSettled
  • 成功でも失敗でも最後に必ず呼ばれる
  • ローディング解除処理などに使う
  • 引数:
    • data: 成功時のレスポンス or undefined
    • error: 失敗時のエラー or null
    • variables: mutate() に渡した引数
    • context: onMutate の戻り値

---

呼び出し順序（成功時）

1. onMutate
2. API 実行
3. onSuccess
4. onSettled

呼び出し順序（失敗時）

1. onMutate
2. API 実行
3. onError
4. onSettled