← React / TypeScript

React / TypeScript · 21 / 24

Serverdaten mit TanStack Query und Abbruch

Du prüfst gecachte Daten und einen abgebrochenen HTTP-Aufruf gegen einen lokalen Testserver.

  • Groß
  • Anspruchsvoll
  • 90 min

Voraussetzungen: HTTP-Verträge und Laufzeitvalidierung, TypeScript: Generics und unterscheidbare Union-Typen

In diesem Tutorial
  1. Das Zustandsmodell verstehen
  2. Das Projekt starten
  3. Den Vertrag mit einem Test prüfen
  4. Fehler und technische Grenzen beobachten
  5. Die Übung umsetzen
  6. Die Musterlösung überprüfen
  7. Übung und Lösung
  8. Projektbezug und Quellen

Lernpaket herunterladen

Einrichtung und Prüfstand

Node.js ab 22.23 mit npm. Zusätzlich Python 3 für den gemeinsamen Prüfstart. Entpacke das Lernpaket in einen neuen Ordner und führe dort python3 run_checks.py aus. Das Skript kopiert die enthaltenen Dateien in einen temporären Lernordner. Dort prüft es zuerst das Beispiel und danach die mitgelieferte Lösung. Die Ausgangsdateien bleiben erhalten. Benötigte Pakete werden beim ersten Lauf aus dem Netz geladen.

Geprüft am 20.10.2026 unter Linux x86_64. Ein lokaler Server zählt Requests. Wiederholtes Lesen frischer Daten soll keinen zweiten Request erzeugen. Die Lösung invalidiert den Key und erwartet einen weiteren Request. Ein abgebrochener Aufruf darf keinen gültigen Datensatz in den Cache schreiben.

Serverdaten gehören zu einer adressierbaren Abfrage. Der Query-Key trennt unterschiedliche Ressourcen. Ein AbortSignal wirkt nur, wenn die Transportfunktion es tatsächlich verwendet. Die Tests starten einen lokalen HTTP-Server. Sie prüfen Antwortdaten und Wiederverwendung, statt nur einen Hook zu mocken.

Paketinhalt und einzelne Dateien

01Das Zustandsmodell verstehen

Ein Query-Key identifiziert Daten im Cache. staleTime beschreibt deren Frische. Der queryFn erhält ein AbortSignal und reicht es an fetch weiter. Erst dadurch kann eine abgebrochene Abfrage ihren laufenden Transport beenden.

src/App.tsx · typescriptDatei öffnen
import {
  QueryClient,
  QueryClientProvider,
  useQuery,
} from "@tanstack/react-query";
export async function loadVehicles(
  base: string,
  signal: AbortSignal,
): Promise<string[]> {
  const response = await fetch(base + "/vehicles", { signal });
  if (!response.ok) throw new Error(`HTTP ${response.status}`);
  const value: unknown = await response.json();
  if (!Array.isArray(value) || !value.every((x) => typeof x === "string"))
    throw new Error("Invalid vehicles");
  return value;
}
const client = new QueryClient({
  defaultOptions: { queries: { retry: false, staleTime: 60000 } },
});
function Vehicles() {
  const query = useQuery({
    queryKey: ["vehicles"],
    queryFn: ({ signal }) => loadVehicles("http://127.0.0.1:4107", signal),
  });
  if (query.isPending) return <p role="status">Loading</p>;
  if (query.isError) return <p role="alert">{query.error.message}</p>;
  return (
    <main>
      <h1>Vehicles</h1>
      <ul>
        {query.data.map((name) => (
          <li key={name}>{name}</li>
        ))}
      </ul>
      <button onClick={() => query.refetch()}>Refresh</button>
    </main>
  );
}
export default function App() {
  return (
    <QueryClientProvider client={client}>
      <Vehicles />
    </QueryClientProvider>
  );
}

02Das Projekt starten

Installiere die fest angegebenen Abhängigkeiten und starte npm run dev. Die Daten sind künstliche Lernwerte. Starte in einem zweiten Terminal node server.mjs. Nur dieser lokale Lernserver liefert die Fahrzeugliste.

package.json · jsonDatei öffnen
{
  "name": "appfabrik-learning",
  "private": true,
  "type": "module",
  "scripts": {
    "dev": "vite --host 127.0.0.1",
    "build": "tsc --noEmit && vite build",
    "test": "vitest run src"
  },
  "dependencies": {
    "react": "19.2.3",
    "react-dom": "19.2.3",
    "react-router-dom": "7.18.4",
    "@tanstack/react-query": "5.104.5"
  },
  "devDependencies": {
    "vite": "8.1.5",
    "typescript": "6.0.3",
    "@types/react": "19.2.14",
    "@types/react-dom": "19.2.3",
    "@types/node": "22.19.15",
    "vitest": "4.1.10",
    "@testing-library/react": "16.3.2",
    "@testing-library/user-event": "14.6.1",
    "jsdom": "29.1.1",
    "@playwright/test": "1.64.1"
  }
}

03Den Vertrag mit einem Test prüfen

Ein lokaler Server zählt Requests. Wiederholtes Lesen frischer Daten soll keinen zweiten Request erzeugen. Die Lösung invalidiert den Key und erwartet einen weiteren Request. Ein abgebrochener Aufruf darf keinen gültigen Datensatz in den Cache schreiben.

src/App.test.tsx · typescriptDatei öffnen
import { test, expect } from "vitest";
import { createServer } from "node:http";
import { once } from "node:events";
import { QueryClient } from "@tanstack/react-query";
import { loadVehicles } from "./App";
test("real HTTP response is cached and cancellation is propagated", async () => {
  let requests = 0;
  const server = createServer((req, res) => {
    requests++;
    res.setHeader("Content-Type", "application/json");
    res.end('["Family car"]');
  });
  server.listen(0, "127.0.0.1");
  await once(server, "listening");
  const address = server.address();
  if (!address || typeof address === "string") throw Error("No port");
  const base = `http://127.0.0.1:${address.port}`;
  const client = new QueryClient({
    defaultOptions: { queries: { retry: false, staleTime: 60000 } },
  });
  const query = {
    queryKey: ["vehicles"],
    queryFn: ({ signal }: { signal: AbortSignal }) =>
      loadVehicles(base, signal),
  };
  try {
    expect(await client.fetchQuery(query)).toEqual(["Family car"]);
    expect(await client.fetchQuery(query)).toEqual(["Family car"]);
    expect(requests).toBe(1);
    const controller = new AbortController();
    controller.abort();
    await expect(loadVehicles(base, controller.signal)).rejects.toThrow();
    expect(requests).toBe(1);
  } finally {
    client.clear();
    server.closeAllConnections();
    await new Promise<void>((resolve) => server.close(() => resolve()));
  }
});

test("an in-flight request observes cancellation", async () => {
  let arrived!: () => void;
  const seen = new Promise<void>((resolve) => {
    arrived = resolve;
  });
  const server = createServer(() => {
    arrived();
  });
  server.listen(0, "127.0.0.1");
  await once(server, "listening");
  const address = server.address();
  if (!address || typeof address === "string") throw Error("No port");
  const controller = new AbortController();
  const result = loadVehicles(
    `http://127.0.0.1:${address.port}`,
    controller.signal,
  ).then(
    () => "unexpected success",
    (error) => error.name,
  );
  try {
    await seen;
    controller.abort();
    expect(await result).toBe("AbortError");
  } finally {
    controller.abort();
    server.closeAllConnections();
    await new Promise<void>((resolve) => server.close(() => resolve()));
  }
});

Starten / prüfen

npm install
npm test
npm run build
Erwartetes Ergebnis

Ein lokaler Server zählt Requests. Wiederholtes Lesen frischer Daten soll keinen zweiten Request erzeugen. Die Lösung invalidiert den Key und erwartet einen weiteren Request. Ein abgebrochener Aufruf darf keinen gültigen Datensatz in den Cache schreiben.

04Fehler und technische Grenzen beobachten

Ändere die erwartete Ausgabe und beobachte einen fehlgeschlagenen Test. Ein TypeScript-Build schützt Typverträge, ein Browsertest schützt Interaktionen. Beide Prüfarten erfüllen unterschiedliche Aufgaben.

05Die Übung umsetzen

Invalidiere den Query-Key und prüfe, dass danach ein neuer HTTP-Aufruf erfolgt.

06Die Musterlösung überprüfen

Die Invalidierung markiert den Wert als veraltet. Der nächste fetchQuery-Aufruf liest neu. Der Lösungstest prüft sowohl den Inhalt als auch die Zahl der tatsächlich empfangenen Requests. Kopiere die Lösungsdateien an die entsprechenden Stellen im Lernprojekt und starte Tests und Build erneut.

Erwartetes Ergebnis

Tests und Typprüfung bestehen. Das beobachtete Ergebnis entspricht dem Lernziel.

Deine Übung

Invalidiere den Query-Key und prüfe, dass danach ein neuer HTTP-Aufruf erfolgt.

Lösung mit Erklärung anzeigen

Die Invalidierung markiert den Wert als veraltet. Der nächste fetchQuery-Aufruf liest neu. Der Lösungstest prüft sowohl den Inhalt als auch die Zahl der tatsächlich empfangenen Requests.

solution/App.test.tsx · typescriptDatei öffnen
import { test, expect } from "vitest";
import { createServer } from "node:http";
import { once } from "node:events";
import { QueryClient } from "@tanstack/react-query";
import { loadVehicles } from "./App";
test("real HTTP response is cached and cancellation is propagated", async () => {
  let requests = 0;
  const server = createServer((req, res) => {
    requests++;
    res.setHeader("Content-Type", "application/json");
    res.end('["Family car"]');
  });
  server.listen(0, "127.0.0.1");
  await once(server, "listening");
  const address = server.address();
  if (!address || typeof address === "string") throw Error("No port");
  const base = `http://127.0.0.1:${address.port}`;
  const client = new QueryClient({
    defaultOptions: { queries: { retry: false, staleTime: 60000 } },
  });
  const query = {
    queryKey: ["vehicles"],
    queryFn: ({ signal }: { signal: AbortSignal }) =>
      loadVehicles(base, signal),
  };
  try {
    expect(await client.fetchQuery(query)).toEqual(["Family car"]);
    expect(await client.fetchQuery(query)).toEqual(["Family car"]);
    expect(requests).toBe(1);
    const controller = new AbortController();
    controller.abort();
    await expect(loadVehicles(base, controller.signal)).rejects.toThrow();
    expect(requests).toBe(1);
    await client.invalidateQueries({ queryKey: ["vehicles"] });
    await client.fetchQuery(query);
    expect(requests).toBe(2);
  } finally {
    client.clear();
    server.closeAllConnections();
    await new Promise<void>((resolve) => server.close(() => resolve()));
  }
});

test("an in-flight request observes cancellation", async () => {
  let arrived!: () => void;
  const seen = new Promise<void>((resolve) => {
    arrived = resolve;
  });
  const server = createServer(() => {
    arrived();
  });
  server.listen(0, "127.0.0.1");
  await once(server, "listening");
  const address = server.address();
  if (!address || typeof address === "string") throw Error("No port");
  const controller = new AbortController();
  const result = loadVehicles(
    `http://127.0.0.1:${address.port}`,
    controller.signal,
  ).then(
    () => "unexpected success",
    (error) => error.name,
  );
  try {
    await seen;
    controller.abort();
    expect(await result).toBe("AbortError");
  } finally {
    controller.abort();
    server.closeAllConnections();
    await new Promise<void>((resolve) => server.close(() => resolve()));
  }
});

Projektbezug und Quellen

Das eigenständige Lernprojekt vertieft ein Thema aus diesem Technologiebereich. Die Projektverweise zeigen einen festgehaltenen Quellstand als Architekturkontext. Sie sind kein Beleg dafür, dass jede hier neu eingeführte Bibliothek oder Funktion bereits in dieser App verwendet wird.