データ取得とTanStack Query — 取得コードが200行になる

データ取得とTanStack Query。データベースとキャッシュの引き出し、ブラウザと更新マーク。

前の深掘り(useEffectの回)の最後に、私はこう書きました。「データ取得に useEffect を使わない」。

前回: 条件分岐の書き方 — 三項演算子が5段ネストした

これは深掘りです。本線の順路ではありません。 本線のAPIを作った回で「JSONを返すHTTP」を用意し、Reactの画面の回で「動くと使えるの差は4つの状態」までやった人が、その画面を実際に何枚も書き始めて、取得のコードが増え続けていることに気づいたときに読む記事です。飛ばしても本線は進みます。

この記事のコマンドは、すべて VM(Ubuntu Server)の中で打ちます。 Windows の PowerShell ではありません。 画面の確認は、ホストの Windows のブラウザで行います。 本線で作った ~/react-demo/ と ~/server/ には触りません。 この記事では、まっさらな ~/reactlab/ を新しく作り、ポート 5182番で動かします。APIも、本線の ~/server/ は使わず、練習用に小さいものを新しく立てます。

そう書いた時点では、まだ何も入れていませんでした。 「使わない」と言いながら、実際のコードは useEffect のままでした。

そのまま画面を増やしました。一覧、詳細、検索、登録後の再表示。4画面目を書き終えて、ファイルを開いたときに気づきました。

bash
$ wc -l src/BooksEffect.jsx
203 src/BooksEffect.jsx

203行。 そのうち、画面(JSXの見た目)は40行もありませんでした。 残りは全部、「取得の世話」でした。

何を書いていたのか、正確に思い出すとこうです。

  • isLoading を立てて、倒す
  • error を持って、次の取得のときに消し忘れる
  • データが0件のときと、まだ来ていないときを、別の表示にする
  • 競合状態を避けるための ignore フラグを、取得のたびに書く
  • 「登録したあとに一覧を出し直す」ための reload 関数と、それを呼ぶ場所
  • 同じ一覧を2箇所で使いたくなって、片方に props で流すか、両方で取るかで悩む
  • タブを切り替えて戻ったときに古いままでいいのか、毎回考える

これは「Reactが下手」なのではありません。 useEffect は、そもそも通信のための道具ではないので、通信に必要なものを1つも持っていないだけです。 足りないぶんを、毎回、手で埋めていたのがこの203行です。

この記事では、まず「自分で書くと何が必要になるか」を数えます。 数えてから、TanStack Query を実際に入れて、同じ画面を書き直します。

対象レベル: 中級〜上級 / 区分: 発展

目次

この記事でわかること

  • データ取得に必要な仕事は、少なくとも10個あること。useEffect + fetch は、そのうち1個(通信する)しかやってくれない
  • 「読み込み中 / エラー / 空 / 正常」の4状態は、ライブラリを入れても消えないこと。消えるのは「4つを自分で組み立てる手間」だけ
  • 同じデータを2つの部品が欲しがると、素の fetch では2回通信すること。それを1回にまとめるのが、キャッシュの一番わかりやすい効果
  • TanStack Query の useQuery が返すのは、isPending / isError / data の3つでほぼ足りること
  • 既定では「画面に戻ると勝手に取り直す」こと。それが嬉しい場合と、うるさい場合がある
  • staleTime と gcTime は別物であること。「古いとみなすまで」と「メモリから消すまで」で、混ぜると設定を間違える
  • queryKey に引数を入れ忘れると、古いデータが出たまま更新されないこと。これがこのライブラリで一番多い事故
  • 登録・更新は useMutation で書き、終わったら invalidateQueries で一覧に「古くなった」と伝えること
  • エラーは既定で3回リトライされること。そのせいで「エラー表示が出るまでが遅い」ことがあり、retry: false にすべき場面がある
  • 取得が1〜2箇所しかないなら、入れないほうがいいこと。そして、フレームワーク側で取るならそもそも要らない場合がある

この記事でやること

  1. ~/reactlab/ を新しく作り、ポート 5182番で起動する
  2. 練習用の小さなAPIを、Node.js 組み込みの http だけで立てる(わざと遅く、わざと失敗させられるもの)
  3. useEffect + fetch で一覧+検索を書き、行数を数える
  4. 足りないものを10項目の表にして、「全部自分で書くのか」を確かめる
  5. TanStack Query を入れて同じ画面を書き直し、wc -l で before / after を比べる
  6. queryKey をわざと間違えて、古いデータが出るところを目で見る
  7. useMutation で登録し、一覧が自動で更新されるところまで作る

先に知る言葉

この記事で初めて出てくる言葉です。 基本的な言葉は用語集にもまとめてあります。

言葉意味
サーバー状態(server state)本当の持ち主が自分ではないデータ。サーバーにある本体を、手元に一時的に写して表示しているだけのもの
クライアント状態(client state)自分が持ち主のデータ。開いているタブ、入力途中の文字など。useState が扱ってきたのはこちら
キャッシュ(cache)一度取ったものを、次に備えて手元に置いておくこと。またはその置き場所
stale(ステイル)「古くなった」という印。消えたのではなく、「次に見られたら取り直したほうがいい」という状態
fresh(フレッシュ)stale の反対。まだ新しいので、取り直さなくてよい状態
ガベージコレクション(GC)もう誰も見ていないものを、メモリから片づけること
queryKey(クエリキー)そのデータに付ける名前。この名前が同じなら「同じデータ」として扱われる
無効化(invalidate)「これはもう古い」と印を付けること。消すのではなく、古いと印を付けるだけ
mutation(ミューテーション)データを変える通信。登録・更新・削除。取得(query)と対になる言葉
リトライ(retry)失敗したときに、もう一度やり直すこと

1つだけ、先に頭に入れてください。 useState が扱ってきたのは「自分が持ち主のデータ」でした。サーバーから取ってきたデータは、持ち主が自分ではありません。 持ち主が別にいるものを useState に入れると、「向こうで変わったらどうするのか」を全部自分で面倒みることになります。 この記事の10項目は、全部そこから出てきます。


① 準備 — reactlab と、練習用のAPI

本線で作った ~/react-demo/ と ~/server/ は、そのまま残します。 この記事はわざと失敗させるAPIを使うので、別のプロジェクトでやります。

VM の中で打ちます。

bash
$ cd ~
$ npm create vite@latest reactlab -- --template react

「このまま依存を入れて起動しますか」と聞かれたら No(n)を選んでください。ポートを自分で決めたいからです。

bash
$ cd ~/reactlab
$ npm install
$ ls
eslint.config.js  index.html  package.json  public  README.md  src  vite.config.js

この一覧が出れば成功です。 npm install は初回だけ数分かかります(npmの回)。

ポートを2つ開ける

この記事では、ポートを2つ使います。

ポート何が使うか
5182Vite の開発サーバー(画面)
4182練習用API

APIのポートも開ける必要があります。 ブラウザがAPIを直接叩くからです。「VMの中にあるんだから届くだろう」は間違いで、叩いているのはホストのWindowsで動いているブラウザです(ネットワークの回)。

bash
$ sudo ufw allow 5182/tcp
$ sudo ufw allow 4182/tcp
$ sudo ufw status
Status: active

To                         Action      From
--                         ------      ----
22/tcp                     ALLOW       Anywhere
4182/tcp                   ALLOW       Anywhere
5182/tcp                   ALLOW       Anywhere

この2行が出れば準備完了です。

練習用のAPIを書く

本線の ~/server/ は使いません。 理由は2つです。

  1. わざと遅くして、わざと失敗させたい。 本線のAPIにその細工を入れると、あとで戻し忘れます
  2. この記事だけで完結させたい。 本線のAPIを立て直さないと読めない記事にはしません

中身は、本線のAPIの回でやったものと同じです。 Express も使いません。Node.js に最初から入っている http だけで足ります。

bash
$ mkdir -p ~/reactlab/api

VS Code から VM を開いて(VS Code Remote の回)、~/reactlab/api/server.js を作ります。

import http from 'node:http'

const PORT = 4182

let books = [
  { id: 1, title: 'はじめてのLinux', author: '佐藤' },
  { id: 2, title: 'Linuxのネットワーク', author: '鈴木' },
  { id: 3, title: 'React入門', author: '田中' },
]
let nextId = 4

const sleep = (ms) => new Promise((r) => setTimeout(r, ms))

const readBody = (req) =>
  new Promise((resolve) => {
    let body = ''
    req.on('data', (chunk) => {
      body += chunk
    })
    req.on('end', () => resolve(body))
  })

const json = (res, status, data) => {
  res.writeHead(status, { 'Content-Type': 'application/json; charset=utf-8' })
  res.end(JSON.stringify(data))
}

const server = http.createServer(async (req, res) => {
  const url = new URL(req.url, `http://${req.headers.host}`)

  res.setHeader('Access-Control-Allow-Origin', '*')
  res.setHeader('Access-Control-Allow-Headers', 'Content-Type')
  res.setHeader('Access-Control-Allow-Methods', 'GET, POST, OPTIONS')
  if (req.method === 'OPTIONS') {
    res.writeHead(204)
    res.end()
    return
  }

  const body = req.method === 'POST' ? await readBody(req) : ''
  const q = url.searchParams.get('q') ?? ''

  // わざと遅くする。短い言葉ほど遅く返す(競合状態を再現するため)
  const delay = url.searchParams.has('delay')
    ? Number(url.searchParams.get('delay'))
    : Math.max(1500 - q.length * 300, 200)
  await sleep(delay)

  console.log(`${req.method} ${url.pathname}${url.search} (${delay}ms)`)

  // わざと失敗させる
  if (url.searchParams.get('fail') === '1') {
    json(res, 500, { message: 'わざと失敗させました' })
    return
  }

  if (req.method === 'GET' && url.pathname === '/api/books') {
    json(res, 200, books.filter((b) => b.title.includes(q)))
    return
  }

  if (req.method === 'POST' && url.pathname === '/api/books') {
    const input = JSON.parse(body || '{}')
    if (!input.title) {
      json(res, 400, { message: 'title は必須です' })
      return
    }
    const book = { id: nextId++, title: input.title, author: input.author || '不明' }
    books.push(book)
    json(res, 201, book)
    return
  }

  json(res, 404, { message: 'not found' })
})

server.listen(PORT, '0.0.0.0', () => {
  console.log(`practice API listening on ${PORT}`)
})

3か所だけ説明します。

場所何のためか
Access-Control-Allow-Origin の3行これが無いとブラウザが結果を捨てます。 画面は 5182番、APIは 4182番で、番号が違えば別のサイト扱い(本線のAPIの回でやったCORS)
Math.max(1500 - q.length * 300, 200)短い言葉ほど遅く返します。 開発機は速すぎて競合状態が再現しないので、細工を入れます
fail=1?fail=1 を付けると 500 を返します。 エラー側の道を、いつでも通せるようにするため

import で書いています。 Vite の React テンプレートの package.json には "type": "module" が入っているので、この api/server.js も ESM として動きます。 require で書くとエラーになります。

APIを起動して、curl で確かめる

画面より先に、APIだけで確かめます。 ブラウザから叩いて動かないとき、原因がAPIなのか画面なのか分からなくなるからです。

ターミナルをもう1枚開いて、そちらで起動します。

bash
$ cd ~/reactlab
$ node api/server.js
practice API listening on 4182

別のターミナル(VMの中)から叩きます。

bash
$ curl -s "http://localhost:4182/api/books" | head -c 200
[{"id":1,"title":"はじめてのLinux","author":"佐藤"},{"id":2,"title":"Linuxのネットワーク","author":"鈴木"},{"id":3,"title":"React入門","author":"田中"}]

確認: JSONが返れば成功です。返るまで1.5秒くらい待たされるのも、わざとです。

わざと失敗させるほうも確かめます。

bash
$ curl -s -o /dev/null -w "%{http_code}\n" "http://localhost:4182/api/books?fail=1"
500

確認: 500 が出れば、エラーの道が通せます。

[スクリーンショット: 01_練習API起動.png] VM のターミナルで node api/server.js が動いていて、curl を打つたびに GET /api/books ... のログが増えていくところを撮ってください。

画面を起動する

さらにターミナルをもう1枚開いて、そちらで Vite を起動します(APIは動かしたまま)。

bash
$ cd ~/reactlab
$ npm run dev -- --host 0.0.0.0 --port 5182

ホストの Windows のブラウザで http://192.168.226.50:5182/ を開きます(IPは自分の値に。分からなければ VM の中で ip a)。Vite のロゴとカウンターが出れば成功です。

[スクリーンショット: 02_reactlab起動5182.png] ホストのブラウザで :5182 を開き、Vite + React の初期画面が出ているところを撮ってください。アドレスバーのポート番号が 5182 になっているのが見える形で。

この記事は、Network タブを見る時間が長くなります。 ブラウザで F12 を押して、Network タブを出したままにしてください(開発者ツールの回)。


② 自分で書くと、何が必要になるか数える

先にライブラリを入れません。 入れてから「これが便利です」と言われても、何が便利なのか分からないからです。

まず、素の useEffect + fetch で、検索付きの一覧を書きます。

素直に書いてみる

src/BooksEffect.jsx を作ります。API のIPは、自分のVMの値に直してください。

import { useEffect, useState } from 'react'

const API = 'http://192.168.226.50:4182'

export default function BooksEffect() {
  const [q, setQ] = useState('')
  const [books, setBooks] = useState([])
  const [isLoading, setIsLoading] = useState(true)
  const [error, setError] = useState(null)

  useEffect(() => {
    let ignore = false
    setIsLoading(true)
    setError(null)

    fetch(`${API}/api/books?q=${encodeURIComponent(q)}`)
      .then((res) => {
        if (!res.ok) throw new Error(`HTTP ${res.status}`)
        return res.json()
      })
      .then((data) => {
        if (ignore) return
        setBooks(data)
        setIsLoading(false)
      })
      .catch((err) => {
        if (ignore) return
        setError(err)
        setIsLoading(false)
      })

    return () => {
      ignore = true
    }
  }, [q])

  return (
    <div>
      <h2>useEffect版</h2>
      <input value={q} onChange={(e) => setQ(e.target.value)} placeholder="タイトルで検索" />
      {isLoading && <p>読み込み中...</p>}
      {error && <p style={{ color: 'crimson' }}>失敗しました: {error.message}</p>}
      {!isLoading && !error && books.length === 0 && <p>1件もありません</p>}
      {!isLoading && !error && books.length > 0 && (
        <ul>
          {books.map((b) => (
            <li key={b.id}>
              {b.title} / {b.author}
            </li>
          ))}
        </ul>
      )}
    </div>
  )
}

src/App.jsx を、まるごとこれに置き換えます。

import BooksEffect from './BooksEffect'

export default function App() {
  return (
    <div style={{ padding: 24, fontFamily: 'sans-serif' }}>
      <BooksEffect />
    </div>
  )
}

ブラウザで確認します。 1.5秒ほど「読み込み中…」が出てから、3件の一覧が出れば成功です。検索欄に Linux と打つと2件に絞られます。

確認: 検索欄に zzz と打つと「1件もありません」が出ます。「読み込み中」と「0件」が、ちゃんと別の表示になっていることを見てください。

この時点で、すでに Reactの画面の回でやった「読み込み中 / エラー / 空 / 正常」の4状態を全部書いています。 そして、isLoading と error という、矛盾しうる state を2つ持っています(useStateの深掘り回で「読み込み中なのにエラーもある」とやったやつです)。

ignore フラグは、useEffectの深掘り回でやった競合状態への対処です。外すと、速く打ったときに古い結果が新しい結果を上書きします。 気になる人は消して試してください。「Li」と速く打つと、Li の結果より L の結果が後から来て勝ちます。

行数を数える

bash
$ cd ~/reactlab
$ wc -l src/BooksEffect.jsx
52 src/BooksEffect.jsx

52行。 「一覧を出して、検索できる」だけで52行です。そのうち JSX(見た目)は15行です。

ここからが本題 — まだ足りていないものを数える

この52行は「動きます」。 ですが、実務で必要になるものの、半分も入っていません。

足りないものを並べます。

#必要な仕事上の52行では自分で書くと
1通信する✅ 入っているfetch 1行
2読み込み中を出す✅ 入っているstate 1つ+出し入れ
3エラーを出す✅ 入っているstate 1つ+次の取得で消す処理
4空(0件)と区別する✅ 入っている条件分岐。「まだ来ていない」と「0件」を混同しがち
5競合状態を防ぐ✅ 入っている取得のたびに ignore。書き忘れても動いてしまう
6キャッシュ❌ 無い「一度取ったもの」を置く場所を自作する
7同じデータを2箇所で使う❌ 無いそのままだと2回通信する。 親に持ち上げるか、Contextを引く
8画面に戻ったときの更新❌ 無いvisibilitychange を購読して、自分で取り直す
9登録したあとの再取得❌ 無いreload() を作って、登録側から呼ぶ
10失敗したときのリトライ❌ 無い回数を数えて、待ち時間を伸ばして、やり直す

6〜10は、1つも入っていません。 そして、この5つは「あったほうがいい」ではなく、画面が増えると必ず要求されるものです。

7番だけ、実際に見てみます。 口で言われても実感しないので、目で見ます。

src/App.jsx で、同じ部品を2つ置くだけです。

import BooksEffect from './BooksEffect'

export default function App() {
  return (
    <div style={{ padding: 24, fontFamily: 'sans-serif' }}>
      <BooksEffect />
      <BooksEffect />
    </div>
  )
}

ブラウザの Network タブを見ながら再読み込みします。

GET  api/books?q=   200   1.5 s
GET  api/books?q=   200   1.5 s

同じURLを、2回叩いています。 APIのターミナルにも、ログが2行増えているはずです。

[スクリーンショット: 03_同じ通信が2回.png] Network タブに api/books?q= の行が2行並んでいるところを撮ってください。「同じデータなのに2回」が見える形で。

これが実務でどう出るか。 ヘッダーに「未読3件」、サイドバーにも「未読3件」を出したい。部品は別々なので、それぞれが取りに行きます。 画面に5箇所あれば、5回叩きます。

逃げ道は2つありました。

  1. 親まで持ち上げて、props で配る → 深い部品に届けるために、通らない階層まで props を通す羽目になる
  2. Context に入れる → 状態管理の回でやった手。ただし、キャッシュも再取得もリトライも自分で書くことに変わりはない

ここで問うべきは「どう書くか」ではありません。 「6〜10を、画面のたびに、全部自分で書くのか」です。 私は書きませんでした。 書いたつもりで、抜けたまま出しました。 203行のうちの何割かは、抜けを見つけて後から足した跡です。

そして重要なのは、1〜5も消えないということです。 ライブラリは「4つの状態」を無くしません。 無くすのは、4つを自分で組み立てて、矛盾しないように守る手間です。


③ TanStack Query を入れて、同じものを書き直す

やっと入れます。

入れる

Vite を止めなくても入りますが、止めたほうが安全です。 Vite のターミナルで Ctrl+C を押してから、

bash
$ cd ~/reactlab
$ npm install @tanstack/react-query
added 3 packages, and audited 194 packages in 4s

確認: 入ったことを見ます。

bash
$ npm ls @tanstack/react-query
reactlab@0.0.0 /home/ubuntu/reactlab
└── @tanstack/react-query@5.62.7

5. で始まっていることを確認してください。 この記事は v5 の書き方です。 v4 以前は名前が違うものがあり(後述)、ネットの古い記事をそのまま写すと動きません。

開発中だけ使う道具も入れます。キャッシュは目に見えないので、これが無いと確かめようがありません。

bash
$ npm install -D @tanstack/react-query-devtools

土台を1つ置く

このライブラリは、useQuery を書く前に「キャッシュの置き場所」をアプリ全体に配る必要があります。 これをやらないと No QueryClient set というエラーで止まります。

src/main.jsx を、まるごとこれに置き換えます。

import { StrictMode } from 'react'
import { createRoot } from 'react-dom/client'
import { QueryClient, QueryClientProvider } from '@tanstack/react-query'
import { ReactQueryDevtools } from '@tanstack/react-query-devtools'
import App from './App.jsx'
import './index.css'

const queryClient = new QueryClient()

createRoot(document.getElementById('root')).render(
  <StrictMode>
    <QueryClientProvider client={queryClient}>
      <App />
      <ReactQueryDevtools initialIsOpen={false} />
    </QueryClientProvider>
  </StrictMode>,
)

足したのは4行だけです。

行何をしているか
new QueryClient()キャッシュの実体。 ここに取ったデータが溜まる
<QueryClientProvider>そのキャッシュを、下にある全部の部品から使えるようにする(状態管理の回でやった Context の仕組みそのもの)
<ReactQueryDevtools>開発中だけ出る、キャッシュの中身を見る窓

new QueryClient() を、コンポーネントの中で書かないでください。 描画のたびに新しいキャッシュができて、キャッシュが一切効かなくなります。 ファイルの一番外側で1回だけ作ります。

書き直す

src/BooksQuery.jsx を作ります。

import { useState } from 'react'
import { useQuery } from '@tanstack/react-query'

const API = 'http://192.168.226.50:4182'

async function fetchBooks(q) {
  const res = await fetch(`${API}/api/books?q=${encodeURIComponent(q)}`)
  if (!res.ok) throw new Error(`HTTP ${res.status}`)
  return res.json()
}

export default function BooksQuery() {
  const [q, setQ] = useState('')

  const { data, isPending, isError, error } = useQuery({
    queryKey: ['books', q],
    queryFn: () => fetchBooks(q),
  })

  return (
    <div>
      <h2>Query版</h2>
      <input value={q} onChange={(e) => setQ(e.target.value)} placeholder="タイトルで検索" />
      {isPending && <p>読み込み中...</p>}
      {isError && <p style={{ color: 'crimson' }}>失敗しました: {error.message}</p>}
      {!isPending && !isError && data.length === 0 && <p>1件もありません</p>}
      {!isPending && !isError && data.length > 0 && (
        <ul>
          {data.map((b) => (
            <li key={b.id}>
              {b.title} / {b.author}
            </li>
          ))}
        </ul>
      )}
    </div>
  )
}

src/App.jsx を、2つ並べる形にします。比べたいからです。

import BooksQuery from './BooksQuery'

export default function App() {
  return (
    <div style={{ padding: 24, fontFamily: 'sans-serif' }}>
      <BooksQuery />
      <BooksQuery />
    </div>
  )
}

起動し直します。

bash
$ npm run dev -- --host 0.0.0.0 --port 5182

Network タブを見ながら再読み込みします。

GET  api/books?q=   200   1.5 s

1回しか叩いていません。 同じ queryKey を欲しがった2つの部品に、1回の結果を配っています。 ②の7番が、書かずに解決しました。

[スクリーンショット: 04_通信が1回になる.png] <BooksQuery /> を2つ置いた状態で Network タブに api/books が1行しか無いところを撮ってください。③の 03_同じ通信が2回.png と並べて見せたいので、同じ見せ方で。

行数を比べる

bash
$ wc -l src/BooksEffect.jsx src/BooksQuery.jsx src/main.jsx
  52 src/BooksEffect.jsx
  35 src/BooksQuery.jsx
  22 src/main.jsx
  109 total
useEffect版Query版
部品のファイル52行35行
土台(main.jsx)0行+4行(アプリ全体で1回だけ)
キャッシュ・重複排除・再取得・リトライ❌ 入っていない✅ 入っている
競合状態への対処ignore を手書き✅ 書かなくていい

35行のうち、JSXは15行のままです。 減ったのは「取得の世話」の部分で、52 − 35 = 17行。しかも、②の表の6〜10が「無いまま」から「入っている」に変わっています。

17行しか減っていない、と読まないでください。 効くのは2画面目からです。 main.jsx の4行は一度きりで、画面が10枚になれば 17 × 10 = 170行が消えます。そして、6〜10を10回書く仕事は、最初から発生しません。

3つだけ覚える

useQuery が返すものは山ほどありますが、最初は3つで足ります。

名前意味注意
isPendingまだ一度もデータが無い(=読み込み中)v4 までは isLoading という名前だった。 ネットの古い記事はこちらで書かれている
isError失敗したerror に中身が入る
data取れたデータisPending が true の間は undefined。 だから先に isPending で分岐する

data.length を、isPending の判定より先に書かないでください。 Cannot read properties of undefined で落ちます(DOM操作の回で見たのと同じエラーの出方です)。

isFetching という似た名前もあります。 isPending は「まだ何も無い」、isFetching は「いま通信中(前のデータは表示できる)」です。「更新中…」を小さく出したいときは isFetching を使います。


④ キャッシュ — staleTime と gcTime

ここが、このライブラリで一番誤解されるところです。

既定のままだと、こうなる

まず、既定の動きを目で見ます。 ブラウザで、

  1. 検索欄に Linux と打つ(1.5秒くらい待って、2件出る)
  2. 検索欄を空にする(待たずに、すぐ3件出る)
  3. もう一度 Linux と打つ(待たずに、すぐ2件出る。だが Network には新しい通信が出ている)

3の挙動が、このライブラリの本体です。

キャッシュがあるので、画面には「前に取ったもの」を即座に出す。 そのうえで、裏で取り直して、返ってきたら差し替える。

「速い」と「新しい」を両立させるために、順番を入れ替えています。 待ってから出すのではなく、出してから直すのです。

Devtools を開くと、溜まっているものが見えます。 画面の隅に出ているアイコンを押してください。

["books",""]      fresh
["books","L"]     stale
["books","Li"]    stale
["books","Linux"] fresh

[スクリーンショット: 05_devtoolsのキャッシュ一覧.png] React Query Devtools を開いて、["books","Linux"] のように打った文字の分だけキャッシュが並んでいるところを撮ってください。

staleTime と gcTime は別物

この2つを混ぜると、設定を必ず間違えます。

設定意味既定
staleTime「取ってから何ミリ秒は、新しいとみなすか」0(=取った瞬間に古い)
gcTime「誰も見なくなってから何ミリ秒で、メモリから捨てるか」5分

時間の流れで書くと、こうです。

取得 ──[ staleTime ]──> stale(古い印が付く)
                          │
     画面から消える ──[ gcTime ]──> メモリから消える
  • stale は「消えた」ではありません。 表示には使われ続けます。 「次に見られたら取り直せ」という印が付いただけです
  • staleTime: 0 が既定なので、何もしないと「見るたびに取り直す」動きになります。表示は即座なので気づきにくいだけです

変えてみます。 src/main.jsx の new QueryClient() を、こう書き換えます。

const queryClient = new QueryClient({
  defaultOptions: {
    queries: {
      staleTime: 30 * 1000,
    },
  },
})

もう一度、Linux → 空 → Linux とやってください。 3回目に、Network に新しい通信が出ません。 30秒以内なら「まだ新しい」とみなすからです。

確認: Devtools の ["books","Linux"] が、30秒間 fresh のままで、そのあと stale に変わります。

既定では、画面に戻ると取り直す

これが、入れた直後に一番驚くところです。

やってみてください。

  1. ブラウザで一覧を出す
  2. 別のタブに切り替える(またはブラウザを最小化する)。v5 は「ページが見えなくなって、また見えた」ときに取り直します。ブラウザが見えたまま別のウィンドウをクリックしただけでは取り直しません
  3. 元のタブに戻る

Network タブに、通信が1本増えています。

[スクリーンショット: 06_フォーカスを戻すと再取得.png] 元のタブに戻った瞬間に Network タブへ api/books の行が増えるところを撮ってください。何も操作していないのに増えているのが分かる形で。

これは refetchOnWindowFocus という既定の動きです。バグではありません。

嬉しい場合と、うるさい場合があります。

例なぜ
嬉しい在庫数、通知の未読、チームで共有している一覧、価格他人が変えている可能性があるデータ。 戻ってきた瞬間に古い数字を見せたくない
うるさい重い集計、従量課金の外部API、変わらないマスタデータ戻るたびに金と時間がかかる。 しかも中身は変わっていない
危ない入力途中のフォームの隣にある一覧書いている最中に表示が入れ替わる。人が驚く

止め方は2つです。

// A: そのクエリだけ止める
useQuery({
  queryKey: ['books', q],
  queryFn: () => fetchBooks(q),
  refetchOnWindowFocus: false,
})
// B: アプリ全体の既定を変える(main.jsx の QueryClient)
defaultOptions: {
  queries: {
    staleTime: 30 * 1000,
    refetchOnWindowFocus: false,
  },
}

refetchOnWindowFocus: false を、入れた初日に全体へ書かないでください。 staleTime を伸ばすだけで、たいていは静かになります。 フォーカスで再取得しても、fresh なら通信は起きないからです。 「うるさい」の正体は、フォーカスの再取得ではなく staleTime: 0 のほうであることが多いです。


⑤ queryKey の設計 — 入れ忘れると古いデータが出る

このライブラリで一番多い事故がこれです。 エラーも警告も出ません。 ただ、間違ったデータが出ます。

わざと間違える

src/BooksQuery.jsx の queryKey から、q を消します。

  const { data, isPending, isError, error } = useQuery({
    queryKey: ['books'],
    queryFn: () => fetchBooks(q),
  })

ブラウザで、検索欄に Linux と打ってください。

一覧が変わりません。 3件のままです。 Network にも、新しい通信は1本も出ません。

[スクリーンショット: 07_queryKeyの入れ忘れ.png] 検索欄に Linux と入っているのに、一覧が3件(絞られていない)のままで、Network に新しい行が出ていないところを撮ってください。

理由は単純です。

queryKey は「そのデータの名前」です。 名前が ['books'] のままなら、React Query から見て「さっきと同じデータ」です。同じなら、取り直す理由がありません。 queryFn の中で q を使っているかどうかは、見ていません。

直します。 queryFn が使う値は、全部 queryKey に入れます。

    queryKey: ['books', q],

打つたびに絞り込まれるようになります。

覚え方

queryKey は、useEffect の依存配列と同じルールだと思ってください。

依存配列(useEffect)queryKey(useQuery)
中身effect の中で使う値を全部queryFn の中で使う値を全部
抜けると古い値を掴んだまま動く古いデータが出たまま、取り直さない
教えてくれるか✅ eslint が警告する❌ 誰も教えてくれない

依存配列は eslint が守ってくれますが、queryKey は誰も守ってくれません。 これが厄介なところです。

設計の型は、これで足ります。

['books']                      // 一覧(引数なし)
['books', q]                   // 検索語で絞った一覧
['books', { q, page, sort }]   // 条件が増えたらオブジェクトで1つに
['book', id]                   // 1件の詳細
  • 粗いほうから細かいほうへ並べる。 invalidateQueries({ queryKey: ['books'] }) が、['books', 何か] を全部まとめて無効化できるからです(⑥で使います)
  • オブジェクトを入れてよい。キーの並び順が違っても同じものとして扱われます(中身で比べているため)
  • 一覧と詳細で、名前を分ける。 ['books'] と ['book', id]。同じ名前にすると、詳細を取ったつもりで一覧が壊れます

1つだけ、実務の型を書いておきます。 queryKey を書く場所を、1ファイルにまとめてしまうやり方があります。const bookKeys = { all: ['books'], list: (q) => ['books', q] } のように書いて、必ずそこから取る。 文字列を各所で手書きしていると、'books' と 'book' の書き間違いに気づけません。 これは初日からやっていい対策です。


⑥ 更新系 — useMutation と invalidateQueries

ここまでは「取る」だけでした。 登録します。

登録の面倒さは、登録そのものではありません。 「登録したあと、一覧をどうやって出し直すか」です。

素の useEffect で書くと、こうなっていました。

// 登録側から呼べるように reload を外に出す
const reload = () => { /* さっきの fetch を丸ごともう一度 */ }
// 登録が成功したら
await postBook(input)
reload()               // ⚠️ 呼び忘れると、一覧が古いまま

「呼び忘れると古いまま」が、この書き方の欠点です。しかも、一覧が2箇所にあれば、2箇所とも呼ばせる必要があります。

useMutation で書く

src/BooksQuery.jsx を、こう直します。足すのは import 2つと、20行ほどです。

import { useState } from 'react'
import { useMutation, useQuery, useQueryClient } from '@tanstack/react-query'

const API = 'http://192.168.226.50:4182'

async function fetchBooks(q) {
  const res = await fetch(`${API}/api/books?q=${encodeURIComponent(q)}`)
  if (!res.ok) throw new Error(`HTTP ${res.status}`)
  return res.json()
}

async function postBook(input) {
  const res = await fetch(`${API}/api/books`, {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify(input),
  })
  if (!res.ok) throw new Error(`HTTP ${res.status}`)
  return res.json()
}

export default function BooksQuery() {
  const [q, setQ] = useState('')
  const [title, setTitle] = useState('')
  const queryClient = useQueryClient()

  const { data, isPending, isError, error } = useQuery({
    queryKey: ['books', q],
    queryFn: () => fetchBooks(q),
  })

  const addBook = useMutation({
    mutationFn: postBook,
    onSuccess: () => {
      queryClient.invalidateQueries({ queryKey: ['books'] })
      setTitle('')
    },
  })

  return (
    <div>
      <h2>Query版</h2>
      <input value={q} onChange={(e) => setQ(e.target.value)} placeholder="タイトルで検索" />

      <div style={{ margin: '12px 0' }}>
        <input value={title} onChange={(e) => setTitle(e.target.value)} placeholder="新しい本" />
        <button onClick={() => addBook.mutate({ title })} disabled={addBook.isPending || !title}>
          {addBook.isPending ? '登録中...' : '登録'}
        </button>
        {addBook.isError && <span style={{ color: 'crimson' }}> 登録できませんでした</span>}
      </div>

      {isPending && <p>読み込み中...</p>}
      {isError && <p style={{ color: 'crimson' }}>失敗しました: {error.message}</p>}
      {!isPending && !isError && data.length === 0 && <p>1件もありません</p>}
      {!isPending && !isError && data.length > 0 && (
        <ul>
          {data.map((b) => (
            <li key={b.id}>
              {b.title} / {b.author}
            </li>
          ))}
        </ul>
      )}
    </div>
  )
}

ブラウザで、「新しい本」の欄に Linuxの続き と入れて、登録を押してください。

  1. ボタンが「登録中…」になって、押せなくなる
  2. 1.5秒ほどで戻る
  3. 一覧に Linuxの続き が増えている
  4. <BooksQuery /> を2つ置いていれば、両方とも増えている

[スクリーンショット: 08_登録すると一覧が自動で更新.png] 登録ボタンを押したあと、下の一覧に新しい本が増えているところを撮ってください。2つ並べた両方が更新されているのが見える形で。

何が起きたのか

queryClient.invalidateQueries({ queryKey: ['books'] })

この1行が、「['books'] で始まる名前のデータは、全部古くなった」と宣言しています。

  • ['books', ''] も ['books', 'Linux'] も、まとめて stale になる(前方一致です)
  • そして、いま画面に出ているものだけが、自動で取り直されます。 画面に無いものは、次に見られたときに取り直されます
  • 「どこで一覧を表示しているか」を、登録側が知る必要がありません

これが reload() を手で呼ぶのとの決定的な違いです。 reload() は「誰を更新するか」を呼ぶ側が知っている必要があります。 画面が増えるたびに、呼び出しを足して回ることになります。 invalidateQueries は「このデータが古くなった」としか言いません。 誰が使っているかは、キャッシュが知っています。

useMutation の返り値も、覚えるのは3つです。

名前意味
mutate(引数)実行する関数。useQuery と違い、自動では動きません。押されたときに呼びます
isPending送信中。ボタンを disabled にして、二重送信を防ぐ
isError失敗した

mutate は Promise を返しません。 await したいときは mutateAsync です。ただし、mutateAsync は自分で try / catch しないと、握られていない例外になります。 最初は mutate と onSuccess / onError だけで足ります。


⑦ エラーの扱い — 既定で3回リトライされる

わざと失敗させます。 fetchBooks のURLに &fail=1 を足してください。

  const res = await fetch(`${API}/api/books?q=${encodeURIComponent(q)}&fail=1`)

ブラウザで見ると、「読み込み中…」が、やたら長く続きます。 Network タブには、

GET  api/books?q=&fail=1   500   1.5 s
GET  api/books?q=&fail=1   500   1.5 s
GET  api/books?q=&fail=1   500   1.5 s
GET  api/books?q=&fail=1   500   1.5 s

4本並びます。 最初の1回+リトライ3回です。エラー表示が出るまでに、10秒以上(この API では約13秒)かかります。

[スクリーンショット: 09_リトライが3回走る.png] Network タブに 500 が4本並んでいて、行と行の間隔がだんだん広がっているところを撮ってください。

既定は、こうです。

設定既定意味
retry3失敗したら3回やり直す
待ち時間1秒 → 2秒 → 4秒(最大30秒)だんだん間隔を空ける。 サーバーが落ちているときに追い打ちをかけないため
useMutation の retry0更新系はリトライしない。 二重登録になるため

取得はリトライされ、更新はされない——これは正しい既定です。取得は何回やっても同じですが、登録は2回やると2件できるからです。

retry: false にすべき場合

「サーバーが一時的に不調」なら、リトライは正しい対処です。 ですが、やり直しても絶対に直らない失敗があります。

状況リトライすべきか
ネットワークが切れた / 500 / 503 / タイムアウト✅ する価値がある
404(そんなIDは無い)❌ 何回やっても無い。 待たせるだけ
400(入力が間違っている)❌ 直るのは人が直したときだけ
401 / 403(ログインしていない・権限が無い)❌ 4回叩いて、4回怒られるだけ。 アカウントロックの引き金になることもある
開発中に、エラー画面をすぐ見たいとき❌ 待つのが無駄

全部止めるなら、こうです。

  const { data, isPending, isError, error } = useQuery({
    queryKey: ['books', q],
    queryFn: () => fetchBooks(q),
    retry: false,
  })

「サーバー側の失敗だけリトライする」なら、関数を渡します。

    retry: (failureCount, error) => {
      if (String(error.message).includes('HTTP 4')) return false
      return failureCount < 2
    },

上のコードが動くのは、fetchBooks が throw new Error('HTTP 404') のように、ステータスをメッセージに入れているからです。 error に何が入るかは、queryFn が投げたものそのものです。

queryFn の中で、if (!res.ok) throw を書き忘れないでください。 fetch は、404 でも 500 でも例外を投げません。 ok が false の Response を、正常に返します(非同期処理の回でやった落とし穴です)。 書き忘れると、エラー画面が出る代わりに {"message":"わざと失敗させました"} が「データ」として一覧に流れ込みます。 isError は永遠に false のままです。

確かめたら、&fail=1 は消しておいてください。


⑧ 入れるべきか — 入れないほうがいい場合がある

ここまで書いておいて言いますが、いつでも入れるべきものではありません。

状況判断
取得が1〜2箇所しかない❌ 入れない。 main.jsx の土台と、queryKey の設計と、既定の挙動(フォーカス再取得)を覚えるコストのほうが高い
一度取ったら二度と変わらない設定ファイルを読むだけ❌ 入れない。 キャッシュも再取得も要らない
画面が5枚を超えた / 同じデータを2箇所以上で使い始めた✅ 入れる。 ②の表の6〜10を書き始める前に
「登録したのに一覧が古い」を、2回以上直した✅ 入れる。 それは invalidateQueries が欲しくなっているサイン
一覧と詳細を行き来する画面がある✅ 入れる。 戻ったときに「即座に出て、裏で更新」が効くのはここ
他人が同時に変えるデータを扱う✅ 入れる。 フォーカス再取得が、そのまま価値になる

判断の言い方を1つに絞るなら、こうです。 「キャッシュを自分で書き始めたら、負け」。 「一度取ったやつ、どこかに置いておけないかな」と思った瞬間が、入れどきです。そこから自作すると、必ず ②の表の10項目を全部作ることになります。

そして、選択肢は1つではありません。 SWR は同じ系統の、より小さいライブラリです。やることはほぼ同じなので、小さいほうがよければこちらでも構いません(この記事の考え方はそのまま通じます)。


⑨ サーバー側で取るなら、そもそも要らないことがある

1段落だけ、先の話を書いておきます。

この記事でやったのは全部、「ブラウザの中で JavaScript が取りに行く」やり方でした。画面が出てから、通信が始まります。 だから「読み込み中」が要ります。

サーバー側でデータを取ってから HTML を作って送るやり方だと、「読み込み中」も「競合状態」も「キャッシュ」も、ブラウザ側の問題ではなくなります。Next.js のようなフレームワークや、React のサーバーコンポーネントがやっているのはそれです。そういう作りなら、TanStack Query は要らないか、要っても「操作してから変わる部分」だけになります。 ただし、その場合もキャッシュの問題は消えません。サーバー側に移るだけです。どこで持つかが変わります。 この話はSSRの回で、curl で取ると中身が空になるところから確かめます。


つまずいたところ

isLoading が無い、と5分悩んだ

ネットの記事を写して isLoading と書いたら、期待通りに動きませんでした。 v5 で isPending に変わっていました。

isLoading という名前自体は v5 にもありますが、意味が違います。 isPending && isFetching(=まだデータが無くて、いま取りに行っている)です。似ているので、動いてしまう場面もあり、余計に気づきませんでした。

npm ls @tanstack/react-query でバージョンを確かめてから、そのバージョンの公式ドキュメントを読む。 これを最初にやるべきでした。

new QueryClient() をコンポーネントの中に書いた

最初、App.jsx の中に書きました。 動きました。 ただし、キャッシュが一切効きませんでした。

描画のたびに新しいキャッシュができていたからです。「入れたのに通信が減らない」の8割はこれだと思います。Devtools を開いたら、キャッシュの一覧が毎回空になっていて、やっと気づきました。

「勝手に通信している」と思って、全部止めた

入れた翌日、Network タブに身に覚えのない通信が並んでいて、refetchOnWindowFocus: false と refetchOnMount: false を全部書きました。

静かになりました。 同時に、「登録したのに一覧が古い」が復活しました。 止めたのは、まさに欲しかった機能でした。

正しくは staleTime を伸ばすだけでした。 「再取得の回数」ではなく「何秒までを新しいとみなすか」を触る。 入り口が違っていました。

queryKey に q を入れ忘れて、半日気づかなかった

⑤でわざとやったやつを、本番でやりました。 エラーが出ないので、「検索が効かない」というバグとして報告されました。

queryFn の中では q を使っているので、コードを読んでも間違って見えません。 useEffect の依存配列なら eslint が教えてくれたのに、queryKey は誰も教えてくれない——この差を知らなかったのが原因です。

それ以来、queryFn: () => fetchBooks(q) と書いたら、指で q を差して queryKey に同じものがあるか確かめるようにしています。

エラー画面が出ずに、変なデータが一覧に並んだ

queryFn の中で if (!res.ok) throw を書き忘れました。 APIが 500 を返しているのに、isError が false のままでした。

{"message":"わざと失敗させました"} が data に入り、data.map で落ちました。 fetch は 500 を「失敗」とみなさないという、非同期処理の回で一度読んだはずのことを、ライブラリを入れた安心感で忘れていました。

ライブラリは、queryFn が投げたものしか知りません。 投げなければ、成功です。

練習用APIを止めたまま、Reactのせいにした

「急に全部エラーになった」と30分調べて、ターミナルを閉じたときに node api/server.js ごと落としていただけでした。

curl で1回叩けば5秒で分かる話です。画面から調べ始めたのが遠回りでした(エラーの読み方の回でやった「下から読む」と同じで、手前から確かめるべきでした)。


後片づけ

この記事で使った ~/reactlab/ は、実験用です。

まず、練習用APIを止めます。 起動しているターミナルで Ctrl+C を押します。

bash
$ ss -tlnp | grep 4182

確認: 何も返らなければ、止まっています。

開発サーバーも止めます。 起動しているターミナルで Ctrl+C。

bash
$ ss -tlnp | grep 5182

確認: 何も返らなければ、止まっています。

ポートを2つとも閉じます。

bash
$ sudo ufw delete allow 5182/tcp
$ sudo ufw delete allow 4182/tcp
$ sudo ufw status

確認: 一覧に 5182/tcp も 4182/tcp も残っていなければ成功です。

プロジェクトを消します。

bash
$ du -sh ~/reactlab
$ rm -rf ~/reactlab
$ ls ~

確認: reactlab が消えていれば片づけ完了です。

本線のものが無事なことを、必ず確認してください。

bash
$ ls ~/react-demo/src
$ ls ~/server

~/react-demo/ と ~/server/ は、この先の本線でも使うので消さないでください。

戻し方: もう一度試したくなったら、①の npm create vite@latest reactlab -- --template react からやるだけです。数分で戻せます。 node_modules だけ消して中身を残すなら rm -rf ~/reactlab/node_modules、戻すのは cd ~/reactlab && npm install です(npmの回)。


まとめ

  • 取得のコードが膨らむのは、Reactが下手だからではない。 useEffect が通信のための道具ではないので、足りないぶんを毎回手で埋めていただけ
  • サーバーから来たデータは「自分が持ち主ではない」。 持ち主が別にいるものを useState に入れると、「向こうで変わったら」を全部自分で面倒みることになる
  • データ取得に必要な仕事は10個ある。 素の useEffect + fetch が持っているのは、そのうち5個まで
  • 持っていないのは、キャッシュ・重複排除・フォーカス再取得・更新後の再取得・リトライの5つ。 どれも、画面が増えると必ず要求される
  • 同じデータを2つの部品が欲しがると、素の fetch は2回叩く。 useQuery は同じ queryKey なら1回にまとめる
  • ライブラリを入れても、「読み込み中 / エラー / 空 / 正常」の4状態は消えない。 消えるのは、4つを自分で組み立てて矛盾しないように守る手間
  • useQuery は isPending / isError / data の3つで足りる。 data は isPending の間は undefined。先に分岐する
  • isLoading は v4 までの名前。 バージョンを確かめてから、そのバージョンのドキュメントを読む
  • new QueryClient() はコンポーネントの中で作らない。 描画のたびに作り直されて、キャッシュが一切効かない
  • 行数は 52 → 35。 効くのは2画面目から。 土台の4行は一度きりで、10画面なら170行が消える
  • このライブラリの本体は「出してから直す」。 待ってから出すのではなく、キャッシュを即座に出して、裏で取り直して差し替える
  • staleTime と gcTime は別物。 「古いとみなすまで」と「メモリから捨てるまで」
  • staleTime の既定は 0。 何もしないと「見るたびに取り直す」。表示が速いので気づきにくい
  • stale は「消えた」ではない。 表示には使われ続ける。「次に見られたら取り直せ」という印
  • 既定では、別ウィンドウから戻るだけで取り直す。 在庫や未読なら嬉しく、重い集計や従量課金APIならうるさい
  • 「うるさい」の対処に refetchOnWindowFocus: false を最初に書かない。 staleTime を伸ばせば、fresh の間は通信そのものが起きない
  • queryKey には、queryFn が使う値を全部入れる。 入れ忘れると、古いデータが出たまま取り直さない
  • その事故は、エラーも警告も出ない。 依存配列は eslint が守ってくれるが、queryKey は誰も守ってくれない
  • キーは粗いほうから細かいほうへ並べる。 ['books'] → ['books', q]。 前方一致でまとめて無効化できるようにするため
  • 更新は useMutation。 useQuery と違って自動では動かない。mutate() を押されたときに呼ぶ
  • 登録が終わったら invalidateQueries で「古くなった」と伝える。 消すのではなく、印を付けるだけ
  • reload() を手で呼ぶのとの違いは、「誰が使っているか」を呼ぶ側が知らなくていいこと。 画面が増えても、呼び出しを足して回らなくていい
  • isPending でボタンを disabled にする。 二重登録は、リトライではなく人の二度押しで起きる
  • 取得は既定で3回リトライされ、更新はされない。 これは正しい。取得は何度やっても同じで、登録は2回やると2件できる
  • 404 / 400 / 401 は、やり直しても直らない。 待たせるだけで、権限系はロックの引き金にもなる。retry: false を検討する
  • queryFn の中で if (!res.ok) throw を書き忘れない。 fetch は 500 でも例外を投げないので、エラーの中身が「データ」として流れ込む
  • 取得が1〜2箇所なら入れない。 土台と queryKey と既定の挙動を覚えるコストのほうが高い
  • 入れどきは「キャッシュを自分で書き始めたとき」。 「一度取ったやつ、どこかに置けないかな」と思った瞬間
  • 選択肢は1つではない。 SWR は同じ系統の、より小さいもの。考え方はそのまま通じる
  • サーバー側でデータを取る作りなら、そもそも要らないことがある。 ただしキャッシュの問題は消えず、サーバー側に移るだけ

参考リンク


次に読む

この記事は 【深掘り】React の 13 / 24 本目です。

記事
← 前の記事条件分岐の書き方 — 三項演算子が5段ネストした
→ 次の記事エラー境界 — 例外1つで画面が真っ白

上から順に読めば積み上がるように並べています。 飛ばしても構いませんが、詰まったら前の回に戻ってください。

全体の順路は はじめに にあります。

roadmap.sh のどこをやっているか

Frontend›React — Data Fetching
  • 自分で書くと何が必要になるか
  • TanStack Query とキャッシュ設計

この記事は、上の項目を実際に手を動かして確かめる回です。

よかったらシェアしてね!
  • URLをコピーしました!
  • URLをコピーしました!

コメント

コメントする

目次