Day 22:API通信でユーザー検索アプリを作る
この日は、fetchでAPIにリクエストを送り、async / awaitで応答を待ち、取得したデータを画面に表示するユーザー検索アプリを作ります。読み込み中、エラー、検索結果なしの状態も分けて表示します。
学習用APIには、テストデータを返すDummyJSONを使います。ユーザー検索は/users/search?q=検索語で行え、結果はusers配列とtotalを含みます。selectを使って必要な項目だけを指定できます。(🔗 dummyjson.com)
1. API通信の流れを理解する
API通信とは、アプリからサーバーへリクエストを送り、返ってきたデータを利用することです。ユーザー検索アプリでは、次の順に処理します。
- 検索欄に入力された文字を受け取ります。
- 検索ボタンが押されたらAPIへリクエストを送ります。
- APIの応答を待ちます。
- 成功したらユーザー一覧をStateに保存します。
- 画面に応じてローディング、エラー、結果、検索結果なしを表示します。
ネットワーク通信には時間がかかることがあります。そのため、「データを取得する処理」と「待っている間に何を表示するか」を一緒に考えます。
2. fetchとasync / await
fetch()は、指定したURLへリクエストを送るブラウザー標準の関数です。通信結果はすぐには返らないため、awaitで完了を待ちます。awaitを使う関数にはasyncを付けます。
// asyncを付けた関数の中でawaitを使います
async function loadData() {
// fetchの応答が返るまで待ちます
const response = await fetch("https://example.com/api");
// JSONデータへの変換が終わるまで待ちます
const data = await response.json();
// 受け取ったデータを返します
return data;
}JavaScriptfetch()は、HTTPエラーのステータスを受け取っただけでは必ずしも例外を投げません。たとえば404や500でも応答自体は返るので、response.okを確認してからJSONを処理します。(🔗 developer.mozilla.org)
3. アプリの状態を整理する
検索アプリでは、画面に必要なデータをStateとして管理します。
query:検索欄の入力内容です。users:APIから取得したユーザー一覧です。total:APIが返した検索結果数です。isLoading:通信中かどうかを表します。error:通信やデータ処理に失敗したときのメッセージです。hasSearched:少なくとも一度検索したかを表します。
検索前と、検索結果が0件だった場合は、画面に表示したい案内が異なります。そのため、単にusers.length === 0だけで判断せず、検索済みかどうかも管理します。
4. Next.jsの準備
App Routerを使っている場合、ページはapp/page.jsまたはsrc/app/page.jsに作成します。今回はuseState、フォーム送信、ブラウザーからのAPI通信を使うため、Client Componentにします。ファイルの先頭に'use client'を記述してください。(🔗 nextjs.org)
my-app/
└── app/
└── page.js
開発サーバーが動いていない場合は、プロジェクトフォルダーで起動します。
# Next.jsの開発サーバーを起動します
npm run dev
5. ユーザー検索アプリの完成コード
次のコードをapp/page.jsまたはsrc/app/page.jsに記述します。検索を送信するとAPIを呼び、結果を一覧で表示します。
// このファイルをClient Componentとして扱います
"use client";
// ReactのState、Effect、Refを読み込みます
import { useEffect, useRef, useState } from "react";
// ユーザー検索アプリのページです
export default function UserSearchPage() {
// 検索欄の入力値を管理します
const [query, setQuery] = useState("");
// APIから受け取ったユーザー一覧を管理します
const [users, setUsers] = useState([]);
// APIが返した検索結果数を管理します
const [total, setTotal] = useState(0);
// 通信中かどうかを管理します
const [isLoading, setIsLoading] = useState(false);
// エラーメッセージを管理します
const [error, setError] = useState("");
// 検索を一度でも実行したかを管理します
const [hasSearched, setHasSearched] = useState(false);
// 現在の通信を中断するための参照を保持します
const controllerRef = useRef(null);
// ページが外れるときに、実行中の通信を中断します
useEffect(() => {
// cleanup関数を返します
return () => {
// まだ通信中のコントローラーがあれば中断します
controllerRef.current?.abort();
};
}, []);
// フォーム送信時にユーザーを検索します
async function handleSubmit(event) {
// ブラウザー標準のフォーム送信による再読み込みを防ぎます
event.preventDefault();
// 入力前後の空白を取り除きます
const trimmedQuery = query.trim();
// 空欄では検索せず、案内を表示します
if (trimmedQuery === "") {
setError("検索する名前を入力してください。");
setUsers([]);
setTotal(0);
setHasSearched(false);
return;
}
// 前回の検索が残っていれば中断します
controllerRef.current?.abort();
// 今回の通信を中断するためのコントローラーを作ります
const controller = new AbortController();
// cleanupや次の検索で使えるように保持します
controllerRef.current = controller;
// 新しい検索を始める前に画面の状態を初期化します
setIsLoading(true);
setError("");
setUsers([]);
setTotal(0);
setHasSearched(true);
try {
// 検索語と取得したい項目をURLパラメーターにします
const params = new URLSearchParams({
q: trimmedQuery,
limit: "10",
select: "id,firstName,lastName,email,company",
});
// ユーザー検索APIへリクエストを送ります
const response = await fetch(
`https://dummyjson.com/users/search?${params.toString()}`,
{
// 通信中断用のsignalをfetchに渡します
signal: controller.signal,
}
);
// HTTPステータスが成功か確認します
if (!response.ok) {
throw new Error(`HTTPエラー:${response.status}`);
}
// レスポンス本文をJSONとして読み込みます
const data = await response.json();
// 想定している形式か確認します
if (!Array.isArray(data.users)) {
throw new Error("APIから想定外のデータが返されました。");
}
// 通信が中断されていない場合だけ検索結果を反映します
if (!controller.signal.aborted) {
setUsers(data.users);
setTotal(
// totalが数値でなければ、取得した配列の件数を使います
Number.isFinite(data.total) ? data.total : data.users.length
);
}
} catch (requestError) {
// 古い検索を中断した場合は、エラーとして表示しません
if (requestError.name === "AbortError") {
return;
}
// その他の通信エラーやデータ処理エラーを表示します
setError("ユーザーを取得できませんでした。時間をおいて再度お試しください。");
} finally {
// 現在の検索が中断されていない場合だけ読み込みを終了します
if (!controller.signal.aborted) {
setIsLoading(false);
}
}
}
// 画面を表示します
return (
<main>
<h1>ユーザー検索</h1>
<p>名前の一部を入力して、サンプルユーザーを検索します。</p>
{/* フォーム送信時にAPI検索を実行します */}
<form onSubmit={handleSubmit}>
<label htmlFor="user-query">検索する名前</label>
{/* 入力値をStateと同期させます */}
<input
id="user-query"
type="search"
value={query}
onChange={(event) => setQuery(event.target.value)}
placeholder="例:Emily"
maxLength={80}
required
/>
{/* クリックまたはEnterキーで検索します */}
<button type="submit" disabled={isLoading}>
{isLoading ? "検索中..." : "検索"}
</button>
</form>
{/* 検索中の状態を表示します */}
{isLoading && (
<p aria-live="polite">ユーザーを検索しています...</p>
)}
{/* エラーがあるときに案内を表示します */}
{error !== "" && (
<p role="alert">{error}</p>
)}
{/* 成功し、検索結果がある場合に一覧を表示します */}
{!isLoading && error === "" && users.length > 0 && (
<section aria-labelledby="results-heading">
<h2 id="results-heading">検索結果</h2>
<p>該当:{total}件(この画面では最大10件を表示)</p>
<ul>
{users.map((user) => (
// APIから取得したidを各項目のkeyに使います
<li key={user.id}>
<article>
<h3>
{user.firstName} {user.lastName}
</h3>
{/* APIがメールアドレスを返した場合だけ表示します */}
{user.email && <p>メール:{user.email}</p>}
{/* 会社情報がある場合だけ表示します */}
{user.company?.name && (
<p>会社:{user.company.name}</p>
)}
</article>
</li>
))}
</ul>
</section>
)}
{/* 検索済みで結果が0件の場合の案内です */}
{!isLoading &&
error === "" &&
hasSearched &&
users.length === 0 && (
<p>該当するユーザーは見つかりませんでした。</p>
)}
</main>
);
}JSX6. asyncとawaitを順番に読む
handleSubmitにはasyncが付いているので、その中でawaitを使えます。処理は次の順番で進みます。
- `fetch()`がAPIへリクエストを送ります。
- `await`がAPIから応答が届くまで待ちます。
- `response.ok`でHTTP応答が成功か確認します。
- `response.json()`でJSONをJavaScriptの値に変換します。
- `setUsers()`と`setTotal()`で取得結果をStateに保存します。
awaitを使うと、非同期処理を上から順に読む形で書けます。通信失敗などのエラーはtry...catchで受け取ります。
7. URLパラメーターを安全に組み立てる
検索語をそのままURLへ連結すると、空白や記号を含む入力で問題が起こることがあります。完成コードではURLSearchParamsを使って、検索語や取得項目をURLパラメーターとして組み立てています。
// 検索条件をURLパラメーターにまとめます
const params = new URLSearchParams({
q: trimmedQuery,
limit: "10",
select: "id,firstName,lastName,email,company",
});
// 完成したクエリ文字列をURLに付けます
const url = `https://dummyjson.com/users/search?${params.toString()}`;JSXDummyJSONの検索結果にはプロフィールのさまざまな項目が含まれる場合があります。今回のアプリでは画面に必要な項目をselectで指定しています。実際のアプリでも、APIから必要なデータだけを扱うようにしましょう。(🔗 dummyjson.com)
8. ローディング・エラー・結果なしを分ける
検索結果が表示されない理由は、ひとつではありません。通信中、通信エラー、検索結果0件、検索前の状態を分けると、利用者にも開発者にも分かりやすくなります。
- 通信中:`isLoading`が`true`です。
- エラー:`error`にメッセージが入っています。
- 結果あり:`users.length > 0`です。
- 検索結果なし:検索済みで、`users.length === 0`です。
- 未検索:`hasSearched`が`false`です。
aria-live="polite"は読み込み状態などの更新を支援技術に伝えるために、role="alert"はエラーを明確に伝えるために使っています。
9. response.okを確認する理由
fetch()は、ネットワークそのものに接続できない場合などには失敗します。しかし、サーバーから404や500の応答が返った場合、fetch()が必ずしも例外を投げるわけではありません。そのため、次のようにHTTPステータスを確認します。(🔗 developer.mozilla.org)
// HTTP応答が成功でなければ、エラー処理へ進めます
if (!response.ok) {
throw new Error(`HTTPエラー:${response.status}`);
}JSXこれを省くと、エラー応答を正常なJSONだと思って後続処理を進めてしまうことがあります。
10. 連続検索とAbortController
検索中に別の語で検索したり、ページを離れたりすると、不要になった通信が残ることがあります。この例ではAbortControllerを使い、次の検索が始まったら前の通信を中断し、ページが外れるときにも中断します。fetch()にsignalを渡すと、abort()でリクエストを中止できます。(🔗 developer.mozilla.org)
古いリクエストが新しい検索より後に完了すると、画面に古い検索結果が表示される可能性があります。前の通信を中断することで、この競合を避けやすくなります。
11. APIのデータをそのまま信用しない
外部APIの応答は、常に想定どおりとは限りません。通信が失敗したり、応答形式が変わったりする可能性があります。完成コードでは、少なくともdata.usersが配列かどうかを確認しています。
また、APIが返すユーザー情報は学習用のサンプルデータです。検索結果を本物の利用者情報と混同しないでください。実際の個人情報を扱うアプリでは、取得する項目、表示範囲、保存先、アクセス権限を慎重に設計します。
12. よくあるつまずき
- 取得したのに画面が変わらない:データを通常の変数ではなくStateに保存しているか確認します。
- 404や500がエラー表示されない:`response.ok`を確認しているか確認します。
- JSONの読み込みで失敗する:APIの応答がJSONか、想定した形式かを確認します。
- 空の検索で不必要な通信が走る:`trim()`した検索語が空でないか、送信前に確認します。
- 連続検索で前の結果が後から表示される:前のリクエストを`AbortController`で中断する方法を検討します。
- 検索前から「該当なし」と出る:検索済みかどうかを`hasSearched`などで区別します。
- Client Componentに`use client`がない:ファイルの先頭に指定します。
13. 練習用テンプレート
次のテンプレートを使って、商品や記事など別のAPIデータを表示する練習もできます。
// このファイルをClient Componentとして扱います
"use client";
// Reactの状態管理機能を読み込みます
import { useState } from "react";
// API検索の練習用コンポーネントです
export default function SearchPractice() {
// TODO: 検索語を管理するStateを作ります
// TODO: APIから取得したデータを管理するStateを作ります
// TODO: ローディング状態を管理するStateを作ります
// TODO: エラーメッセージを管理するStateを作ります
// フォーム送信時の検索処理です
async function handleSubmit(event) {
// TODO: フォームの再読み込みを防ぎます
// TODO: 入力値をtrim()して空欄を確認します
try {
// TODO: fetchでAPIにリクエストを送ります
// TODO: response.okを確認します
// TODO: response.json()でデータを読み込みます
// TODO: 取得したデータをStateに保存します
} catch (error) {
// TODO: エラー用Stateに案内を保存します
} finally {
// TODO: ローディング状態を解除します
}
}
return (
<main>
<h1>API検索の練習</h1>
{/* TODO: 検索フォームを作ります */}
{/* TODO: ローディング、エラー、結果を条件付きで表示します */}
</main>
);
}JSX14. Day 22のチェックリスト
- `fetch()`でAPIへリクエストを送れます。
- `async` / `await`で通信の完了を待てます。
- `response.ok`を確認してHTTPエラーを扱えます。
- `response.json()`でJSONをJavaScriptのデータに変換できます。
- 取得したデータをStateに保存して画面に表示できます。
- ローディング、エラー、結果なしを区別できます。
- 検索語を`URLSearchParams`でURLに含められます。
- `AbortController`で不要な通信を中断できます。
API通信では、fetchでリクエストを送り、応答の成功を確認し、JSONを読み込んでStateに保存します。さらに、通信中・失敗・検索結果なしの画面を用意すると、使いやすく壊れにくいアプリになります。まずは検索語を変えて試し、エラー時や0件時にどの表示になるかも確認してみましょう。
