JavaScript Fetch API入門：GET・POST・JSON・エラー処理

Fetch は Promise ベースの HTTP クライアント

fetch はブラウザや最近の Node に標準で組み込まれているので、追加で何かをインストールする必要はありません。URL を渡すと Response オブジェクトに解決される Promise が返ってくる、というシンプルな仕組みで、コアの API はこれだけです。

fetch("https://jsonplaceholder.typicode.com/todos/1")
    .then(response => response.json())
    .then(data => console.log(data))
    .catch(err => console.error("失敗:", err));

.then が2つ連なっているのは、非同期のステップが2段階あるからです。まずレスポンスヘッダーが届きます（最初の Promise が解決されるのはこのタイミング）。その後にボディを読み取ってパースします（response.json() 自体も Promise を返します）。ボディは、こちらから要求するまでダウンロードされません。

同じ流れを async/await で書くと、上から下に読める普通のコードのように見えます。

async function loadTodo() {
    const response = await fetch("https://jsonplaceholder.typicode.com/todos/1");
    const data = await response.json();
    console.log(data);
}

loadTodo();

await を 2 回使うので、サスペンションポイントも 2 つ。処理内容は同じですが、こちらの方が上から順に読み下しやすくなります。

Response オブジェクトについて

fetch の戻り値はレスポンスボディそのものではなく、Response オブジェクトです。ここにはメタデータに加えて、ボディをさまざまな形式で取り出すためのメソッドが用意されています。

async function inspect() {
    const response = await fetch("https://jsonplaceholder.typicode.com/todos/1");

    console.log(response.status);       // 200
    console.log(response.ok);           // 200-299 の場合は true
    console.log(response.headers.get("content-type"));

    const data = await response.json();
    console.log(data.title);
}

inspect();

レスポンスボディの読み取りには .json()、.text()、.blob()、.arrayBuffer()、.formData() が使えます。いずれも Promise を返します。ただし、ボディを読めるのは1回だけ。同じレスポンスに対して .json() を2回呼ぶと、2回目は例外になります。

最大の落とし穴: HTTP エラーでは reject されない

fetch に入門したばかりの人がほぼ全員ハマるポイントです。404 や 500 のレスポンスは、実は reject されません。Promise は普通に解決され、response.ok === false になるだけ。fetch が reject するのは、リクエストそのものが完了できなかったとき、つまり DNS 解決の失敗、ネットワーク切断、CORS ブロックなどに限られます。

つまり、何も考えずに fetch を書くと、エラーページの HTML を平然と受け取ってしまい、後から .json() で落ちるハメになります。

async function buggy() {
    // このURLは404を返しますが、fetchはそれでもresolveします。
    const response = await fetch("https://jsonplaceholder.typicode.com/nope/999");
    const data = await response.json();    // エラーになるか、意味不明なデータが返る可能性あり
    console.log(data);
}

buggy();

response.ok を自分でチェックして、サーバーがエラーステータスを返したら明示的に throw するのが正しい対処法です。

async function loadTodo(id) {
    const response = await fetch(`https://jsonplaceholder.typicode.com/todos/${id}`);

    if (!response.ok) {
        throw new Error(`HTTP ${response.status}: ${response.statusText}`);
    }

    return response.json();
}

loadTodo(1).then(console.log).catch(err => console.error(err.message));

if (!response.ok) のチェックは体に染み込ませておきましょう。自作の fetch ラッパーには、必ず入れておきたいお約束です。

POST リクエストを送る

デフォルトは GET リクエストです。それ以外のメソッドを使いたいときは、第2引数にオプションオブジェクトを渡します。

async function createPost() {
    const response = await fetch("https://jsonplaceholder.typicode.com/posts", {
        method: "POST",
        headers: {
            "Content-Type": "application/json"
        },
        body: JSON.stringify({
            title: "hello",
            body: "from fetch",
            userId: 1
        })
    });

    if (!response.ok) throw new Error(`HTTP ${response.status}`);
    const data = await response.json();
    console.log(data);
}

createPost();

ここで押さえておきたいポイントが3つあります。

• method のデフォルトは "GET" です。POST・PUT・DELETE・PATCH を使うときは明示的に指定しましょう。
• body に渡せるのは文字列（または FormData、Blob など）だけです。fetch はオブジェクトを勝手にシリアライズしてくれないので、JSON.stringify(...) は自分で書く必要があります。
• Content-Type ヘッダーは、サーバーに対して body のパース方法を伝える役割を持ちます。これを忘れると、多くのサーバーはボディをただのプレーンテキストとして扱ってしまいます。

ヘッダー・クエリ文字列・その他のオプション

ヘッダーはただのオブジェクト（もしくは Headers インスタンス）として渡せます。クエリ文字列は自分で組み立てる形で、普段は URLSearchParams を使うのが定番です。

async function search(query, token) {
    const params = new URLSearchParams({ q: query, limit: "10" });
    const url = `https://api.example.com/search?${params}`;

    const response = await fetch(url, {
        headers: {
            "Authorization": `Bearer ${token}`,
            "Accept": "application/json"
        }
    });

    if (!response.ok) throw new Error(`HTTP ${response.status}`);
    return response.json();
}

URLSearchParams を使えば、スペースやアンパサンド、Unicode 文字などのエンコードを自動でやってくれます。エスケープが必要な文字が混ざっていても、URL が壊れる心配はありません。

実際のコードでよく見かける他のオプションも紹介しておきます。クロスオリジンで Cookie を送りたいときは credentials: "include"、HTTP キャッシュを無視したいときは cache: "no-store"、CORS の挙動を制御するには mode: "cors"(通常はこれがデフォルト) といった具合です。

AbortController で fetch リクエストをキャンセルする

途中でリクエストを中断したい場面ってありますよね。ユーザーが検索ワードを打ち直したときや、応答が遅すぎるときなどです。そんなときに使うのが AbortController です。

async function loadWithTimeout(url, ms) {
    const controller = new AbortController();
    const timeout = setTimeout(() => controller.abort(), ms);

    try {
        const response = await fetch(url, { signal: controller.signal });
        if (!response.ok) throw new Error(`HTTP ${response.status}`);
        return await response.json();
    } finally {
        clearTimeout(timeout);
    }
}

loadWithTimeout("https://jsonplaceholder.typicode.com/todos/1", 3000)
    .then(console.log)
    .catch(err => console.error(err.name, err.message));

controller.abort() が呼ばれると、fetch の Promise は DOMException を投げて reject されます。この例外の name は "AbortError" になります。finally ブロックでタイマーをクリアしているのは、リクエストが成功した場合にタイマーが残り続けないようにするためです。

この「fetch + タイムアウト + クリーンアップ」のパターンは、ヘルパー関数にまとめて使い回すのがおすすめです。

再利用できるラッパー関数を作る

ここまでの内容を1つにまとめると、定型コードを一度だけ書けば済む小さなヘルパーができあがります。

async function apiRequest(url, options = {}) {
    const response = await fetch(url, {
        headers: { "Content-Type": "application/json", ...options.headers },
        ...options
    });

    if (!response.ok) {
        const text = await response.text();
        throw new Error(`HTTP ${response.status}: ${text || response.statusText}`);
    }

    if (response.status === 204) return null;   // コンテンツなし
    return response.json();
}

apiRequest("https://jsonplaceholder.typicode.com/todos/1")
    .then(console.log)
    .catch(err => console.error(err.message));

ヘッダーの変更箇所はひとつ、エラー処理もひとつ、空レスポンスの扱いもひとつ。ある程度の規模のアプリなら、結局こういう形に落ち着きます。

次は非同期コードのエラーハンドリング

fetch は非同期のエラーが顔を出しやすい代表格で、response.ok のチェックはそのうちのほんの一部でしかありません。次のページでは、Promise と async/await にまたがるエラーハンドリングを取り上げます。エラーがどこへ流れていくのか、どうキャッチするのか、そして気づかないうちにエラーがすり抜けてしまう落とし穴について見ていきましょう。