Fetch API w JavaScript: żądania, JSON i obsługa błędów

Fetch to klient HTTP oparty na obietnicach

fetch jest wbudowany w przeglądarki i nowoczesny Node. Podajesz mu URL, a on zwraca Promise, który rozwiązuje się do obiektu Response. W swej istocie to całe API:

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

Dwa wywołania .then, bo są dwa asynchroniczne kroki: najpierw przychodzą nagłówki odpowiedzi (tym rozwiązuje się pierwsza obietnica), potem treść zostaje odczytana i sparsowana (response.json() samo jest obietnicą). Treść nie jest pobierana, dopóki o nią nie poprosisz.

Ten sam przepływ z async/await czyta się jak zwykły kod z góry na dół:

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

loadTodo();

Dwa await, dwa punkty wstrzymania. Ta sama praca, czytelniejsza kolejność.

Obiekt Response

To, co dostajesz z powrotem, nie jest treścią, tylko obiektem Response z metadanymi i metodami do odczytu treści w różnych formach:

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

    console.log(response.status);       // 200
    console.log(response.ok);           // true for 200-299
    console.log(response.headers.get("content-type"));

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

inspect();

Treść możesz odczytać przez .json(), .text(), .blob(), .arrayBuffer() lub .formData(). Każda z tych metod zwraca obietnicę. Treść da się odczytać tylko raz: wywołaj .json() dwa razy na tej samej odpowiedzi, a drugie wywołanie rzuci błąd.

Wielka pułapka: błędy HTTP nie odrzucają obietnicy

Na tym potyka się prawie każdy, kto zaczyna z fetch. Odpowiedź 404 czy 500 nie jest odrzuceniem. Obietnica rozwiązuje się normalnie, z response.ok === false. Fetch odrzuca obietnicę tylko wtedy, gdy samego żądania nie dało się wykonać: awaria DNS, brak sieci, blokada CORS.

To znaczy, że naiwny fetch chętnie poda ci stronę błędu i wysypie się później na .json():

async function buggy() {
    // This URL returns 404, but fetch resolves anyway.
    const response = await fetch("https://jsonplaceholder.typicode.com/nope/999");
    const data = await response.json();    // might explode or return garbage
    console.log(data);
}

buggy();

Poprawka to samodzielne sprawdzenie response.ok i rzucenie błędu, jeśli serwer zwrócił status błędu:

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));

Przyzwyczaj się do pisania tego bloku if (!response.ok). Powinien się znaleźć w każdym opakowaniu fetch, które napiszesz.

Wysyłanie żądania POST

Domyślnie jest GET. Do wszystkiego innego przekaż drugi argument, obiekt opcji:

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();

Trzy rzeczy warte uwagi:

• method domyślnie ma wartość "GET". Ustaw ją jawnie dla POST, PUT, DELETE, PATCH.
• body przyjmuje string (albo FormData, Blob itd.): fetch nie zserializuje obiektów za ciebie. JSON.stringify(...) to twoje zadanie.
• Nagłówek Content-Type mówi serwerowi, jak parsować treść. Zapomnisz o nim, a większość serwerów potraktuje treść jak zwykły tekst.

Nagłówki, query stringi i inne opcje

Nagłówki to po prostu obiekt (albo instancja Headers). Query stringi budujesz sam, zwykle przez 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 zajmuje się kodowaniem za ciebie (spacje, znaki &, unicode), więc nie skończysz z zepsutymi adresami URL, gdy dane wejściowe zawierają znaki wymagające escapowania.

Inne opcje, które zobaczysz w prawdziwym kodzie: credentials: "include", żeby wysyłać ciasteczka między domenami, cache: "no-store", żeby ominąć cache HTTP, mode: "cors" (zwykle domyślne) do sterowania zachowaniem CORS.

Anulowanie żądania przez AbortController

Czasem chcesz zrezygnować: użytkownik wpisał nowe zapytanie wyszukiwania albo żądanie trwa za długo. Służy do tego 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() sprawia, że obietnica fetch zostaje odrzucona z DOMException, którego name to "AbortError". Blok finally czyści timeout, żeby udane żądanie nie zostawiało wiszącego timera.

Ten wzorzec, czyli fetch z timeoutem i sprzątaniem, warto opakować w funkcję pomocniczą i używać wszędzie.

Opakowanie wielokrotnego użytku

Połącz to wszystko, a dostaniesz małą funkcję pomocniczą, która raz na zawsze załatwia szablonowy kod:

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;   // No Content
    return response.json();
}

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

Jedno miejsce do zmiany nagłówków, jedno do obsługi błędów, jedno do radzenia sobie z pustymi odpowiedziami. Każda nietrywialna aplikacja w końcu ma coś takiego.

Dalej: obsługa błędów w kodzie asynchronicznym

Fetch to jedno z najczęstszych miejsc, w których wychodzą błędy asynchroniczne, a sprawdzenie response.ok to tylko jeden element układanki. Następna strona dotyczy obsługi błędów w obietnicach i async/await: dokąd trafiają błędy, jak je łapać i jakie pułapki pozwalają im po cichu się prześlizgnąć.