Skip to content

8. Kommunikation mit dem Server

Die Beispiele in diesem Kapitel fragen den JSON-Server von [RdvMedecins] ab: Er muss laufen ([npm run start:dev] im Ordner [rdvmedecins-nestjs-json]) auf Port 8080, gleichzeitig mit dem Entwicklungsserver [Vite] auf Port 5173.

8.1. Beispiel 22: Eine erste HTTP-Anfrage

8.1.1. Der Proxy des Entwicklungsservers

Die Seite dieses Beispiels stammt von http://localhost:5173 (dem Entwicklungsserver [Vite]); die API befindet sich unter http://localhost:8080. Für einen Browser sind dies zwei verschiedene Ursprünge (der Port ist Teil des Ursprungs). Aus Sicherheitsgründen erlaubt ein Browser einer Seite jedoch nicht, Antworten eines anderen Ursprungs zu lesen, es sei denn, der Server erlaubt dies ausdrücklich (der Mechanismus namens CORS). Und eine Anfrage an einen anderen Ursprung enthält keine Cookies (und damit auch nicht das Token), es sei denn, der Code verlangt es ([credentials: 'include']) UND der Server akzeptiert dies, wiederum über CORS.

Anstatt den Server für andere Ursprünge zu öffnen, leiten wir die API-Anfragen über den Entwicklungsserver [Vite] um. Das ist der Proxy , der in der Datei [vite.config.ts] der Beispiele deklariert ist (siehe Beispiel 01):

1
2
3
    proxy: {
      '/api': 'http://localhost:8080',
    },

Der Browser sendet eine Anfrage an [GET http://localhost:5173/api/captcha]; der Entwicklungsserver leitet die Anfrage an [http://localhost:8080/api/captcha] weiter und schickt die Antwort dann an den Browser zurück. Aus Sicht des Browsers haben die Seite und die API denselben Ursprung:

Image

In der Produktion gibt es keinen Entwicklungsserver mehr: Der JSON-Server selbst liefert die kompilierten Client-Dateien aus (siehe Kapitel „Deployment“). Seite und API haben weiterhin denselben Ursprung.

8.1.2. Die Anfrage

[React] hat keinen eigenen HTTP-Client: Es wird die Funktion [fetch] des Browsers oder eine Bibliothek ([axios] ...) verwendet. [fetch] ist mehr als ausreichend.

// =========================================================================
// 22-fetch/src/App.tsx - eine erste HTTP-Anfrage an den Server
// -------------------------------------------------------------------------
// Der JSON-Server von RdvMedecins muss gestartet sein (Port 8080). Wir fragen ihn nach
// einem CAPTCHA: GET /api/captcha -> { "id": "...", "svg": "<svg ...>" }.
//
//   - fetch(url): die Browserfunktion, die eine HTTP-Anfrage sendet.
//     Sie liefert ein PROMISE der Antwort; response.json() ein Promise
//     des aus JSON umgewandelten Bodys. React hat keinen eigenen HTTP-Client;
//   - die Adresse ist RELATIV (/api/captcha): Die Anfrage geht an den
//     Server der Seite, den von Vite (Port 5173), der sie dank seines Proxys an den
//     JSON-Server (Port 8080) weiterreicht (vgl. vite.config.ts);
//   - drei anzuzeigende Zustände: in Bearbeitung, erfolgreich, fehlgeschlagen.
// =========================================================================

import { useEffect, useState } from 'react';

// was GET /api/captcha zurückliefert
interface Captcha {
  id: string;
  svg: string;
}

const captchaStyle = { display: 'inline-block', border: '1px solid #dee2e6', borderRadius: '0.375rem' };

export default function App() {
  const [captcha, setCaptcha] = useState<Captcha | null>(null);
  const [loading, setLoading] = useState(true);
  const [error, setError] = useState<string | null>(null);
  const [requestCount, setRequestCount] = useState(0);
  // jeder Klick auf "Another image" ändert diese Zahl, wodurch der Effekt neu gestartet wird
  const [demand, setDemand] = useState(0);

  useEffect(() => {
    // AbortController: das Mittel, um eine laufende Anfrage ABZUBRECHEN
    const cancellation = new AbortController();
    setLoading(true);
    setError(null);
    fetch('/api/captcha', { signal: cancellation.signal })
      .then(async (response) => {
        // fetch weist eine Fehlerantwort (4xx, 5xx) NICHT zurück: ok wird geprüft
        if (!response.ok) {
          throw new Error(`the server answered ${response.status} ${response.statusText}`);
        }
        const c = (await response.json()) as Captcha;
        setCaptcha(c);
        setRequestCount((n) => n + 1);
        setLoading(false);
      })
      .catch((e: Error) => {
        if (e.name === 'AbortError') return; // Anfrage abgebrochen: nichts anzuzeigen
        setError(e.message);
        setCaptcha(null);
        setLoading(false);
      });
    // das Cleanup BRICHT die Anfrage ab, wenn der Effekt neu gestartet wird oder wenn die
    // Komponente vor der Antwort verschwindet. In der Entwicklung führt StrictMode
    // den Effekt beim Start zweimal aus: Die erste Anfrage wird
    // abgebrochen (Tab Network: "canceled"), nur die zweite zählt.
    return () => cancellation.abort();
  }, [demand]);

  return (
    <div className="container py-4" style={{ maxWidth: 640 }}>
      <h1 className="h3 mb-3">Example 22 - a first HTTP request</h1>
      <div className="card p-3">
        {loading && <p className="text-muted">Loading...</p>}
        {error && (
          <div className="alert alert-danger mb-3">
            Unable to get a captcha: {error}.<br />
            Is the RdvMedecins JSON server started (port 8080)?
          </div>
        )}
        {captcha && !loading && (
          <>
            {/* dangerouslySetInnerHTML: eine Zeichenkette als HTML einfügen */}
            <div className="mb-2"><div style={captchaStyle} dangerouslySetInnerHTML={{ __html: captcha.svg }} /></div>
            <p className="small text-muted">id: <code>{captcha.id}</code></p>
          </>
        )}
        <button className="btn btn-primary align-self-start" disabled={loading} onClick={() => setDemand((d) => d + 1)}>
          Another image
        </button>
        <p className="small text-muted mt-2 mb-0">
          {requestCount} successful request(s) - open the Network tab of the developer tools (F12).
        </p>
      </div>
    </div>
  );
}
  • Zeilen 19–22: was [GET /api/captcha] zurückgibt;
  • Zeilen 27–30: drei anzuzeigende Zustände: in Bearbeitung, erfolgreich (das CAPTCHA), Fehler;
  • Zeile 32: eine Anfragenummer: Jeder Klick auf „Another image“ erhöht sie, wodurch der Effekt erneut ausgelöst wird;
  • Zeilen 34–61: Die Anfrage ist ein Effekt: Er synchronisiert die Komponente mit dem Server, bei der ersten Anzeige und danach bei jeder neuen Anfrage:
    • Zeile 36: Ein [AbortController] ermöglicht es, eine ausstehende Anfrage abzubrechen: Sein [signal] wird an [fetch] übergeben;
    • Zeile 39: [fetch(url)] sendet eine Anfrage (GET) und gibt ein Promise für die Antwort zurück. Die Adresse ist RELATIV: Die Anfrage wird an den Server der Seite gesendet, [Vite], der sie an den JSON-Server weiterleitet;
    • Zeilen 42–44: ACHTUNG: [fetch] weist das Promise NICHT ab, wenn es eine Fehlerantwort (4xx, 5xx) erhält; sein Promise wird nur abgewiesen, wenn KEINE Antwort eintrifft (Netzausfall). Daher wird [response.ok] geprüft (true bei einem 2xx-Code);
    • Zeile 45: [response.json()] liest den Body und wandelt ihn aus JSON um (ein weiteres Promise). [as Captcha]: Wir teilen [TypeScript] das Format der empfangenen Daten mit; es kann dies nicht überprüfen;
    • Zeilen 50–55: ein Fehler; [AbortError]: Die Anfrage wurde abgebrochen; es gibt nichts anzuzeigen;
    • Zeile 60: Das Cleanup BRICHT die Anfrage ab, wenn der Effekt erneut ausgelöst wird oder die Komponente vor der Antwort verschwindet. In der Entwicklung führt [<StrictMode>] den Effekt beim Start zweimal aus: Die erste Anfrage wird abgebrochen (die Registerkarte Network zeigt sie als „canceled“); nur die zweite zählt;
  • Zeile 77: Das Bild ist ein SVG-Fragment, ein String, der wie HTML eingefügt wird. [{captcha.svg}] würde den Text [<svg ...>] maskiert anzeigen. [dangerouslySetInnerHTML] fügt den String unverändert ein: Sein Name warnt vor der Gefahr. Verwenden Sie es NUR für sichere Inhalte: Dieses SVG wird von UNSEREM Server erzeugt. Bei Benutzereingaben würde es der Skript-Injektion Tür und Tor öffnen;
  • Zeile 81: eine neue Anfrage; der Effekt wird erneut ausgelöst.

Image

Wenn der JSON-Server nicht läuft, liefert der Proxy von [Vite] einen 500-Fehler: „Unable to get a captcha: the server answered 500 Internal Server Error.“

// =========================================================================
// 23-login/src/App.tsx - Anmeldung am RdvMedecins-Server
// -------------------------------------------------------------------------
//   1. beim Start: GET /api/auth/me - sind wir bereits angemeldet?
//      (nach einem F5 hat der Client alles vergessen; der Server liest das Cookie);
//   2. Login: POST /api/auth/login, JSON-Body { login, password,
//      captchaId, captcha }. Bei Erfolg setzt der Server das httpOnly-Cookie
//      des JWT-Tokens: Unser Code sieht es NIE (versuchen Sie
//      document.cookie in der Konsole: Es ist nicht da);
//   3. geschützte Anfrage: GET /api/doctors. Der Browser hängt das Cookie
//      von selbst an (gleicher Origin);
//   4. Logout: POST /api/auth/logout - der Server löscht das Cookie.
//
// Das Formular verwendet die ACTIONS von React 19: <form action={function}>.
// Statt onSubmit und jedes Feld zu behandeln, erhalten wir alle Werte
// des Formulars (FormData), und useActionState behält das Ergebnis der
// letzten Action (hier eine Fehlermeldung) und zeigt an, ob sie gerade läuft.
//
// Ein Cookie gehört zu einem Host (localhost) und zu einem Pfad (/api): Es
// ist daher allen Beispielen GEMEINSAM. Ist man hier einmal angemeldet, sind es die Beispiele
// 24 und 25 ebenfalls.
// =========================================================================

import { useActionState, useEffect, useState } from 'react';
import { useFormStatus } from 'react-dom';

interface User {
  login: string;
  name: string;
  role: 'ADMIN' | 'DOCTOR' | 'USER';
}
interface Doctor {
  id: number;
  title: string;
  firstName: string;
  lastName: string;
}
interface Captcha {
  id: string;
  svg: string;
}
// die Form ALLER Fehler der API
interface ApiError {
  statusCode: number;
  key: string;
  params?: Record<string, string>;
}

// die wenigen Meldungen, die dieses Beispiel braucht (Beispiel 25 verwendet i18next)
const MESSAGES: Record<string, string> = {
  'LOGIN.ERROR': 'Incorrect login or password.',
  'ERRORS.WRONG_CAPTCHA': 'The characters you typed do not match the image.',
  'ERRORS.TOO_MANY_ATTEMPTS': 'Too many failed attempts. Try again later.',
};

// eine GET-Anfrage, deren JSON-Antwort typisiert ist; ein Fehler, wenn sie nicht 2xx ist
async function read<T>(url: string): Promise<T> {
  const response = await fetch(url);
  if (!response.ok) {
    throw response; // die Antwort selbst wird „geworfen“: Ihr Status sagt, was zu tun ist
  }
  return (await response.json()) as T;
}

// der Submit-Button: useFormStatus() zeigt an, ob das Formular, das ihn ENTHÄLT,
// gerade gesendet wird (es muss daher eine eigene Komponente sein, die darin platziert ist)
function LoginButton() {
  const { pending } = useFormStatus();
  return <button className="btn btn-primary" disabled={pending}>{pending ? 'Logging in...' : 'Log in'}</button>;
}

// das Ergebnis des letzten Anmeldeversuchs
interface LoginState {
  error: string | null;
  login: string; // das eingegebene Login, um es erneut anzuzeigen
}

export default function App() {
  const [user, setUser] = useState<User | null>(null);
  const [doctors, setDoctors] = useState<Doctor[]>([]);
  const [captcha, setCaptcha] = useState<Captcha | null>(null);
  const [ready, setReady] = useState(false); // ist die anfängliche Prüfung beendet?
  const [serverError, setServerError] = useState<string | null>(null);

  async function loadCaptcha() {
    setCaptcha(await read<Captcha>('/api/captcha'));
  }

  async function loadDoctors() {
    setDoctors(await read<Doctor[]>('/api/doctors'));
  }

  // 1. wer ist angemeldet? 200 -> der Benutzer; 401 -> niemand
  useEffect(() => {
    async function checkSession() {
      try {
        setUser(await read<User>('/api/auth/me'));
        await loadDoctors();
      } catch (e) {
        if (!(e instanceof Response) || e.status !== 401) {
          setServerError('Is the RdvMedecins JSON server started (port 8080)?');
        } else {
          await loadCaptcha();
        }
      }
      setReady(true);
    }
    checkSession();
  }, []);

  // 2. das Login: eine ACTION, die den vorherigen Zustand und die
  // Daten des Formulars erhält und den neuen Zustand zurückliefert
  async function logIn(_previous: LoginState, data: FormData): Promise<LoginState> {
    const login = String(data.get('login'));
    const response = await fetch('/api/auth/login', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' }, // der Body ist JSON
      body: JSON.stringify({ login, password: data.get('password'), captchaId: captcha?.id, captcha: data.get('captcha') }),
    });
    if (!response.ok) {
      // der JSON-Body der Fehlerantwort
      const error = (await response.json().catch(() => null)) as ApiError | null;
      const key = error?.key ?? 'ERRORS.SERVER_UNREACHABLE';
      await loadCaptcha(); // jedes Bild wird nur einmal verwendet
      return { error: `${response.status} - ${MESSAGES[key] ?? key}`, login };
    }
    setUser((await response.json()) as User);
    await loadDoctors();
    return { error: null, login };
  }
  const [state, loginAction] = useActionState(logIn, { error: null, login: 'admin' });

  // 4. der Logout
  async function logOut() {
    await fetch('/api/auth/logout', { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: '{}' });
    setUser(null);
    setDoctors([]);
    await loadCaptcha();
  }

  let content;
  if (!ready) {
    content = <p className="text-muted">Checking the session...</p>;
  } else if (user) {
    // angemeldet
    content = (
      <div className="card p-3">
        <p>
          Logged in: <strong>{user.name}</strong> ({user.login}), role{' '}
          <span className="badge text-bg-primary">{user.role}</span>
        </p>
        <h2 className="h6">GET /api/doctors</h2>
        <ul>
          {doctors.map((m) => <li key={m.id}>{m.title} {m.firstName} {m.lastName}</li>)}
        </ul>
        <p className="small text-muted">Reload the page (F5): you remain logged in.</p>
        <button className="btn btn-outline-secondary align-self-start" onClick={logOut}>Log out</button>
      </div>
    );
  } else if (!serverError) {
    // nicht angemeldet: das Formular. Die Felder sind NICHT kontrolliert: name
    // bezeichnet sie in FormData; nach jeder Action setzt React sie auf
    // ihren Anfangswert zurück (defaultValue)
    content = (
      <form className="card p-3" action={loginAction}>
        <div className="mb-2">
          <label className="form-label" htmlFor="login">Login</label>
          <input id="login" name="login" className="form-control" autoComplete="username" defaultValue={state.login} />
        </div>
        <div className="mb-2">
          <label className="form-label" htmlFor="password">Password</label>
          <input id="password" name="password" type="password" className="form-control" autoComplete="current-password" />
        </div>
        <div className="mb-3">
          <label className="form-label" htmlFor="captcha">Type the characters of the image</label>
          <div className="d-flex align-items-center gap-3 mb-2">
            <div dangerouslySetInnerHTML={{ __html: captcha?.svg ?? '' }} />
            <button type="button" className="btn btn-link btn-sm" onClick={loadCaptcha}>Another image</button>
          </div>
          <input id="captcha" name="captcha" className="form-control" autoComplete="off" />
        </div>
        <LoginButton />
        <p className="small text-muted mt-2 mb-0">Accounts: admin, pelissier, martin... (password = login).</p>
        {state.error && <div className="alert alert-danger mt-3 mb-0">{state.error}</div>}
      </form>
    );
  }

  return (
    <div className="container py-4" style={{ maxWidth: 640 }}>
      <h1 className="h3 mb-3">Example 23 - logging in to the server</h1>
      {content}
      {serverError && <div className="alert alert-danger mt-3">{serverError}</div>}
    </div>
  );
}

Der Ablauf (Zeilen 4–12): Beim Start wird der Server abgefragt, um festzustellen, wer angemeldet ist; dann folgen die Anmeldung, eine gesicherte Anfrage und die Abmeldung.

  • Zeilen 27–47: einige API-Typen, darunter die Form ALLER Fehler;
  • Zeilen 50–54: die wenigen Meldungen, die dieses Beispiel zur Übersetzung der Schlüssel des Servers benötigt (Beispiel 25 wird [i18next] verwenden);
  • Zeilen 57–63: eine kleine generische Funktion für GET-Anfragen: die JSON-Antwort, mit einem Typ; und wenn es kein 2xx ist, „werfen“ wir die Antwort selbst: Ihr Status zeigt, was zu tun ist;
  • Zeilen 67–70: die Schaltfläche zum Absenden des Formulars. [useFormStatus()] (aus [react-dom]) zeigt an, ob das Formular, das sie ENTHÄLT, gerade abgesendet wird: Es muss sich also um eine separate Komponente handeln, die innerhalb des Formulars platziert ist;
  • Zeilen 94–109: Beim Start wird [GET /api/auth/me] aufgerufen: Sind wir bereits angemeldet? Nach einem F5 hat der Client alles vergessen; der Server hingegen liest das Cookie. 200: der Benutzer; 401: niemand (dann wird ein CAPTCHA geladen); alles andere: Der Server antwortet nicht. Eine [async]-Funktion kann nicht selbst der Effekt sein (ein Effekt gibt sein Cleanup zurück, kein Promise): Wir deklarieren sie innerhalb des Effekts und rufen sie dann auf;
  • Zeilen 113–130: die Anmeldung, geschrieben als Aktion von [React] 19 (siehe unten). Sie erhält den vorherigen Zustand und die Formulardaten ([FormData]) und gibt den neuen Zustand zurück:
    • Zeile 114: [data.get(name)] liest ein Feld des Formulars, identifiziert über sein Attribut [name];
    • Zeilen 115–119: [POST /api/auth/login], mit einem JSON-Body: [method], dem Header [Content-Type] und dem Body, erzeugt von [JSON.stringify]. Bei Erfolg setzt der Server das [httpOnly]-Cookie aus dem JWT-Token: Unser Code sieht es NIEMALS (versuchen Sie es mit [document.cookie] in der Konsole: Es ist nicht vorhanden);
    • Zeilen 120–126: ein Fehlschlag: Der Body der Fehlerantwort, JSON, liefert den Meldungsschlüssel; jedes CAPTCHA-Bild wird nur einmal verwendet: Ein anderes wird geladen;
    • Zeilen 127–129: ein Erfolg: der Benutzer, gefolgt von einer geschützten Anfrage, [GET /api/doctors]: Der Browser fügt das Cookie automatisch bei (gleicher Ursprung);
  • Zeile 131: [useActionState(action, initialState)] ([React] 19) liefert den Zustand, der von der letzten Ausführung der Aktion erzeugt wurde, und eine Version der Aktion, die an das Formular übergeben wird;
  • Zeilen 134–139: Abmeldung; [POST /api/auth/logout]: Der Server löscht das Cookie. Jeder POST muss einen JSON-Body haben (der Server lehnt andere ab; siehe das vorherige Kapitel): ['{}'];
  • Zeile 165: [<form action={function}>]: Ab [React] 19 kann das Attribut [action] eines Formulars eine Funktion akzeptieren. Beim Absenden [React] verhindert es, dass der Browser das Formular absendet, fasst die Felder in einem [FormData] zusammen und ruft die Funktion auf; während deren Ausführung [useFormStatus] „in Bearbeitung“ anzeigt. [onSubmit], [preventDefault] und ein Status pro Feld sind nicht mehr erforderlich;
  • Zeilen 168–180: Die Felder sind nicht kontrolliert: Sie werden über ihren [name] identifiziert. Nach jeder Aktion setzt [React] das Formular zurück: Jedes Feld kehrt zu seinem Anfangswert zurück ([defaultValue]). Die Felder für Passwort und CAPTCHA werden daher geleert; das Login-Feld kehrt zu dem Wert zurück, der von der Aktion im Zustand gespeichert wurde ([state.login]), also dem soeben eingegebenen;
  • Zeile 184: die Fehlermeldung, die von der letzten Aktion erzeugt wurde.

Ein Cookie gehört zu einem Rechner (localhost) und einem Pfad ([/api]): Es wird daher von ALLEN Beispielen geteilt. Sobald Sie sich hier angemeldet haben, sind auch die Beispiele 24 und 25 angemeldet.

Image

Ein falsches Passwort: Der Login bleibt erhalten, und ein neues Bild wird angezeigt:

Image

Angemeldet als [admin]; Sie können die Seite neu laden (F5): Sie bleiben angemeldet:

Image

8.3. Beispiel 24: Eine Zugriffsschicht für die API

Beispiel 23 wiederholte für jede Anfrage dieselben Schritte: das Präfix [/api], den JSON-Header, die Prüfung auf [response.ok], das Lesen des Fehler-Bodys ... Die Beispiele 24 und 25 fassen diese im Ordner [common/] zusammen, und die Fallstudie wird demselben Ansatz folgen.

8.3.1. Die Typen

// =========================================================================
// common/types.ts - die zwischen dem Client und der RdvMedecins-API ausgetauschten JSON-Objekte
// (vgl. Kapitel über die Blackbox, das jede Route beschreibt)
// =========================================================================

export type Role = 'ADMIN' | 'DOCTOR' | 'USER';

// POST /api/auth/login, GET /api/auth/me
export interface User {
  login: string;
  name: string;
  role: Role;
}

// GET /api/captcha
export interface Captcha {
  id: string;
  svg: string;
}

// ein Arzt oder ein Client (GET /api/doctors, GET /api/clients...)
export interface Person {
  id: number;
  version: number;
  title: string;
  firstName: string;
  lastName: string;
  login?: string; // nur für den ADMIN
}

export interface Identity {
  title: string;
  firstName: string;
  lastName: string;
}

// eine Zeile von GET /api/schedule
export interface ScheduleSlot {
  id: number;
  startHour: number;
  startMinute: number;
  endHour: number;
  endMinute: number;
  free: boolean;
  patient: Identity | null;
  mine: boolean;
  bookable: boolean;
  appointmentId: number | null;
}

// GET /api/schedule?doctorId=...&day=...
export interface Schedule {
  doctor: Person;
  day: string;
  slots: ScheduleSlot[];
  info: string | null;
}

Die Übersetzung der im vorherigen Kapitel beschriebenen API in [TypeScript]-Interfaces. Eine Zeile des Terminkalenders ([ScheduleSlot]) beschreibt ein Zeitfenster UND das, was der angemeldete Benutzer damit tun darf.

8.3.2. Fehler

// =========================================================================
// common/api-error.ts - EINE Klasse für alle Fehler der API
// -------------------------------------------------------------------------
// Alle Fehlerantworten des RdvMedecins-Servers haben dieselbe Form:
//   { "statusCode": 409, "key": "ERRORS.LOGIN_TAKEN", "params": {...}, "fields": {...} }
// Eine Anfrage kann aber auch ANDERS scheitern: gar keine Antwort
// (Netzwerk ausgefallen: fetch wirft einen TypeError) oder eine Antwort, die
// nicht von unserem Server stammt (eine Fehlerseite des Vite-Proxys, wenn der
// JSON-Server gestoppt ist). All das wird in EINE Klasse umgewandelt,
// ApiError, die den vom Server gesendeten Übersetzungsschlüssel trägt (und,
// falls vorhanden, dessen Parameter und den Fehler jedes Feldes).
// =========================================================================

export class ApiError extends Error {
  readonly statusCode: number; // 0: Der Server hat nicht geantwortet
  readonly key: string; // z. B.: 'ERRORS.LOGIN_TAKEN'
  readonly params: Record<string, string>;
  readonly fields: Record<string, string>;

  constructor(statusCode: number, key: string, params: Record<string, string> = {}, fields: Record<string, string> = {}) {
    super(key);
    this.name = 'ApiError';
    this.statusCode = statusCode;
    this.key = key;
    this.params = params;
    this.fields = fields;
  }
}

// eine Fehlerantwort (4xx, 5xx) -> ein ApiError
export async function fromResponse(response: Response): Promise<ApiError> {
  // der JSON-Body des Fehlers, falls vorhanden und von der richtigen Form
  let body: { key?: string; params?: Record<string, string>; fields?: Record<string, string> } = {};
  try {
    const json: unknown = await response.json();
    if (typeof json === 'object' && json !== null) {
      body = json;
    }
  } catch {
    // kein JSON: Es hat nicht unser Server geantwortet
  }
  // kein Schlüssel: Der Proxy oder das Netzwerk hat an seiner Stelle geantwortet
  const key = body.key ?? (response.status >= 500 ? 'ERRORS.SERVER_UNREACHABLE' : 'ERRORS.SERVER_ERROR');
  return new ApiError(response.status, key, body.params, body.fields);
}
  • Zeilen 14–28: EINE Klasse für alle API-Fehler: den HTTP-Status (0: keine Antwort), den vom Server gesendeten Übersetzungsschlüssel, seine Parameter und den Fehler zu jedem Feld eines abgelehnten Formulars. Sie erbt von [Error]: Sie kann geworfen ([throw]) und erkannt ([instanceof ApiError]) werden. Die „Property-Parameter“ von [TypeScript] ([constructor(public readonly key: string)]) werden nicht verwendet: Die Option [erasableSyntaxOnly] von [tsconfig.json] deaktiviert sie, weil sie Code erzeugen;
  • Zeilen 31–45: Eine Fehlerantwort wird zu einem [ApiError]. Der Body stammt nicht immer als JSON von unserem Server: Wenn der JSON-Server nicht läuft, antwortet der Proxy von [Vite] ohne JSON-Body. Kein Schlüssel: Ein Statuscode von 500 oder höher bedeutet „Server nicht erreichbar“.

8.3.3. Anfragen

// =========================================================================
// common/api.ts - Anfragen an die API, in einer Zeile
// -------------------------------------------------------------------------
// In Beispiel 23 wiederholte jede Anfrage dieselben Handgriffe: Präfix
// /api, JSON-Header, Test von response.ok, Lesen des Fehler-Bodys... Sie
// sind hier zusammengefasst:
//
//   const doctors = await api.get<Person[]>('/doctors');
//   await api.post('/appointments', { day, slotId, clientId });
//
//   - bei Erfolg liefert das Promise den JSON-Body, TYPISIERT;
//   - bei einem Fehler wird es mit einem ApiError ABGELEHNT.
// Alle Anfragen laufen über die Funktion request: Sie ist der Ort,
// an dem ein ihnen allen GEMEINSAMES Problem behandelt würde (vgl. die Fallstudie und die
// Antwort 401). Verwendet von den Beispielen 24 und 25.
// =========================================================================

import { fromResponse, ApiError } from './api-error';

export async function request<T>(method: string, url: string, body?: unknown): Promise<T> {
  let response: Response;
  try {
    response = await fetch(`/api${url}`, {
      method,
      // ein JSON-Body (der Server weist ein POST ab, das keinen hat)
      headers: body === undefined ? {} : { 'Content-Type': 'application/json' },
      body: body === undefined ? undefined : JSON.stringify(body),
    });
  } catch {
    // fetch hat KEINE Antwort erhalten (Netzwerk, Server gestoppt)
    throw new ApiError(0, 'ERRORS.SERVER_UNREACHABLE');
  }
  if (!response.ok) {
    throw await fromResponse(response);
  }
  return (await response.json()) as T;
}

export const api = {
  get: <T>(url: string) => request<T>('GET', url),
  // ein POST hat immer einen JSON-Body: standardmäßig {}
  post: <T>(url: string, body: unknown = {}) => request<T>('POST', url, body),
  put: <T>(url: string, body: unknown) => request<T>('PUT', url, body),
  delete: <T>(url: string, body?: unknown) => request<T>('DELETE', url, body),
};
  • Zeilen 20–37: ALLE Anfragen laufen über diese generische Funktion:
    • Zeilen 23–28: das Präfix [/api] und, falls ein Body vorhanden ist, der Header und JSON;
    • Zeilen 29–32: keine Antwort: ein [ApiError] mit Status 0;
    • Zeilen 33–35: eine Fehlerantwort: ein [ApiError];
    • Zeile 36: ein Erfolg: der Body, typisiert;
  • Zeilen 39–45: Abkürzungen, eine Funktion pro HTTP-Methode. Ein POST hat immer einen JSON-Body: standardmäßig [{}] .

Hier würde ein GEMEINSAMES Problem für alle Anfragen behandelt: Die Fallstudie wird hier die 401-Antwort (Sitzung abgelaufen) behandeln.

8.3.4. Eine Anmeldeleiste

// =========================================================================
// common/LoginBar.tsx - Login / Logout in einer Leiste
// -------------------------------------------------------------------------
// Das Formular aus Beispiel 23, auf eine Leiste reduziert und mit api.ts neu geschrieben.
// Die Komponente ruft onUserChange mit dem angemeldeten Benutzer (oder
// null) bei jeder Änderung auf - auch beim Start, nachdem
// GET /api/auth/me abgefragt wurde.
// =========================================================================

import { useEffect, useEffectEvent, useState, type FormEvent } from 'react';
import { api } from './api';
import { ApiError } from './api-error';
import type { Captcha, User } from './types';
import './LoginBar.css';

interface Props {
  onUserChange: (user: User | null) => void;
}

export default function LoginBar({ onUserChange }: Props) {
  const [user, setUser] = useState<User | null>(null);
  const [captcha, setCaptcha] = useState<Captcha | null>(null);
  const [login, setLogin] = useState('admin');
  const [password, setPassword] = useState('');
  const [captchaAnswer, setCaptchaAnswer] = useState('');
  const [error, setError] = useState<string | null>(null);

  function changeUser(u: User | null) {
    setUser(u);
    onUserChange(u);
  }

  async function newCaptcha() {
    setCaptcha(await api.get<Captcha>('/captcha'));
    setCaptchaAnswer('');
  }

  // beim Start: sind wir bereits angemeldet?
  const start = useEffectEvent(async () => {
    try {
      changeUser(await api.get<User>('/auth/me'));
    } catch {
      changeUser(null); // 401: Niemand ist angemeldet
      await newCaptcha().catch(() => setError('Is the JSON server started (port 8080)?'));
    }
  });
  useEffect(() => {
    start();
  }, []);

  async function logIn(e: FormEvent<HTMLFormElement>) {
    e.preventDefault();
    setError(null);
    try {
      const u = await api.post<User>('/auth/login', { login, password, captchaId: captcha?.id, captcha: captchaAnswer });
      setPassword('');
      changeUser(u);
    } catch (err) {
      setError(err instanceof ApiError ? `${err.statusCode} ${err.key}` : String(err));
      await newCaptcha();
    }
  }

  async function logOut() {
    await api.post('/auth/logout');
    changeUser(null);
    await newCaptcha();
  }

  return (
    <div className="alert alert-secondary d-flex flex-wrap align-items-center gap-2 py-2">
      {user ? (
        <>
          <span>
            Logged in: <strong>{user.name}</strong> <span className="badge text-bg-primary ms-1">{user.role}</span>
          </span>
          <button className="btn btn-sm btn-outline-secondary ms-auto" onClick={logOut}>Log out</button>
        </>
      ) : (
        <form className="d-flex flex-wrap align-items-center gap-2 w-100" onSubmit={logIn}>
          <input className="form-control form-control-sm w-auto" placeholder="login" autoComplete="username" value={login}
                 onChange={(e) => setLogin(e.target.value)} />
          <input type="password" className="form-control form-control-sm w-auto" placeholder="password"
                 autoComplete="current-password" value={password} onChange={(e) => setPassword(e.target.value)} />
          {/* das SVG-Bild des CAPTCHA, von UNSEREM Server erzeugt (vgl. Beispiel 22) */}
          <div className="captcha-bar" dangerouslySetInnerHTML={{ __html: captcha?.svg ?? '' }} />
          <input className="form-control form-control-sm w-auto" placeholder="captcha" autoComplete="off" size={8}
                 value={captchaAnswer} onChange={(e) => setCaptchaAnswer(e.target.value)} />
          <button className="btn btn-sm btn-primary">Log in</button>
          {error && <span className="text-danger small">{error}</span>}
        </form>
      )}
    </div>
  );
}

Das Formular aus Beispiel 23, auf eine Leiste reduziert und mit [api.ts] neu geschrieben (und zum Vergleich mit validierten Feldern):

  • Zeile 17: Die Komponente benachrichtigt ihr Elternelement, sobald sich der angemeldete Benutzer ändert;
  • Zeilen 39–46 und 47–49: Beim Start wird [GET /api/auth/me] aufgerufen. Die vom Effekt aufgerufene Funktion benachrichtigt das Elternelement: [useEffectEvent] vermeidet, dass sie zu einer Abhängigkeit wird (siehe Beispiel 13);
  • Zeile 55: eine einzeilige Anfrage; schlägt sie fehl, wird ein [ApiError] ausgelöst;
  • Zeile 86: das CAPTCHA-Bild, mithilfe eines kleinen Stylesheets auf die Höhe der Leiste skaliert:
1
2
3
4
5
6
7
8
/* das SVG-Bild des CAPTCHA, unverändert in die Seite eingefügt: Es wird verkleinert
   die Höhe der Leiste verkleinert. Ein importiertes Stylesheet gilt für die
   GANZE Seite: die Klasse .captcha-bar beschränkt es auf unser Element. */
.captcha-bar svg {
  display: block;
  height: 32px;
  width: auto;
}

8.3.5. Die Zugriffsschicht auf die API

// =========================================================================
// 24-api-layer/src/rdvmedecins.ts - die Zugriffsschicht auf die API
// -------------------------------------------------------------------------
// Eine typisierte Funktion pro Route der API. Die Komponenten kennen weder
// die URLs noch fetch noch das JSON-Format: Sie rufen Funktionen auf.
// Es ist das clientseitige Gegenstück zur DAO-Schicht auf der Server-Seite: Ändert sich die API
// (eine URL, ein Feldname), wird nur diese Datei geändert.
// =========================================================================

import { api } from '../../common/api';
import type { Schedule, Person } from '../../common/types';

export const rdvmedecins = {
  getDoctors: () => api.get<Person[]>('/doctors'),
  getClients: () => api.get<Person[]>('/clients'),
  // URLSearchParams erzeugt "doctorId=1&day=2030-01-15" und kodiert, was kodiert werden muss
  getSchedule: (doctorId: number, day: string) =>
    api.get<Schedule>(`/schedule?${new URLSearchParams({ doctorId: String(doctorId), day })}`),
  book: (day: string, slotId: number, clientId?: number) =>
    api.post<{ id: number }>('/appointments', { day, slotId, clientId }),
  cancelAppointment: (appointmentId: number) => api.delete<Record<string, never>>(`/appointments/${appointmentId}`),
};

Eine typisierte Funktion pro Route der API. Die Komponenten kennen weder URL, [fetch] noch das JSON-Format: Sie rufen Funktionen auf. Dies ist das clientseitige Gegenstück zur DAO-Schicht auf der Serverseite: Wenn sich die API ändert (eine URL, ein Feldname), wird nur diese Datei geändert. [URLSearchParams] (Zeile 18) erzeugt den Teil [doctorId=1&day=2030-01-15] einer Adresse, indem es die nötigen Daten kodiert.

8.3.6. TanStack Query

Daten von einem Server in einem Effekt zu lesen, wie in Beispiel 22, erfordert, sich um alles zu kümmern: den Status „in Bearbeitung“, Fehler, veraltete Antworten, Abbrüche, doppelt gesendete Anfragen und bereits empfangene Daten, die wiederverwendet werden könnten ... [TanStack Query] (früher [React Query]), die am weitesten verbreitete Bibliothek für diesen Zweck, übernimmt all dies.

// =========================================================================
// 24-api-layer/src/main.tsx
// -------------------------------------------------------------------------
// TanStack Query (früher React Query): die meistverwendete Bibliothek,
// um Daten eines Servers in einer React-Anwendung zu LESEN.
// Der QueryClient hält die bereits erhaltenen Antworten im Speicher (im „Cache“);
// <QueryClientProvider> stellt ihn der gesamten Anwendung bereit (ein Kontext,
// vgl. Beispiel 14).
// =========================================================================

import { StrictMode } from 'react';
import { createRoot } from 'react-dom/client';
import { QueryClient, QueryClientProvider } from '@tanstack/react-query';
import 'bootstrap/dist/css/bootstrap.min.css';
import App from './App';

const queryClient = new QueryClient({
  // bei einem Fehler kein neuer Versuch: Wir wollen den Fehler sehen
  defaultOptions: { queries: { retry: false } },
});

createRoot(document.getElementById('root')!).render(
  <StrictMode>
    <QueryClientProvider client={queryClient}>
      <App />
    </QueryClientProvider>
  </StrictMode>,
);
  • Zeile 17: der [TanStack Query]-Client, der zuvor empfangene Antworten im Speicher ablegt (im „Cache“); [retry: false]: Bei einem Fehlschlag gibt es keinen erneuten Versuch (standardmäßig werden drei unternommen);
  • Zeile 24: Er wird der gesamten Anwendung über einen Kontext bereitgestellt (siehe Beispiel 14).

8.3.7. Die Seite

// =========================================================================
// 24-api-layer/src/App.tsx - ein Terminkalender mit der Zugriffsschicht auf die API
// -------------------------------------------------------------------------
// Anmelden (obere Leiste), einen Arzt und einen Tag wählen: Der Terminkalender
// wird angezeigt. ADMIN und DOCTOR können für einen Patienten buchen und stornieren;
// ein Patient (martin...) bucht für sich selbst. Jede Aktion endet mit
// einem Neuladen des Terminkalenders: Der SERVER hat das letzte Wort.
//
// useQuery({ queryKey, queryFn }): ein LESEN von Daten, beschrieben durch
//   - queryFn: die Funktion, die sie holt (ein Promise);
//   - queryKey: was diese Daten IDENTIFIZIERT: ['schedule', doctorId, day].
// TanStack Query ruft queryFn zu Beginn auf, dann jedes Mal, wenn sich der Schlüssel
// ÄNDERT (anderer Arzt, anderer Tag). Es liefert ein Objekt: data (die
// Antwort), isPending, isFetching, error... und refetch() zum erneuten Lesen.
// Es übernimmt auch, was mit useEffect von Hand geschrieben werden müsste: eine veraltete
// Antwort verwerfen, dieselbe Anfrage nicht zweimal senden, die
// Antworten im Cache halten.
// =========================================================================

import { useState } from 'react';
import { useQuery } from '@tanstack/react-query';
import LoginBar from '../../common/LoginBar';
import { ApiError } from '../../common/api-error';
import type { ScheduleSlot, User } from '../../common/types';
import { rdvmedecins } from './rdvmedecins';

function tomorrow(): string {
  const d = new Date(Date.now() + 24 * 3600 * 1000);
  return `${d.getFullYear()}-${String(d.getMonth() + 1).padStart(2, '0')}-${String(d.getDate()).padStart(2, '0')}`;
}

function timeRange(c: ScheduleSlot): string {
  const hm = (h: number, m: number) => `${h}:${String(m).padStart(2, '0')}`;
  return `${hm(c.startHour, c.startMinute)} - ${hm(c.endHour, c.endMinute)}`;
}

// ein Fehler -> ein Text (sein Schlüssel, mangels Wörterbuch an dieser Stelle)
function errorText(e: unknown): string {
  return e instanceof ApiError ? `${e.statusCode} ${e.key}` : String(e);
}

export default function App() {
  const [user, setUser] = useState<User | null>(null);
  const [doctorId, setDoctorId] = useState<number | null>(null);
  const [day, setDay] = useState(tomorrow);
  const [clientId, setClientId] = useState<number | null>(null);
  const [message, setMessage] = useState<{ type: 'success' | 'danger'; text: string } | null>(null);

  const loggedIn = user !== null;
  const isManager = loggedIn && user.role !== 'USER';

  // die Ärzte, dann (ADMIN, DOCTOR) die Clients: neu gelesen, wenn
  // sich der Benutzer ändert (er ist Teil des Schlüssels)
  const doctors = useQuery({
    queryKey: ['doctors', user?.login],
    queryFn: rdvmedecins.getDoctors,
    enabled: loggedIn, // false: keine Anfrage (niemand angemeldet)
  });
  const clients = useQuery({
    queryKey: ['clients', user?.login],
    queryFn: rdvmedecins.getClients,
    enabled: isManager, // ein USER würde 403 erhalten
  });

  // der Terminkalender: Der Schlüssel enthält den Arzt und den Tag
  const schedule = useQuery({
    queryKey: ['schedule', doctorId, day, user?.login],
    queryFn: () => rdvmedecins.getSchedule(doctorId!, day),
    enabled: loggedIn && doctorId !== null,
  });

  // eine neue Wahl von Arzt oder Tag löscht die vorherige Meldung
  function chooseDoctor(id: number) {
    setDoctorId(id);
    setMessage(null);
  }
  function chooseDay(d: string) {
    setDay(d);
    setMessage(null);
  }

  async function book(c: ScheduleSlot) {
    try {
      await rdvmedecins.book(day, c.id, isManager ? (clientId ?? undefined) : undefined);
      setMessage({ type: 'success', text: `Slot ${timeRange(c)} booked.` });
    } catch (e) {
      setMessage({ type: 'danger', text: errorText(e) });
    }
    schedule.refetch();
  }

  async function cancel(c: ScheduleSlot) {
    try {
      await rdvmedecins.cancelAppointment(c.appointmentId!);
      setMessage({ type: 'success', text: `Appointment of ${timeRange(c)} cancelled.` });
    } catch (e) {
      setMessage({ type: 'danger', text: errorText(e) });
    }
    schedule.refetch();
  }

  const a = schedule.data;
  return (
    <div className="container py-4">
      <h1 className="h3 mb-3">Example 24 - an API access layer</h1>
      <LoginBar onUserChange={setUser} />

      {loggedIn && (
        <>
          <div className="row g-2 mb-3">
            <div className="col-sm-5">
              <select className="form-select" value={doctorId ?? ''} onChange={(e) => chooseDoctor(Number(e.target.value))}>
                <option value="" disabled>-- choose a doctor --</option>
                {doctors.data?.map((m) => <option key={m.id} value={m.id}>{m.title} {m.firstName} {m.lastName}</option>)}
              </select>
            </div>
            <div className="col-sm-3">
              <input type="date" className="form-control" value={day} onChange={(e) => chooseDay(e.target.value)} />
            </div>
            {isManager && (
              <div className="col-sm-4">
                <select className="form-select" value={clientId ?? ''}
                        onChange={(e) => setClientId(e.target.value === '' ? null : Number(e.target.value))}>
                  <option value="">-- patient to book for --</option>
                  {clients.data?.map((c) => <option key={c.id} value={c.id}>{c.title} {c.firstName} {c.lastName}</option>)}
                </select>
              </div>
            )}
          </div>

          {message && <div className={`alert alert-${message.type}`}>{message.text}</div>}
          {schedule.error && <div className="alert alert-danger">{errorText(schedule.error)}</div>}
          {schedule.isFetching && <p className="small text-muted">loading the schedule...</p>}

          {a && (
            <>
              {/* info: der vom Server gesendete Schlüssel, wenn ein Patient bereits einen bevorstehenden Termin hat */}
              {a.info && <div className="alert alert-info">{a.info}</div>}
              <table className="table table-sm align-middle">
                <caption className="caption-top">
                  Schedule of {a.day} - {a.doctor.title} {a.doctor.firstName} {a.doctor.lastName}
                </caption>
                <tbody>
                  {a.slots.map((c) => (
                    <tr key={c.id}>
                      <td>{timeRange(c)}</td>
                      <td>
                        {c.free ? (
                          <span className="badge text-bg-success">Free</span>
                        ) : c.patient ? (
                          <span className={`badge ${c.mine ? 'text-bg-primary' : 'text-bg-secondary'}`}>
                            {c.patient.title} {c.patient.firstName} {c.patient.lastName}
                          </span>
                        ) : (
                          <span className="badge text-bg-secondary">Booked</span>
                        )}
                      </td>
                      <td className="text-end">
                        {/* die Buttons folgen den vom Server berechneten Rechten */}
                        {c.bookable && <button className="btn btn-sm btn-outline-success" onClick={() => book(c)}>Book</button>}
                        {c.appointmentId !== null && <button className="btn btn-sm btn-outline-danger" onClick={() => cancel(c)}>Cancel</button>}
                      </td>
                    </tr>
                  ))}
                </tbody>
              </table>
            </>
          )}
        </>
      )}
    </div>
  );
}
  • Zeilen 54–58: [useQuery({ queryKey, queryFn, enabled })] beschreibt ein LESEN von Daten:
    • [queryFn]: die Funktion, die sie abruft, ein Promise;
    • [queryKey]: was die Daten IDENTIFIZIERT – ein Array. [TanStack Query] ruft [queryFn] zuerst auf und dann jedes Mal, wenn sich der Schlüssel ÄNDERT; zwei Komponenten, die denselben Schlüssel anfordern, teilen sich dieselbe Anfrage und dieselbe Antwort. Der Benutzer wird ihm hinzugefügt: Die Liste wird neu geladen, wenn sich der Benutzer ändert;
    • [enabled: false]: keine Anfrage (niemand ist angemeldet);
    • Das Ergebnis ist ein Objekt: [data] (die Antwort, [undefined] bis sie eintrifft), [isPending], [isFetching] (eine Anfrage läuft), [error] und [refetch()] zum erneuten Lesen;
  • Zeilen 59–63: die Patientenliste, nur für ADMIN und DOCTOR (ein USER würde einen 403 erhalten);
  • Zeilen 66–70: der Terminkalender: Der Schlüssel enthält den Arzt und den Tag; die Änderung eines von beiden sendet eine neue Anfrage. Eine veraltete Antwort wird automatisch ignoriert;
  • Zeilen 82–90: eine Reservierung: [POST /api/appointments], dann [schedule.refetch()]: Der Terminkalender wird neu gelesen. Der SERVER ist maßgeblich;
  • Zeile 106: Die Anmeldeleiste benachrichtigt die Seite;
  • Zeile 114: die Ärzte, falls sie eingetroffen sind ([?.]: nichts, wenn [data] gleich [undefined] ist);
  • Zeile 133: Eine Terminkalender-Anfrage läuft;
  • Zeilen 160–161: Die Schaltflächen folgen den vom Server berechneten Berechtigungen;
  • Zeile 138: [info]: der vom Server gesendete Schlüssel, wenn ein Patient bereits einen bevorstehenden Termin hat (roh angezeigt: hier gibt es kein Wörterbuch).

Als [admin] angemeldet, wählen wir Frau PELISSIER aus, dann einen Patienten, und buchen das erste Zeitfenster:

Image

Als [martin] angemeldet, buchen wir ein Zeitfenster: Der Patient sieht seinen eigenen Namen, aber der Name eines anderen Patienten wird ihm nie gesendet; die Schaltfläche „Buchen“ ist nicht mehr verfügbar (nur ein bevorstehender Termin):

Image

Für die Verarbeitung von Transaktionen (Buchen, Stornieren) bietet [TanStack Query] außerdem [useMutation], das den Status „in Bearbeitung“ und Fehler bei Änderungen behandelt. Wir verwenden dies hier nicht: Eine [async]-Funktion und ein [try / catch] genügen.

8.4. Beispiel 25: Vom Server zurückgegebene Fehler

Patientenverwaltung (Formular [admin]). Dieses Formular führt im Browser keine Validierung durch: Alles wird an den Server gesendet, der im Falle einer Ablehnung mit einem JSON-Fehler antwortet:

1
2
3
400 { key: 'ERRORS.INVALID_FORM', fields: { lastName: 'ERRORS.LASTNAME_REQUIRED' } }
409 { key: 'ERRORS.PATIENT_ALREADY_EXISTS', fields: { firstName: ..., lastName: ... } }
409 { key: 'ERRORS.CONCURRENT_UPDATE' }         (optimistic lock)

8.4.1. Wörterbücher

{
  "FORM": {
    "TITLE_ADD": "Ajouter un client",
    "TITLE_EDIT": "Modifier un client",
    "TITLE": "Titre",
    "FIRSTNAME": "Prénom",
    "LASTNAME": "Nom",
    "LOGIN": "Login",
    "PASSWORD": "Mot de passe",
    "SAVE": "Enregistrer",
    "CANCEL": "Annuler",
    "EDIT": "Modifier",
    "DELETE": "Supprimer",
    "DELETE_CONFIRM": "Supprimer le client {{name}}, son compte et ses rendez-vous ?",
    "ADDED": "Le client {{name}} a été ajouté (login : {{login}}).",
    "UPDATED": "Le client {{name}} a été modifié.",
    "DELETED": "Le client {{name}} a été supprimé.",
    "ADMIN_ONLY": "Connectez-vous avec le compte admin : seul le rôle ADMIN gère les clients."
  },
  "ERRORS": {
    "INVALID_FORM": "Le formulaire contient des erreurs.",
    "INVALID_TITLE": "Choisissez un titre dans la liste.",
    "FIRSTNAME_REQUIRED": "Le prénom est obligatoire.",
    "FIRSTNAME_TOO_LONG": "Le prénom ne doit pas dépasser 20 caractères.",
    "LASTNAME_REQUIRED": "Le nom est obligatoire.",
    "LASTNAME_TOO_LONG": "Le nom ne doit pas dépasser 20 caractères.",
    "INVALID_LOGIN": "30 caractères au plus : lettres minuscules non accentuées, chiffres, point, tiret, souligné.",
    "PASSWORD_TOO_LONG": "Le mot de passe ne doit pas dépasser 72 caractères.",
    "LOGIN_TAKEN": "Ce login est déjà utilisé par un autre compte.",
    "PATIENT_ALREADY_EXISTS": "Un client portant ce prénom et ce nom existe déjà.",
    "PATIENT_NOT_FOUND": "Ce client n'existe pas (ou plus).",
    "CONCURRENT_UPDATE": "Cette fiche a été modifiée entre-temps par un autre utilisateur. Rechargez-la avant de recommencer.",
    "FORBIDDEN": "Votre rôle ne vous permet pas cette action.",
    "AUTH_REQUIRED": "Connectez-vous d'abord.",
    "SESSION_EXPIRED": "Votre session a expiré : reconnectez-vous.",
    "SERVER_UNREACHABLE": "Le serveur ne répond pas.",
    "SERVER_ERROR": "Une erreur inattendue s'est produite."
  }
}

Die Schlüssel [ERRORS.*] sind die vom Server zurückgegebenen. Das englische Wörterbuch [en.json] hat dieselben Schlüssel. Die Konfiguration von [i18next] ist dieselbe wie in Beispiel 21, aber einfacher:

// =========================================================================
// 25-server-errors/src/i18n/i18n.ts - i18next, wie in Beispiel 21
// =========================================================================

import i18n from 'i18next';
import { initReactI18next } from 'react-i18next';
import fr from './fr.json';
import en from './en.json';

i18n.use(initReactI18next).init({
  resources: { fr: { translation: fr }, en: { translation: en } },
  lng: 'en',
  fallbackLng: 'en',
  interpolation: { escapeValue: false },
});
// =========================================================================
// 25-server-errors/src/main.tsx
// -------------------------------------------------------------------------
//   - i18next (vgl. Beispiel 21);
//   - der Bestätigungsdialog aus Beispiel 16, unverändert wiederverwendet.
// =========================================================================

import { StrictMode } from 'react';
import { createRoot } from 'react-dom/client';
import 'bootstrap/dist/css/bootstrap.min.css';
import './i18n/i18n';
import App from './App';
import { ConfirmationProvider } from '../../16-confirmation/src/confirmation/confirmation';

createRoot(document.getElementById('root')!).render(
  <StrictMode>
    <ConfirmationProvider>
      <App />
    </ConfirmationProvider>
  </StrictMode>,
);

Das Bestätigungsfenster aus Beispiel 16 wird unverändert wiederverwendet: Sein Provider wird importiert.

8.4.2. Die Seite

// =========================================================================
// 25-server-errors/src/App.tsx - Anzeige der Fehler des SERVERS
// -------------------------------------------------------------------------
// Die Verwaltung der Clients (Admin-Konto). Dieses Formular führt
// ABSICHTLICH keine Validierung im Browser durch: Alles wird an den
// Server gesendet, der im Fall einer Ablehnung mit einem JSON-Fehler antwortet (von
// common/api.ts in einen ApiError umgewandelt):
//
//   400 { key: 'ERRORS.INVALID_FORM', fields: { lastName: 'ERRORS.LASTNAME_REQUIRED' } }
//   409 { key: 'ERRORS.PATIENT_ALREADY_EXISTS', fields: { firstName: ..., lastName: ... } }
//   409 { key: 'ERRORS.CONCURRENT_UPDATE' }         (optimistisches Sperren)
//
// Der Fehler JEDES Feldes (ApiError.fields) wird im Zustand gespeichert und
// unter dem Feld angezeigt; seine Meldung ist der vom Server gesendete SCHLÜSSEL,
// den die Komponente übersetzt (i18next). Eine Änderung eines Feldes löscht seinen Fehler.
// Ausprobieren: ein leerer Nachname, ein Titel "Dr", ein Namensvetter (Alice DURAND), ein
// bereits vergebenes Login (martin), derselbe Datensatz in zwei Tabs bearbeitet...
// =========================================================================

import { useState, useTransition, type FormEvent } from 'react';
import { useTranslation } from 'react-i18next';
import { api } from '../../common/api';
import LoginBar from '../../common/LoginBar';
import { ApiError } from '../../common/api-error';
import type { Person, User } from '../../common/types';
import { useConfirmation } from '../../16-confirmation/src/confirmation/confirmation';

interface ClientInput {
  title: string;
  firstName: string;
  lastName: string;
  login: string;
  password: string;
  version: number;
}
type Field = keyof ClientInput;

const EMPTY: ClientInput = { title: 'Mr', firstName: '', lastName: '', login: '', password: '', version: 0 };

interface Message {
  key: string;
  params?: Record<string, string>;
}

export default function App() {
  const { t, i18n } = useTranslation();
  const confirm = useConfirmation();

  const [user, setUser] = useState<User | null>(null);
  const [clients, setClients] = useState<Person[]>([]);
  const isAdmin = user?.role === 'ADMIN';

  // das Formular: editedId === null -> Anlegen, sonst Aktualisieren
  const [editedId, setEditedId] = useState<number | null>(null);
  const [input, setInput] = useState<ClientInput>(EMPTY);
  // der Fehler jedes Feldes (ein Übersetzungs-SCHLÜSSEL), vom Server zurückgeliefert
  const [errors, setErrors] = useState<Partial<Record<Field, string>>>({});
  // die allgemeine Meldung des letzten Fehlers und die eines Erfolgs
  const [pageError, setPageError] = useState<ApiError | null>(null);
  const [success, setSuccess] = useState<Message | null>(null);
  // useTransition: isPending ist true während der Ausführung der Action,
  // die an startTransition übergeben wurde - hier das Senden an den Server
  const [sending, startTransition] = useTransition();

  async function reload() {
    setClients(await api.get<Person[]>('/clients'));
  }

  async function onUserChange(u: User | null) {
    setUser(u);
    setClients([]);
    if (u?.role === 'ADMIN') {
      await reload();
    }
  }

  function clearMessages() {
    setErrors({});
    setPageError(null);
    setSuccess(null);
  }

  function newForm() {
    setEditedId(null);
    setInput(EMPTY);
    clearMessages();
  }

  function edit(c: Person) {
    setEditedId(c.id);
    // die mit dem Datensatz gelesene VERSION geht mit der Aktualisierung zurück: Hat jemand
    // den Datensatz inzwischen geändert, antwortet der Server mit 409 CONCURRENT_UPDATE
    setInput({ title: c.title, firstName: c.firstName, lastName: c.lastName, login: c.login ?? '', password: '', version: c.version });
    clearMessages();
  }

  // ein geändertes Feld: Sein Wert ändert sich, sein Fehler verschwindet
  function change(field: Field, value: string) {
    setInput((s) => ({ ...s, [field]: value }));
    setErrors((e) => ({ ...e, [field]: undefined }));
  }

  function save(event: FormEvent<HTMLFormElement>) {
    event.preventDefault();
    clearMessages();
    // eine ASYNCHRONE Transition (React 19): sending bleibt true, bis
    // zum Ende der Funktion
    startTransition(async () => {
      try {
        const client =
          editedId === null
            ? await api.post<Person>('/clients', input)
            : await api.put<Person>(`/clients/${editedId}`, input);
        newForm(); // Formular geleert, Meldungen gelöscht...
        // ... außer dieser
        setSuccess({
          key: editedId === null ? 'FORM.ADDED' : 'FORM.UPDATED',
          params: { name: `${client.firstName} ${client.lastName}`, login: client.login ?? '' },
        });
        await reload();
      } catch (e) {
        if (!(e instanceof ApiError)) {
          throw e;
        }
        setPageError(e); // die allgemeine Meldung
        setErrors(e.fields); // der Fehler jedes Feldes
      }
    });
  }

  async function remove(c: Person) {
    const name = `${c.firstName} ${c.lastName}`;
    if (!(await confirm(t('FORM.DELETE_CONFIRM', { name })))) {
      return;
    }
    clearMessages();
    try {
      await api.delete(`/clients/${c.id}`);
      setSuccess({ key: 'FORM.DELETED', params: { name } });
    } catch (e) {
      setPageError(e instanceof ApiError ? e : null);
    }
    await reload();
  }

  // ein Eingabefeld mit seinem übersetzten Fehler
  function field(name: 'firstName' | 'lastName' | 'login' | 'password', type = 'text') {
    const error = errors[name];
    return (
      <>
        <label className="form-label" htmlFor={name}>{t(`FORM.${name.toUpperCase()}`)}</label>
        <input id={name} type={type} className={`form-control ${error ? 'is-invalid' : ''}`} value={input[name]}
               autoComplete={type === 'password' ? 'new-password' : 'off'} onChange={(e) => change(name, e.target.value)} />
        {/* die Meldung eines Serverfehlers ist ein SCHLÜSSEL: Er wird übersetzt */}
        {error && <div className="invalid-feedback">{t(error)}</div>}
      </>
    );
  }

  return (
    <div className="container py-4">
      <div className="d-flex justify-content-between align-items-center mb-3">
        <h1 className="h3 mb-0">Example 25 - the errors returned by the server</h1>
        <select className="form-select form-select-sm w-auto" value={i18n.language} onChange={(e) => i18n.changeLanguage(e.target.value)}>
          <option value="fr">FR</option>
          <option value="en">EN</option>
        </select>
      </div>
      <LoginBar onUserChange={onUserChange} />
      {user && !isAdmin && <p className="alert alert-warning">{t('FORM.ADMIN_ONLY')}</p>}

      {isAdmin && (
        <div className="row g-4">
          <div className="col-lg-6">
            <table className="table table-sm align-middle">
              <tbody>
                {clients.map((c) => (
                  <tr key={c.id}>
                    <td>{c.title} {c.firstName} {c.lastName}</td>
                    <td><code>{c.login}</code></td>
                    <td className="text-end text-nowrap">
                      <button className="btn btn-sm btn-outline-primary me-1" onClick={() => edit(c)}>{t('FORM.EDIT')}</button>
                      <button className="btn btn-sm btn-outline-danger" onClick={() => remove(c)}>{t('FORM.DELETE')}</button>
                    </td>
                  </tr>
                ))}
              </tbody>
            </table>
          </div>

          <div className="col-lg-6">
            <form className="card p-3" noValidate onSubmit={save}>
              <h2 className="h5">{t(editedId === null ? 'FORM.TITLE_ADD' : 'FORM.TITLE_EDIT')}</h2>
              <div className="mb-2">
                <label className="form-label" htmlFor="title">{t('FORM.TITLE')}</label>
                {/* eine Option "Dr", die der Server ablehnen wird: um ERRORS.INVALID_TITLE zu sehen */}
                <select id="title" className={`form-select ${errors.title ? 'is-invalid' : ''}`} value={input.title}
                        onChange={(e) => change('title', e.target.value)}>
                  <option>Mr</option><option>Mme</option><option>Melle</option><option>Dr</option>
                </select>
                {errors.title && <div className="invalid-feedback">{t(errors.title)}</div>}
              </div>
              <div className="row g-2 mb-2">
                <div className="col-sm-6">{field('firstName')}</div>
                <div className="col-sm-6">{field('lastName')}</div>
              </div>
              <div className="row g-2 mb-3">
                <div className="col-sm-6">{field('login')}</div>
                <div className="col-sm-6">{field('password', 'password')}</div>
              </div>
              <div className="d-flex gap-2">
                <button className="btn btn-primary" disabled={sending}>{t('FORM.SAVE')}</button>
                <button type="button" className="btn btn-secondary" onClick={newForm}>{t('FORM.CANCEL')}</button>
              </div>
              {success && <div className="alert alert-success mt-3 mb-0">{t(success.key, success.params)}</div>}
              {/* die allgemeine Meldung und der HTTP-Status, zum Verständnis */}
              {pageError && (
                <div className="alert alert-danger mt-3 mb-0">
                  {t(pageError.key, pageError.params)}{' '}
                  <span className="small text-muted">({pageError.statusCode} {pageError.key})</span>
                </div>
              )}
            </form>
          </div>
        </div>
      )}
    </div>
  );
}
  • Zeilen 54–55: das Formular: [editedId === null] zum Erstellen eines Patienten oder [editedId] zum Ändern eines Patienten;
  • Zeile 57: der Fehler zu jedem Feld, ein Übersetzungs-SCHLÜSSEL, vom Server zurückgegeben;
  • Zeile 63: [useTransition] liefert ein Flag „in Bearbeitung“ und eine Funktion [startTransition(action)]. Ab [React] 19 kann die Aktion [async] sein: Der Indikator bleibt bis zum Ende der Funktion true, ohne dass eine manuelle Behandlung nötig ist;
  • Zeilen 89–95: einen Patienten ändern. Die VERSION, die aus dem Stammdatensatz gelesen wurde, spiegelt die Änderung wider: Hat jemand den Stammdatensatz zwischenzeitlich geändert, antwortet der Server mit einem 409 [ERRORS.CONCURRENT_UPDATE] (optimistisches Sperren);
  • Zeilen 98–101: ein geändertes Feld: Sein Wert ändert sich, und sein Fehler verschwindet;
  • Zeilen 103–129: das Senden:
    • [POST /api/clients] (Erstellung) oder [PUT /api/clients/:id] (Aktualisierung);
    • bei Erfolg: Das Formular wird geleert, und eine Meldung wird samt ihren Parametern übersetzt;
    • im Fall eines [ApiError] (Zeilen 125–126): die allgemeine Meldung und der Fehler zu JEDEM Feld; die Zeile, wie sie im Bericht erscheint: [e.fields] hat genau das gewünschte Format;
  • Zeilen 131–144: das Löschen, nach Bestätigung. Die Bestätigungsmeldung wird von [t] mit einem Parameter übersetzt;
  • Zeilen 147–158: eine Funktion, die ein Eingabefeld mit seinem Label und seiner Fehlermeldung erzeugt: [t(error)] übersetzt den vom Server gesendeten SCHLÜSSEL;
  • Zeile 164: Sprachauswahl: Die bereits angezeigten Fehler werden neu übersetzt, da es sich um Schlüssel handelt;
  • Zeile 199: eine Option „Dr“, die der Server ablehnen wird, was zu [ERRORS.INVALID_TITLE] führt;
  • Zeile 212: Die Schaltfläche ist während des Sendens deaktiviert;
  • Zeile 219: die allgemeine Meldung und der HTTP-Status, zur Einordnung.

Als [admin] angemeldet, mit dem Titel „Dr“, einem leeren Namen und einem ungültigen Login:

Image

Ein Namensvetter (Alice Durand, die bereits existiert) und ein bereits vergebener Login ([martin]): 409, und die beiden betroffenen Felder werden gekennzeichnet:

Image

Dieselbe Seite auf Französisch: Die Servermeldungen werden zurückübersetzt:

Image

Ein erfolgreiches Hinzufügen:

Image

Dann dessen Löschung:

Image

Image

Um das optimistische Sperren zu sehen, öffnen Sie denselben Datensatz in zwei Tabs, speichern ihn im ersten Tab und dann im zweiten: Der Server antwortet mit einem 409-Fehler ([ERRORS.CONCURRENT_UPDATE]).