Die meisten modernen Web-Apps kommunizieren ständig mit einem Server. Die JavaScript Fetch API ist die Standardmethode dafür und sie ist in Browser und in Node.js 18 und höher integriert, sodass nichts installiert werden muss.

Die grundlegende Verwendung dauert zwei Zeilen, doch viele Tutorials hören hier auf und lassen den Teil weg, der echte Fehler verursacht: die Fehlerbehandlung. Wir haben die Beispiele in diesem Handbuch auf einem kleinen lokalen Server auf Node.js 24 getestet und die angezeigte Ausgabe stammt von diesem Lauf. example.com im Code steht für Ihre eigene API. Wenn Versprechen für Sie neu sind, beginnen Sie mit der Erklärung von JavaScript-Versprechen.

Was ist die Fetch-API?

Fetch ist eine Promise-basierte Schnittstelle zum Senden von HTTP-Anfragen. Es ersetzte das ältere, rückrufgesteuerte XMLHttpRequest, und viele Projekte verwenden es jetzt, anstatt eine Bibliothek für einfache Aufrufe hinzuzufügen.

Eine GET-Anfrage

Fetch führt standardmäßig eine GET-Anfrage durch. Es gibt zwei Schritte, und jeder benötigt await: Zuerst kommen die Antwortheader an, und dann lesen Sie den Text.

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

console.log(user);

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

Die beiden Schritte sind vorhanden, da der Textkörper möglicherweise groß ist und später als die Kopfzeilen eintrifft. In einem Browser-Skript benötigt die oberste Ebene await ein Modul, daher fügen Sie dieses normalerweise in eine async-Funktion ein. Sehen Sie sich unseren JavaScript-Async/Await-Leitfaden an.

Das Response-Objekt

Bevor Sie den Text lesen, können Sie sich die Antwort ansehen:

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

// 200 true application/json

Ein Körper kann nur einmal gelesen werden. Ein zweiter Aufruf von json() schlug in unserem Test fehl:

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

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

Wenn Sie es zweimal lesen müssen, rufen Sie zuerst response.clone() auf.

Die große Überraschung: Ein 404 wirft nicht

Das ist das Wichtigste in diesem Artikel. Wir haben einen Benutzer angefordert, der nicht existiert:

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

// 404 false

Es wurde keine Ausnahme ausgelöst. Was den Abruf betrifft, hat die Anfrage funktioniert: Der Server wurde erreicht und er hat geantwortet. Das Versprechen wird nur dann abgelehnt, wenn überhaupt keine brauchbare Antwort eintrifft, beispielsweise bei einem Netzwerkausfall. Code wie dieser hat also einen versteckten Fehler:

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
}

Sehen Sie sich unseren Spickzettel für HTTP-Statuscodes an, um zu sehen, was die einzelnen Codes bedeuten.

Ein wiederverwendbarer Helfer

Wiederholen Sie diese Prüfung nicht überall. Wickeln Sie es einmal ein:

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

Jetzt landen sowohl HTTP-Fehler als auch Netzwerkfehler im selben catch. Diese kleine Funktion lohnt sich in jedem Projekt. Eine echte Version könnte auch eine Fehlermeldung aus dem Antworttext lesen und eine 204 No Content-Antwort verarbeiten, die kein JSON zum Parsen hat.

POST-JSON-Daten

Übergeben Sie ein Optionsobjekt als zweites Argument. Für JSON müssen Sie zwei Dinge selbst tun: die Daten in einen String konvertieren und den Header festlegen.

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

Unser Testserver hat den empfangenen Inhaltstyp zurückgegeben und bestätigt, dass der Header angekommen ist. Das Vergessen dieses Headers ist eine häufige Ursache für verwirrende Serverfehler, da viele Frameworks JSON nur dann analysieren, wenn es deklariert wird. Um ein Formular oder Dateien hochzuladen, übergeben Sie ein FormData-Objekt als Textkörper und setzen Sie nicht Content-Type, da der Browser selbst einen Grenzwert hinzufügen muss.

Andere Methoden und Optionen

Wählen Sie zwischen REST und anderen API-Stilen? Unser Vergleich von REST vs. GraphQL zeigt, wie fetch jeweils zusammenpasst.

Abfragezeichenfolgen

Erstellen Sie Abfragezeichenfolgen nicht durch Zusammenfügen von Text, da diese durch Sonderzeichen unterbrochen werden. URLSearchParams übernimmt die Kodierung für Sie:

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

Der Server hat red shoes korrekt empfangen und der Speicherplatz wurde wiederhergestellt.

Auszeiten und Absagen

Der Abruf wird auf einem langsamen Server lange warten, sofern Sie ihm nichts anderes mitteilen. AbortSignal.timeout() setzt eine Grenze. Unser Testendpunkt benötigte zwei Sekunden gegenüber einem Limit von 200 Millisekunden:

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

// TimeoutError

Um den Vorgang manuell abzubrechen, beispielsweise wenn ein Benutzer eine Seite verlässt oder einen neuen Suchbegriff eingibt, verwenden Sie eine 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

Um mehrere Anfragen gleichzeitig auszuführen, verwenden Sie Promise.all, was viel schneller ist, als einzeln auf sie zu warten:

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

Jede Art von Misserfolg

Hier sehen Sie, wie die einzelnen Fehler in unserem Lauf aussahen und wie man sie voneinander unterscheiden kann:

Diese letzte Reihe ist in der Produktion üblich. Ein Proxy, der eine 502 zurückgibt, sendet häufig eine HTML-Fehlerseite. Wir haben dies reproduziert und res.json() hat eine SyntaxError geworfen. Wenn Sie response.ok vor dem Parsen überprüfen, melden Sie das eigentliche Problem und nicht einen verwirrenden Parse-Fehler.

CORS und Anmeldeinformationen

In einem Browser unterliegt eine Anfrage von einem Ursprung zu einem anderen CORS, den Cross-Origin-Ressourcenfreigaberegeln. Wenn Sie einen Fehler mit der Erwähnung von Access-Control-Allow-Origin sehen, gehört der Fix zum Server, der Ihre Site zulassen muss. In Ihrem JavaScript wird der Fehler nur als generisches Problem angezeigt TypeError. Suchen Sie daher in der Browserkonsole nach der tatsächlichen Ursache. Node.js erzwingt CORS nicht, daher kann eine Anfrage, die in einem Skript funktioniert, im Browser dennoch fehlschlagen.

Standardmäßig senden Browser bei Cross-Origin-Anfragen keine Cookies. Stellen Sie bei Bedarf credentials: "include" ein und stellen Sie sicher, dass der Server dies zulässt. Fügen Sie niemals geheime API-Schlüssel in Browser-JavaScript ein, da sie jeder lesen kann. Behalten Sie sie auf Ihrem Server.

Häufige Fehler

• Nicht überprüft response.ok. Fehlerantworten werden als Erfolg behandelt.
• Das Zweite vergessen await. response.json() gibt auch ein Versprechen zurück.
• Vergessen JSON.stringify. Ein Objekt weitergeben, während der Körper es sendet [object Object].
• Setzen von Content-Type mit FormData. Dadurch wird die Grenze überschritten, also lassen Sie es weg.
• Es gibt keine Zeitüberschreitung. Eine blockierte Anfrage kann dazu führen, dass der Spinner einer Seite auf unbestimmte Zeit läuft.
• JSON wird auf eine leere Antwort analysiert. A 204 hat keinen Text und json() wird ausgelöst.

Fazit

Das Abrufen ist einfach, wenn Sie sich an die Hauptregel erinnern: Eine Antwort ist nicht dasselbe wie ein Erfolg. Kopieren Sie den kleinen Helfer in Ihr Projekt, fügen Sie ein Timeout hinzu und testen Sie Ihre Fehlerpfade. Erstellen Sie im nächsten Schritt eine kleine Seite, die Daten von einer API lädt, eine klare Fehlermeldung anzeigt und es dem Benutzer ermöglicht, eine langsame Suche abzubrechen.

Häufige Fragen

Lerne weiter