Większość nowoczesnych aplikacji internetowych cały czas komunikuje się z serwerem. JavaScript Fetch API to standardowy sposób, aby to zrobić, i jest wbudowany w przeglądarki oraz w Node.js 18 i nowsze, więc nie trzeba nic instalować.

Podstawowe użycie zajmuje dwie linijki, ale wiele samouczków kończy się na tym i pomija część, która powoduje prawdziwe błędy: obsługę awarii. Przetestowaliśmy przykłady w tym przewodniku na małym serwerze lokalnym w Node.js 24 i pokazane dane wyjściowe pochodzą z tego uruchomienia. example.com w kodzie oznacza Twój własny interfejs API. Jeśli obietnice są dla Ciebie nowością, zacznij od wyjaśnienia obietnic JavaScript.

Co to jest API pobierania?

Fetch to oparty na obietnicach interfejs umożliwiający wysyłanie żądań HTTP. Zastąpił on starszy, oparty na wywołaniach zwrotnych XMLHttpRequest i wiele projektów używa go obecnie zamiast dodawać bibliotekę do prostych wywołań.

Żądanie GET

Fetch domyślnie wysyła żądanie GET. Są dwa kroki i każdy z nich wymaga await: najpierw przychodzą nagłówki odpowiedzi, a następnie czytasz treść.

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

console.log(user);

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

Te dwa kroki istnieją, ponieważ treść może być duża i pojawiać się później niż nagłówki. W skrypcie przeglądarki najwyższy poziom await potrzebuje modułu, więc zazwyczaj umieszcza się go w funkcji async. Zobacz nasz przewodnik po asynchronizacji/oczekiwaniu JavaScript.

Obiekt odpowiedzi

Zanim przeczytasz treść, możesz sprawdzić odpowiedź:

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

// 200 true application/json

Ciało można odczytać tylko raz. Wywołanie json() po raz drugi nie powiodło się w naszym teście:

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

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

Jeśli chcesz przeczytać to dwa razy, najpierw zadzwoń do response.clone().

Wielka niespodzianka: 404 nie rzuca

To najważniejsza rzecz w tym artykule. Zażądaliśmy użytkownika, który nie istnieje:

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

// 404 false

Nie zgłoszono żadnego wyjątku. Jeśli chodzi o pobieranie, żądanie zadziałało: osiągnięto serwer i odpowiedział. Obietnica zostaje odrzucona tylko wtedy, gdy nie nadchodzi żadna użyteczna odpowiedź, jak w przypadku awarii sieci. Zatem taki kod ma ukryty błąd:

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
}

Sprawdź naszą ściągawkę dotyczącą kodów stanu HTTP, aby zobaczyć, co oznacza każdy kod.

Pomocnik wielokrotnego użytku

Nie powtarzaj tej kontroli wszędzie. Zawiń raz:

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

Teraz zarówno błędy HTTP, jak i błędy sieciowe kończą się w tym samym catch. Tę małą funkcję warto mieć w każdym projekcie. Prawdziwa wersja może również odczytać komunikat o błędzie z treści odpowiedzi i obsłużyć odpowiedź 204 No Content, która nie zawiera kodu JSON do przeanalizowania.

POST danych JSON

Przekaż obiekt opcji jako drugi argument. W przypadku JSON musisz sam zrobić dwie rzeczy: przekonwertować dane na ciąg znaków i ustawić nagłówek.

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' }

Nasz serwer testowy powtórzył otrzymany typ zawartości, potwierdzając otrzymanie nagłówka. Zapomnienie o tym nagłówku jest częstą przyczyną mylących błędów serwera, ponieważ wiele frameworków analizuje JSON tylko wtedy, gdy jest on zadeklarowany. Aby przesłać formularz lub pliki, przekaż obiekt FormData jako treść i nie ustawiaj Content-Type, ponieważ przeglądarka sama musi dodać wartość graniczną.

Inne metody i opcje

Wybierasz pomiędzy REST a innymi stylami API? Nasze porównanie REST vs GraphQL pokazuje, jak fetch pasuje do każdego z nich.

Ciągi zapytań

Nie twórz ciągów zapytań poprzez łączenie tekstu, ponieważ znaki specjalne spowodują ich przerwanie. URLSearchParams obsługuje kodowanie za Ciebie:

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' }

Serwer odebrał red shoes poprawnie, z przywróconą przestrzenią.

Limity czasu i anulowanie

Fetch będzie długo czekać na wolnym serwerze, chyba że powiesz inaczej. AbortSignal.timeout() ustala limit. Nasz testowy punkt końcowy zajął dwie sekundy przy limicie 200 milisekund:

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

// TimeoutError

Aby anulować ręcznie, na przykład gdy użytkownik opuszcza stronę lub wpisuje nowe wyszukiwane hasło, użyj 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

Aby uruchomić kilka żądań jednocześnie, użyj Promise.all, co jest znacznie szybsze niż oczekiwanie na nie pojedynczo:

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

Każdy rodzaj porażki

Oto, jak wyglądała każda porażka w naszym biegu, wraz z tym, jak je odróżnić:

Ten ostatni rząd jest powszechny w produkcji. Serwer proxy zwracający błąd 502 często wysyła stronę błędu HTML. Odtworzyliśmy to i res.json() rzuciło SyntaxError. Sprawdzenie response.ok przed analizą oznacza, że ​​zgłaszasz prawdziwy problem, a nie mylący błąd analizy.

CORS i poświadczenia

W przeglądarce żądanie z jednego źródła do drugiego podlega CORS, zasadom udostępniania zasobów między źródłami. Jeśli zobaczysz błąd wskazujący Access-Control-Allow-Origin, poprawka należy do serwera, który musi zezwalać na Twoją witrynę. W JavaScript awaria pojawia się tylko jako ogólna TypeError, więc spójrz na konsolę przeglądarki, aby poznać rzeczywisty powód. Node.js nie wymusza CORS, więc żądanie działające w skrypcie może nadal zakończyć się niepowodzeniem w przeglądarce.

Domyślnie przeglądarki nie wysyłają plików cookie w przypadku żądań pochodzących z różnych źródeł. Ustaw credentials: "include", jeśli ich potrzebujesz i upewnij się, że serwer na to pozwala. Nigdy nie umieszczaj tajnych kluczy API w JavaScript przeglądarki, ponieważ każdy może je odczytać. Trzymaj je na swoim serwerze.

Typowe błędy

• Nie sprawdzam. response.ok. Odpowiedzi na błędy są traktowane jako pomyślne.
• Zapomnienie o drugim await. response.json() również zwraca obietnicę.
• Zapominanie JSON.stringify. Przekazywanie obiektu w miarę wysyłania go przez ciało [object Object].
• Ustawienie Content-Type z FormData. To przerywa granicę, więc ją pomiń.
• Bez limitu czasu. Zawieszone żądanie może spowodować, że spinner strony będzie działał przez czas nieokreślony.
• Przetwarzanie JSON pod kątem pustej odpowiedzi. Liczba 204 nie ma treści i json() wyrzuci.

Podsumowanie

Pobieranie jest proste, jeśli pamiętasz jego główną zasadę: odpowiedź nie jest tym samym, co sukces. Skopiuj małego pomocnika do swojego projektu, dodaj limit czasu i przetestuj ścieżki błędów. Następnym krokiem będzie zbudowanie małej strony, która ładuje dane z API, wyświetla wyraźny komunikat o błędzie i pozwala użytkownikowi anulować powolne wyszukiwanie.

Najczęstsze pytania

Ucz się dalej