alova-client-usage

Alova クライアントサイドでの使用方法

サーバーサイド（Node/Bun/Deno）については、alova-server スキルを参照してください。 alova openapi の使用方法については、alova-openapi スキルを参照してください。

このスキルの使い方

このスキルは、次の2つのレイヤーで構成されています。

1. このファイル — クイックリファレンスインデックスです。各 API の機能と使用するタイミングを確認できます。まずこちらをお読みください。
2. 公式ドキュメント（必要に応じて取得） — オプションの詳細、エッジケース、または使い慣れていない API については、各セクションに記載されている URL から最新かつ正確な情報を取得してください。

特定の API オプションや動作について質問に回答する前に、必ず公式ドキュメントを取得してください。alova は活発に開発されているため、最新のドキュメントのほうが学習データよりも信頼できます。

---

インストールとセットアップ

以下については、references/SETUP.md を参照してください。

• インストール
• Alova インスタンスの作成
• フレームワーク固有の StatesHook
• リクエストアダプター
• リクエストのグローバル共有とタイムアウト
• トークンベースのログイン、ログアウト、トークン更新に関するインターセプターの作成
• キャッシュロガー
• メソッドスナップショット数の上限設定

メソッドインスタンスの作成

alova は、合計7種類のリクエストタイプを提供します。

インスタンス作成関数	パラメーター
GET	alovaInstance.Get(url[, config])
POST	alovaInstance.Post(url[, data[, config]])
PUT	alovaInstance.Put(url[, data[, config]])
DELETE	alovaInstance.Delete(url[, data[, config]])
HEAD	alovaInstance.Head(url[, config])
OPTIONS	alovaInstance.Options(url[, config])
PATCH	alovaInstance.Patch(url[, data[, config]])

パラメーターの説明：

• url はリクエストパスです。
• data はリクエストボディのデータです。
• config はリクエスト設定オブジェクトです。リクエストヘッダー、params パラメーター、リクエスト動作のパラメーターなどの設定を含みます。

実際には、上記の関数を呼び出してもリクエストは送信されません。PromiseLike インスタンスであるメソッドインスタンスが作成されます。Promise オブジェクトと同様に、then、catch、finally メソッドまたは await を使用すると、リクエストが送信されます。

alovaInstance
  .Get('/api/user')
  .then((response) => {
    // ...
  })
  .catch((error) => {
    // ...
  })
  .finally(() => {
    // ...
  });

// or
try {
  await userMethodInstance;
} catch (error) {
  // ...
} finally {
  // ...
}

メソッドインスタンス API の全容については、メソッドのドキュメントを参照してください。

メソッドのメタデータ

特定のメソッドインスタンスに追加情報を設定すると、グローバルインターセプターでそのメソッドを識別しやすくなり、レスポンスの返却方法を変えたり、グローバルトーストを抑制したりできます。メソッドのメタデータを設定してください。詳しくは、メソッドのメタデータを参照してください。

コアフック

一般的なリクエストパターンを独自に実装する代わりに、コンポーネント内でこれらのフックを使用してください。

alova/client からインポートします。

フック	使用する場面	ドキュメント
useRequest	マウント時にデータを取得する場合、またはユーザーの操作（ボタンクリック、フォーム送信）で一度だけ実行する場合	ドキュメント
useWatcher	リアクティブな状態の変化（検索入力、フィルター、タブ、ページ）に応じて自動的に再取得する場合	ドキュメント
useFetcher	バックグラウンドでデータを目立たないように事前読み込みする場合、またはデータを所有するコンポーネントの外部から更新する場合	ドキュメント

ビジネス戦略フック

alova/client からインポートします。

シナリオ	フック	主な機能	ドキュメント
ページネーションリスト／無限スクロール	usePagination	ページの自動管理、次／前のページの先読み、楽観的な追加／削除／置換	ドキュメント
フォーム送信（複雑さを問わず）	useForm	下書きの永続化、複数ステップ間の状態共有、自動リセット	ドキュメント
ポーリング／フォーカス／再接続時の更新	useAutoRequest	トリガーの設定、スロットリング	ドキュメント
SMS、メール認証コードの送信とカウントダウン	useCaptcha	クールダウンタイマーを内蔵	ドキュメント
コンポーネント間でのリクエストのトリガー	actionDelegationMiddleware + accessAction	prop-drilling やグローバルストアが不要	ドキュメント
連鎖する依存リクエスト	useSerialRequest / useSerialWatcher	各ステップで前の結果を受け取る	ドキュメント
指数バックオフによる再試行	useRetriableRequest	試行回数とジッターを設定可能	ドキュメント
進捗状況を表示するファイルアップロード	useUploader	同時実行数の制限、進捗イベント	ドキュメント
Server-Sent Events	useSSE	リアクティブな data と readyState	ドキュメント
シームレスなデータインタラクション	useSQRequest	UI とのインタラクションに、待機せず即座に応答できます	ドキュメント

キャッシュ戦略

Alova には L1（メモリ）および L2（永続化／復元）レイヤーに加え、リクエストの自動共有（重複排除）があります。

キャッシュを全体およびスコープ単位で設定する

• ページ内ですばやくアクセスでき、更新するとリセットされます。ページの更新後も維持する／オフラインファーストにする、キャッシュを無効にする方法については、キャッシュモードを参照してください。
• ミューテーション後に自動で無効化するには、GET に hitSource、ミューテーション Method に name を指定します。詳しくは、キャッシュの自動無効化を参照してください。
• 手動で無効化する方法については、キャッシュの手動無効化を参照してください。
• キャッシュの設定と照会については、キャッシュの操作を参照してください。

重要なルール：hitSource による自動無効化を優先してください。命令型のコードが不要で、コンポーネントを疎結合にできます。

Hooks ミドルウェア

ミドルウェアを使うと、useHooks でリクエストの動作をインターセプトして制御できます。一般的な用途は次のとおりです。

• 特定の条件下でリクエストを無視する
• レスポンスデータを変換する
• リクエストメソッドを変更する、またはキャッシュを強制的にバイパスする
• エラーを処理する（カスタムエラーを捕捉またはスローする）
• レスポンスの遅延を制御する
• リアクティブな状態（loading、data など）を変更する
• リクエストの再試行ロジックを実装する
• loading 状態を完全に制御する

ミドルウェア API の全容と使用例については、リクエストミドルウェアを参照してください。

モックリクエスト

特定のリクエストにモックデータを設定します。モックリクエストを参照してください。

ベストプラクティス

• ドメイン、API、環境ごとに alova インスタンスを複数作成します。
• リクエスト関数を一元管理するフォルダーを用意し、コードを整理します。
• コンポーネント内ではフックを使い、それ以外の場所では Method インスタンスを直接呼び出すことを優先します。
• useRequest(method).onSuccess(...).onError(...) のように、チェーン形式でフックのイベントをバインドすることを優先します。

よくある落とし穴

落とし穴	対処方法
useWatcher の第 1 引数が Method インスタンスになっている	常に () => method(state.value) でラップします
updateState が何もせずに終了する	所有するコンポーネントのマウント中のみ動作します。それ以外では setCache を使います
v3 でキャッシュ操作が同期的に呼び出される	invalidateCache / setCache / queryCache を await します
useWatcher がマウント時にフェッチしない	immediate: true を設定します

TypeScript

Method インスタンスにレスポンスの型を注釈すると、フックが自動的にその型を推論します。

const getUser = (id: number) => alovaInstance.Get<User>(`/users/${id}`);
// or need to transform data.
const getUser = (id: number) =>
  alovaInstance.Get(`/users/${id}`, {
    transform(user: User) {
      return {
        ...user,
        name: user.lastName + ' ' + user.firstName,
      };
    },
  });

const { data } = useRequest(getUser(1)); // data: Ref<User>

📄 TypeScript ドキュメント

SSR コンポーネントパーティー

alova はサーバーとクライアントの両方で API を管理できるため、サーバー側とクライアント側でそれぞれ異なるリクエストソリューションを使う必要はありません。

CSR

通常、alova のフックはクライアント側でのみ動作します。

// won't send request in server side.
useRequest(getUser(1));

Nextjs

サーバーコンポーネントで Method インスタンスを直接 await します。

const App = async () => {
  const data = await alovaInstance.Get('/todo/list');
  // then ... code
  return <div>{...}</div>;
};
export default App;

Nuxt

alova のフックの前に await を付けると、両側の状態を同期できます。これは useFetch と同じ効果です。

const { data } = await useRequest(getUser(1));

Sveltekit

+page.server.[j|ts] で Method インスタンスを直接 await します。

/** @type {import('./$types').PageServerLoad} */
export async function load({ params }) {
  return {
    list: alovaInstance.Get('/todo/list'),
  };
}

カスタムアダプター

プリセットのアダプターがどれも要件に合わない場合は、独自のアダプターを作成してください。

• カスタムリクエストアダプター
• カスタムストレージアダプター
• カスタムクライアント戦略フック

カスタム Method キー

key を設定して、キャッシュ、リクエスト共有、状態更新の照合戦略を変更します。カスタム Method キーを参照してください。