最新の Web アプリのほとんどは、常にサーバーと通信します。 JavaScript Fetch API はこれを行うための標準的な方法であり、ブラウザと Node.js 18 以降に組み込まれているため、インストールするものは何もありません。

基本的な使用方法には 2 行かかりますが、多くのチュートリアルはそこで終わり、実際のバグを引き起こす部分である障害処理を省略しています。このガイドの例を Node.js 24 上の小規模なローカル サーバーに対してテストしました。示されている出力はその実行からのものです。コード内の example.com は独自の API を表します。 Promise が初めての場合は、JavaScript Promise の説明 から始めてください。

フェッチAPIとは何ですか?

Fetch は、HTTP リクエストを行うための Promise ベースのインターフェイスです。これは古いコールバック駆動型 XMLHttpRequest に置き換わるもので、現在では多くのプロジェクトが単純な呼び出し用のライブラリを追加するのではなく、これを使用しています。

GETリクエスト

Fetch はデフォルトで GET リクエストを作成します。 2 つのステップがあり、それぞれ await が必要です。最初に応答ヘッダーが到着し、次に本文を読み取ります。

const response = await fetch("https://example.com/users/1");
const user = await response.json();

console.log(user);

// { id: 1, name: 'Asha' }

本文が大きく、ヘッダーよりも遅く到着する可能性があるため、2 つのステップが存在します。ブラウザ スクリプトでは、トップレベル await にモジュールが必要なので、通常はこれを async 関数内に置きます。 JavaScript の非同期/待機ガイドを参照してください。

応答オブジェクト

本文を読む前に、応答を検査できます。

console.log(response.status, response.ok, response.headers.get("content-type"));

// 200 true application/json

ボディは 1 回だけ読み取ることができます。 json() の 2 回目の呼び出しはテストで失敗しました。

await res.json();
await res.json();

// TypeError: Body is unusable: Body has already been read

2 回読み取る必要がある場合は、最初に response.clone() を呼び出します。

大きな驚き: 404 はスローしない

これがこの記事で最も重要なことです。存在しないユーザーをリクエストしました:

const res = await fetch("https://example.com/users/999");
console.log(res.status, res.ok);

// 404 false

例外はスローされませんでした。フェッチに関する限り、リクエストは機能しました。サーバーに到達し、応答しました。 Promise は、ネットワーク障害など、使用可能な応答がまったく到着しない場合にのみ拒否されます。したがって、次のようなコードには隠れたバグがあります。

try {
  const res = await fetch(url);
  const data = await res.json();   // may be an error payload
  showUser(data);                  // runs anyway for 404 and 500
} catch (error) {
  showError();                     // does not run for 404 or 500
}

HTTP ステータス コードのチートシートを確認して、各コードの意味を確認してください。

再利用可能なヘルパー

このチェックをどこでも繰り返さないでください。一度ラップしてください:

async function getJson(url, options) {
  const response = await fetch(url, options);
  if (!response.ok) {
    throw new Error(`Request failed with status ${response.status}`);
  }
  return response.json();
}

try {
  await getJson("https://example.com/users/999");
} catch (error) {
  console.log("caught:", error.message);
}

// caught: Request failed with status 404

現在、HTTP エラーとネットワーク エラーは両方とも同じ catch に分類されます。この小さな機能は、すべてのプロジェクトに導入する価値があります。実際のバージョンでは、応答本文からエラー メッセージを読み取り、解析する JSON がない 204 No Content 応答を処理することもあります。

JSONデータをPOSTする

オプション オブジェクトを 2 番目の引数として渡します。 JSON の場合、データを文字列に変換し、ヘッダーを設定するという 2 つのことを自分で行う必要があります。

const created = await getJson("https://example.com/users", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({ name: "Ben" }),
});

console.log(created);

// { id: 2, name: 'Ben', type: 'application/json' }

テスト サーバーは受信したコンテンツ タイプをエコー バックし、ヘッダーが到着したことを確認しました。多くのフレームワークは JSON が宣言されたときにのみ解析するため、このヘッダーを忘れることは混乱を招くサーバー エラーの一般的な原因となります。フォームまたはファイルをアップロードするには、FormDataオブジェクトを体として、そして実行するそうではないセットContent-Typeブラウザ自体が境界値を追加する必要があるためです。

他の方法とオプション

REST と他の API スタイルのどちらを選択しますか? REST と GraphQL を比較すると、フェッチがそれぞれにどのように適合するかがわかります。

クエリ文字列

特殊文字によってクエリ文字列が分割されるため、テキストを結合してクエリ文字列を作成しないでください。 URLSearchParams はエンコーディングを処理します。

const params = new URLSearchParams({ q: "red shoes", page: 2 });
console.log(params.toString());

// q=red+shoes&page=2

await getJson(`https://example.com/search?${params}`);

// { q: 'red shoes', page: '2' }

サーバーは red shoes を正しく受信し、スペースが復元されました。

タイムアウトとキャンセル

別の指示をしない限り、Fetch は遅いサーバーでは長時間待機します。 AbortSignal.timeout() は制限を設定します。私たちのテスト エンドポイントは、200 ミリ秒の制限に対して 2 秒かかりました。

try {
  await fetch("https://example.com/slow", { signal: AbortSignal.timeout(200) });
} catch (error) {
  console.log(error.name);
}

// TimeoutError

たとえば、ユーザーがページを離れたり、新しい検索語を入力したりした場合に手動でキャンセルするには、AbortController を使用します。

const controller = new AbortController();
const pending = fetch("https://example.com/slow", { signal: controller.signal });

controller.abort();

try {
  await pending;
} catch (error) {
  console.log(error.name);
}

// AbortError

複数のリクエストを一度に実行するには、Promise.all を使用します。これは、一度に 1 つずつ待つよりもはるかに高速です。

const [user, search] = await Promise.all([
  getJson("https://example.com/users/1"),
  getJson("https://example.com/search?q=a&page=1"),
]);

あらゆる失敗

私たちの実行での各失敗の様子と、それらを区別する方法は次のとおりです。

最後の行は本番環境では一般的です。 502 を返すプロキシは、HTML エラー ページを送信することがよくあります。これを再現し、res.json()がSyntaxErrorを投げました。解析する前に response.ok をチェックすると、紛らわしい解析エラーではなく、実際の問題を報告することになります。

CORS と認証情報

ブラウザでは、あるオリジンから別のオリジンへのリクエストは、オリジン間のリソース共有ルールである CORS の対象となります。 Access-Control-Allow-Origin に関するエラーが表示された場合、修正はサーバーに属しているため、サイトを許可する必要があります。 JavaScript では、失敗は一般的な TypeError としてのみ表示されるため、実際の理由についてはブラウザーのコンソールを確認してください。 Node.js は CORS を強制しないため、スクリプト内で機能するリクエストがブラウザーでは引き続き失敗する可能性があります。

デフォルトでは、ブラウザはクロスオリジンリクエストで Cookie を送信しません。必要な場合は credentials: "include" を設定し、サーバーがそれを許可していることを確認してください。秘密の API キーは誰でも読み取ることができるため、ブラウザーの JavaScript には決して入れないでください。それらをサーバー上に保管してください。

よくある間違い

• チェックしません response.ok。 エラー応答は成功として扱われます。
• 2 番目の await. response.json() を忘れると、Promise も返されます。
• 忘れるJSON.stringify。本体が送信するときにオブジェクトを渡す[object Object]。
• Content-TypeをFormDataで設定します。 これにより境界が壊れるため、省略します。
• タイムアウトがない。 リクエストがハングすると、ページのスピナーが無期限に実行されたままになる可能性があります。
• 空の応答の JSON を解析します。 204 には本文がなく、json() がスローされます。

まとめ

フェッチは、その主なルールを覚えてしまえば簡単です。つまり、応答は成功と同じではありません。小さなヘルパーをプロジェクトにコピーし、タイムアウトを追加して、失敗パスをテストします。次のステップとして、API からデータをロードし、明確なエラー メッセージを表示し、ユーザーが遅い検索をキャンセルできるようにする小さなページを構築します。

よくある質問

学び続ける