blog.dopana

戻る

Reactアプリケーションを開発していると、必ず直面する共通の課題があります。「APIから一度データを取得したのに、別コンポーネントや画面遷移のたびに再度APIを呼ぶ必要があるのだろうか?」

例えば、GET /api/users/123 というエンドポイントを考えてみましょう。ヘッダーコンポーネントがアバター表示のためにユーザー情報を取得し、プロフィールカードも同じ情報を必要とし、アクティビティフィードも同じユーザー情報を参照します。

Header Component       ──→ GET /api/users/123
Profile Component      ──→ GET /api/users/123
ActivityFeed Component ──→ GET /api/users/123
text

従来の useEffect と useState を組み合わせたアプローチでは、各コンポーネントがマウントされるたびに重複したリクエストがネットワークへ送信されます。その結果、無駄な通信トラフィックが発生し、ローディングスピナーが何度もちらつき、サーバーに余計な負荷をかけることになります。

[!NOTE] TL;DR: @tanstack/react-query(旧称 React Query)は、単なる fetch() や axios のラッパーライブラリではありません。実態はクライアントサイドのサーバー状態キャッシュ(Server-State Cache)であり、同一リクエストの重複排除(deduplication)、バックグラウンド再検証、キャッシュライフサイクル管理(staleTime と gcTime)、そして楽観的UI更新(Optimistic Updates)を包括的に提供します。

1. 根本的な課題:自作キャッシュ(DIY Cache)の落とし穴#

重複リクエストを回避しようとして、多くの開発者が最初に思いつくのが Map によるインメモリキャッシュの自作です。

一見するとシンプルに見えますが、プロダクションの要件が複雑化するにつれて、自作キャッシュは深刻な設計課題に突き当たります。

  • キャッシュデータの有効期限はいつ切れるのか?(Stale管理)
  • バックグラウンドでの自動再取得はどう実装するのか?(ウィンドウ復帰時、ネットワーク再接続時)
  • ユーザーが名前を更新した際、画面上の全コンポーネントへどう通知するのか?(キャッシュの無効化・Invalidation)
  • 通信切断時のローディング、エラーハンドリング、再試行(Retry)はどう制御するのか?
  • 高速に画面を切り替えた際の競合(Race Condition)はどう防ぐのか?
  • ユーザーが長時間放置した場合、メモリリークを起こさずに解放できるか?(ガベージコレクション)
  • ページネーションや無限スクロール(Infinite Scroll)への対応は?

単純な Map から始まったコードは、結果として専用キャッシュライブラリの車輪の再発明へと向かいます。この課題を解決するために作られたのが TanStack Query です。

2. メンタルモデル(ELI5):サーバー状態 vs. クライアント状態#

TanStack Queryを正しく理解するための最重要概念は、フロントエンドの状態を2つに分類することです。

バックエンドインフラReact アプリケーションサーバー状態 (TanStack Query)クライアント状態 (Zustand / useState)フロントエンドが完全所有メモリ上にキャッシュされたスナップショットテーマ: dark / lightモーダル開閉: true / false選択中タブ: 2ユーザープロファイル情報注文履歴リストカート内商品データDatabase or REST Server

10歳の子どもにもわかる例え(ELI5)#

  • クライアント状態(Client State): 自分の勉強机の上にある自由帳のようなものです。何を描くか、どのページを開くか、どの色のペンを使うかは完全にあなたの自由であり、外部の誰かが勝手に書き換えることはありません。例:ドロワーの開閉、ダークモード設定、入力フォームの一時入力値。
  • サーバー状態(Server State): 公立図書館から借りてきた本のようなものです。あなたが手元に持っているのは一時的なスナップショットにすぎません。図書館側では著者が改訂版を発行したかもしれず、他の利用者が借りて内容が変わっているかもしれません。

[!WARNING] フロントエンドはサーバー状態の「所有者」ではありません。真実の単一ソース(Single Source of Truth)は常にリモートデータベースにあります。そのため、クライアントのメモリにあるデータは、取得した瞬間から古くなる(staleになる)可能性を常に孕んでいます。

APIデータをReduxやZustandなどのグローバルストアに無理に詰め込むべきでない理由はここにあります。Redux/Zustandは同期的なクライアント状態に最適化されており、TanStack Queryは非同期なサーバー状態のキャッシュ仲介役として設計されています。

3. TanStack Query キャッシュの動作原理#

基本的な実装例を見てみましょう。まず、Reactツリーを QueryClientProvider でラップします。

App.tsx
import { QueryClient, QueryClientProvider } from '@tanstack/react-query'
import { UserProfile } from './UserProfile'

const queryClient = new QueryClient()

export function App() {
  return (
    <QueryClientProvider client={queryClient}>
      <UserProfile userId={123} />
    </QueryClientProvider>
  )
}
tsx

コンポーネント内で useQuery を利用します。

queryKey はキャッシュのエントリ識別子#

TanStack Queryは、配列として指定された queryKey を決定論的にシリアライズし、キャッシュハッシュテーブルのキーとして管理します。

['user', 123]  ──→ キャッシュエントリ A: { id: 123, name: 'John' }
['user', 456]  ──→ キャッシュエントリ B: { id: 456, name: 'Alice' }
['posts', 123] ──→ キャッシュエントリ C: [ ... ]
text

全く異なるコンポーネント階層にある複数のコンポーネントが同時に ['user', 123] を指定して useQuery を呼んだ場合、TanStack Queryは同一キーを検知し、既存キャッシュを即座に再利用します。

4. リクエストの重複排除(Request Deduplication)#

ダッシュボード画面などで、同一ユーザーの情報を参照するコンポーネントが同時にマウントされるケースを考えます。

3つのコンポーネントが同時マウントリモートAPIサーバーリモートAPIサーバーTanStack Query キャッシュ層TanStack Query キャッシュ層useQueryuseQueryuseQueryネットワーク通信は1回のみJSONレスポンス各コンポーネントへ一括配信レンダリングレンダリングレンダリングヘッダーアバターサイドバープロファイルメインダッシュボードqueryKey: ['user', 123]重複排除エンジン (単一Promise)GET /api/users/123

重複排除機構がない場合、ブラウザは同一エンドポイントへ3本のHTTPリクエストを飛ばします。TanStack Queryは同一の queryKey を持つ進行中(in-flight)のリクエストを自動的に1本にまとめ、共有された1つのPromiseから全コンポーネントへデータを供給します。

5. staleTime vs. gcTime:最大の誤解を解き明かす#

TanStack Queryを利用する上で、最も混同されやすいのがこの2つの設定パラメータです。

設定項目旧名称本質的な役割デフォルト値
staleTimestaleTime取得したデータが「新鮮(fresh)」とみなされる期間(過ぎるとstaleになる)0 ms
gcTimecacheTimeどのコンポーネントにも使われなくなった(inactive)キャッシュがメモリ上に保持される期間5 * 60 * 1000(5分)
00秒: APIデータ取得完了 ──────→ データは「Fresh(新鮮)」
     │
     │  (staleTime期間内: 別コンポーネントがマウントされてもAPIは呼ばずキャッシュを即返却)
     ▼
60秒: staleTime満了 ─────────→ データは「Stale(古い)」へ遷移(キャッシュには残る!)
     │
     │  (ユーザーが画面遷移し、['users'] を参照するコンポーネントが全滅)
     ▼
70秒: クエリがInactive化 ────→ gcTimeのカウントダウン開始(5分)
     │
     ▼
370秒: gcTime満了 ───────────→ メモリ(RAM)から完全に消去(ガベージコレクション)
text

[!TIP] 黄金ルール: staleTime: 60000 は「60秒後にキャッシュが破棄される」という意味ではありません。「60秒経過したらデータが古くなったとみなす」という意味です。TanStack Queryは Stale-While-Revalidate の原則に従い、古いデータであっても即座にUIへ表示して画面の白飛びを防ぎつつ、裏で静かに最新データを取得して差し替えます。

マスターデータ向けの推奨設定#

国一覧やカテゴリマスタなど、更新頻度が極めて低いデータの場合:

queries/categories.ts
export const categoriesQueryOptions = {
  queryKey: ['categories'],
  queryFn: fetchCategories,
  staleTime: 10 * 60 * 1000, // 10分間は新鮮とみなす
  gcTime: 60 * 60 * 1000,    // 画面を離れても60分間はメモリに保持
}
typescript

6. トレードオフ:パフォーマンス vs. 新鮮さ#

クライアントサイドキャッシュには常にトレードオフが存在します。

パフォーマンス最大化(通信削減)   ◄───────────►   即時性重視(リアルタイム性)
        大きな staleTime                                    staleTime = 0
text

サーバー側でユーザー名が "John" から "Mike" に変更されたとしても、クライアントが staleTime: 10分 を設定していれば、有効期限が切れるか再検証が走るまで画面には "John" が表示され続けます。

TanStack Queryはユーザー体験を損なわずにデータを最新に保つため、自動バックグラウンド再取得トリガーを備えています。

  • refetchOnWindowFocus(デフォルト: true): ブラウザの別タブから戻ってきた際に、staleなクエリを自動更新。
  • refetchOnReconnect(デフォルト: true): ネットワーク復帰時に自動更新。
  • refetchOnMount(デフォルト: true): コンポーネント再マウント時、データがstaleであれば裏で再取得。

7. 更新処理とキャッシュ破棄(Mutation & Invalidation)#

データの新規作成・更新・削除(POST, PUT, DELETE)を行う場合は、useMutation と queryClient.invalidateQueries を連携させます。

POST api users200 SuccessinvalidateQueries1. ユーザーが作成ボタン押下2. useMutation3. サーバーDBへ永続化4. onSuccess コールバック5. users クエリをstale化6. 自動バックグラウンド再取得7. UIが最新状態に同期

標準的な実装例:

8. 最高のユーザー体験を作る:楽観的更新(Optimistic Updates)#

「いいね」ボタンやタスクの完了チェックなど、ユーザーの直感的な操作に対して300ms〜1秒のサーバー応答を待たせると、アプリが重く感じられます。

楽観的更新(Optimistic Update)では、サーバーへのリクエスト送信と同時に画面上のキャッシュを即時更新し、万が一APIエラーが発生した場合には元の状態へと自動ロールバックします。

9. TanStack Query と ブラウザHTTPキャッシュの棲み分け#

「ブラウザにはすでに Cache-Control や ETag によるHTTPキャッシュがあるのに、なぜTanStack Queryが必要なのか?」という疑問をよく耳にします。

両者は全く異なるアーキテクチャ層で動作しています。

3. インフラ層1. アプリケーション層 (React メモリ)2. ブラウザ層 (HTTP ネットワーク)2. ブラウザ層 (HTTP ネットワーク)useQueryCache Miss or RevalidateCache MissForward304 or 200 OKJSON データリアクティブに再レンダリングReact コンポーネントTanStack Query キャッシュfetch() / XMLHttpRequestブラウザ HTTP キャッシュ(ETag, max-age)CDN エッジキャッシュバックエンドサーバー / DB
比較軸TanStack Queryブラウザ HTTP キャッシュ
保存場所JavaScript ヒープメモリブラウザディスク / メモリ
コンポーネント認識Reactのライフサイクル(マウント、アンマウント)と連動URLとHTTPヘッダーのみを認識
UIへの反応性データ更新時に自動でReact再レンダリングをトリガーDOMレンダリングとは一切無関係
重複排除同時実行中のPromiseを複数コンポーネントで共有同時リクエスト時に重複送信される場合がある
楽観的更新 & ロールバックファーストクラスで完全対応非対応

両者は対立するものではなく、HTTPキャッシュがネットワーク転送量を削減し(304 Not Modified など)、TanStack Queryが滑らかでリアクティブな画面描画を担うという強力な補完関係にあります。

10. 実務で役立つ Query Key Factory パターン#

中規模以上のプロダクトで、['users', id, 'posts'] のような生の配列をコンポーネント各所にベタ書きすると、タイポや無効化漏れの原因になります。

Query Key Factory パターンを活用することで、キー定義を一元管理できます。

queries/userKeys.ts
export const userKeys = {
  all: ['users'] as const,
  lists: () => [...userKeys.all, 'list'] as const,
  list: (filters: { page: number; search?: string }) =>
    [...userKeys.lists(), filters] as const,
  details: () => [...userKeys.all, 'detail'] as const,
  detail: (id: number) => [...userKeys.details(), id] as const,
}
typescript

この階層構造により:

  • 全ユーザー関連キャッシュの一括破棄: queryClient.invalidateQueries({ queryKey: userKeys.all })
  • 一覧のみ破棄し、個別詳細は保持: queryClient.invalidateQueries({ queryKey: userKeys.lists() })
  • 特定ユーザーの購読: queryKey: userKeys.detail(userId)

安全かつ直感的にキャッシュをコントロールできます。

11. 導入すべきケースと不要なケース#

強く推奨されるケース:#

  • 管理画面(ダッシュボード、管理ポータル)、SaaS、CRM、Eコマースサイト。
  • 画面をまたいで同一エンティティを参照・更新するリッチなWebアプリ。
  • React + Vite や Next.js(Client Components)を中心としたSPA。

導入が不要なケース:#

  • お問い合わせフォームを1回送信するだけの静的ランディングページ。
  • Next.js App Router の React Server Components(RSC)中心で構築され、データフェッチとキャッシュがサーバー側で完結しているシステム。

12. まとめ#

TanStack Queryは単なるデータフェッチ用の便利ツールではなく、クライアントサイドでサーバー状態を調和させるための専用キャッシュエンジンです。

  1. クライアント状態(Zustand/useState)と サーバー状態(TanStack Query)の分離
  2. queryKey による一意のキャッシュ管理
  3. staleTime(鮮度)と gcTime(破棄タイマー)の適切な使い分け
  4. Mutation ➔ Invalidate ➔ Refetch の堅牢な更新フロー

これらを正しく理解して活用することで、不要なAPI通信を撲滅し、ユーザーにとっても開発者にとっても心地よいアプリケーションを構築できます。

参考文献#