Skip to content

8. Kommunikation mit dem Server

Die Beispiele dieses Kapitels fragen den JSON-Server [RdvMedecins] ab: Er muss laufen ([npm run start:dev] im Ordner [rdvmedecins-nestjs-json]) auf Port 8080, gleichzeitig mit dem [Angular]-Entwicklungsserver auf Port 4200.

8.1. Beispiel 22: Eine erste HTTP-Anfrage

8.1.1. Der Proxy des Entwicklungsservers

Die Beispielseite stammt von http://localhost:4200 (dem [Angular]-Entwicklungsserver, gestartet mit [ng serve]); 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 es ausdrücklich (der Mechanismus, der als CORS bekannt ist). Und eine Anfrage an einen anderen Ursprung überträgt keine Cookies (und damit auch nicht das Token), es sei denn, der Code verlangt es ([withCredentials: true]) UND der Server akzeptiert es, wiederum über CORS.

Anstatt den Server für andere Ursprünge zu öffnen, leiten wir die API-Anfragen über den [Angular]-Entwicklungsserver. Das ist der Proxy , der in der Workspace-Datei [proxy.conf.json] deklariert ist:

1
2
3
4
5
6
{
  "/api": {
    "target": "http://localhost:8080",
    "secure": false
  }
}
  • Zeile 2: Anfragen, deren Pfad mit /api beginnt ...
  • Zeile 3: ... werden an den JSON-Server weitergeleitet.

Für jedes Beispiel wird die Datei in den Optionen des Befehls [ng serve] in der Datei [angular.json] angegeben:

1
2
3
4
5
        "serve": {
          "builder": "@angular/build:dev-server",
          "options": {
            "proxyConfig": "proxy.conf.json"
          },

Der Browser sendet [GET http://localhost:4200/api/captcha]; der Entwicklungsserver leitet die Anfrage an [http://localhost:8080/api/captcha] weiter und gibt die Antwort dann an den Browser zurück. Für den Browser 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 „Bereitstellung“). Die Seite und die API haben weiterhin denselben Ursprung.

8.1.2. Die Anfrage

[Angular] stellt einen eigenen HTTP-Client bereit, den Service [HttpClient]. Er ist in jeder Anwendung automatisch verfügbar: Man muss ihn nur injizieren.

// =========================================================================
// 22-httpclient/src/app/app.ts - eine erste HTTP-Anfrage an den Server
// -------------------------------------------------------------------------
// Der JSON-Server von RdvMedecins muss laufen (Port 8080). Wir fordern von ihm
// ein Captcha an: GET /api/captcha -> { "id": "...", "svg": "<svg ...>" }.
//
//   - HttpClient: der HTTP-Client von Angular (standardmäßig für die gesamte
//     Anwendung bereitgestellt). http.get<T>(url) liefert ein OBSERVABLE (siehe Beispiel
//     19): Die Anfrage wird erst gesendet, wenn wir es ABONNIEREN (subscribe);
//     die JSON-Antwort kommt bereits in ein Objekt des angegebenen Typs T umgewandelt an;
//   - die Adresse ist RELATIV (/api/captcha): die Anfrage geht an den
//     Server der Seite, den von Angular (Port 4200), der sie dank seines Proxys (siehe proxy.conf.json) an den
//     JSON-Server (Port 8080) weiterleitet;
//   - drei anzuzeigende Zustände: Laden, Erfolg, Fehler.
// =========================================================================

import { Component, computed, inject, signal } from '@angular/core';
import { HttpClient, HttpErrorResponse } from '@angular/common/http';
import { DomSanitizer, SafeHtml } from '@angular/platform-browser';

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

@Component({
  selector: 'app-root',
  templateUrl: './app.html',
  styles: `
    .captcha {
      display: inline-block;
      border: 1px solid #dee2e6;
      border-radius: 0.375rem;
    }
  `,
})
export class App {
  private readonly http = inject(HttpClient);
  private readonly sanitizer = inject(DomSanitizer);

  protected readonly captcha = signal<Captcha | null>(null);
  protected readonly loading = signal(false);
  protected readonly error = signal<string | null>(null);
  protected readonly requestCount = signal(0);

  // [innerHTML] fügt einen String als HTML ein. Aus Sicherheitsgründen BEREINIGT
  // Angular dieses HTML ("Sanitization"): Es entfernt die Skripte ... und die
  // <svg>-Tags. bypassSecurityTrustHtml sagt Angular: "Dieses HTML ist
  // sicher, nicht bereinigen". NUR für sichere Inhalte verwenden: Dieses SVG
  // wird von UNSEREM Server erzeugt. Bei Benutzereingaben wäre das
  // ein Einfallstor für Script-Injection ({{ }} dagegen maskiert alles).
  protected readonly svg = computed<SafeHtml | null>(() => {
    const c = this.captcha();
    return c ? this.sanitizer.bypassSecurityTrustHtml(c.svg) : null;
  });

  constructor() {
    this.load(); // beim Start laden wir ein Captcha
  }

  protected load(): void {
    this.loading.set(true);
    this.error.set(null);
    this.http.get<Captcha>('/api/captcha').subscribe({
      // next: die Antwort (Code 2xx), bereits aus JSON umgewandelt
      next: (captcha) => {
        this.captcha.set(captcha);
        this.requestCount.update((n) => n + 1);
        this.loading.set(false);
      },
      // error: eine Antwort 4xx / 5xx oder gar keine Antwort (Status 0)
      error: (e: HttpErrorResponse) => {
        this.error.set(`the server answered ${e.status} ${e.statusText}`);
        this.captcha.set(null);
        this.loading.set(false);
      },
    });
  }
}
  • Zeile 22: das Format der Antwort von [GET /api/captcha];
  • Zeile 39: den HTTP-Client injizieren;
  • Zeilen 42–45: die drei Zustände einer Anfrage: in Bearbeitung, erfolgreich (das CAPTCHA) und Fehler;
  • Zeile 65: [http.get<Captcha>(url)] bereitet eine GET-Anfrage vor. Sie gibt ein Observable zurück (Beispiel 19): Die Anfrage wird erst gesendet, wenn es abonniert wird ([subscribe]). Die Adresse ist relativ: Die Anfrage geht an den Server der Seite, der sie an den JSON-Server weiterleitet;
  • Zeilen 67–71: [next] erhält die Antwort, die bereits aus JSON umgewandelt wurde. [<Captcha>] teilt [TypeScript] das Format des Objekts mit: Der Compiler kann nicht prüfen, was der Server senden wird;
  • Zeilen 73–77: [error] erhält eine [HttpErrorResponse] bei jeder 4xx- oder 5xx-Antwort sowie dann, wenn keine Antwort eintrifft (Server ausgefallen, Netzwerk getrennt: [status] ist dann 0). Ist der JSON-Server ausgefallen, antwortet der Proxy mit einem 5xx-Fehler;
  • Zeile 59: Beim Start wird ein CAPTCHA geladen;
  • Zeilen 53–56: Das SVG-Bild des CAPTCHA ist eine Zeichenkette, die als HTML eingefügt werden muss ([[innerHTML]] im Template). Aus Sicherheitsgründen [Angular] bereinigt jedes auf diese Weise eingefügte HTML: Es entfernt die Skripte ... und die [<svg>]-Tags. [bypassSecurityTrustHtml] gibt an, dass dieses HTML sicher ist. Wir verwenden es NUR für sichere Inhalte: Dieses SVG wird von UNSEREM Server erzeugt. Bei vom Benutzer eingegebenen Daten würde dies das Einschleusen von Skripten in die Seite ermöglichen; die doppelten geschweiften Klammern [{{ }}] hingegen maskieren alles.
<div class="container py-4" style="max-width: 640px">
  <h1 class="h3 mb-3">Example 22 - a first HTTP request</h1>
  <div class="card p-3">
    @if (loading()) {
      <p class="text-muted">Loading...</p>
    } @else if (error()) {
      <div class="alert alert-danger mb-3">
        Unable to get a captcha: {{ error() }}.<br>
        Is the RdvMedecins JSON server running (port 8080)?
      </div>
    } @else if (captcha(); as c) {
      <div class="mb-2"><div class="captcha" [innerHTML]="svg()"></div></div>
      <p class="small text-muted">id: <code>{{ c.id }}</code></p>
    }
    <button class="btn btn-primary align-self-start" [disabled]="loading()" (click)="load()">Another image</button>
    <p class="small text-muted mt-2 mb-0">{{ requestCount() }} successful request(s) - open the Network tab of the developer tools (F12).</p>
  </div>
</div>
  • Zeilen 4–14: eine Statusanzeige;
  • Zeile 12: das CAPTCHA-Bild.

[npm start 22-httpclient]; klicken Sie auf [Another image]:

Image

In den Entwicklertools des Browsers (F12) zeigt der Tab „Netzwerk“ die Anfrage [captcha], die an [localhost:4200] gesendet wurde, und ihre JSON-Antwort.

// =========================================================================
// 23-login/src/app/app.ts - Anmeldung am RdvMedecins-Server
// -------------------------------------------------------------------------
//   1. beim Start: GET /api/auth/me - sind wir schon 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 NIEMALS (probieren 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.
//
// firstValueFrom(observable): ein PROMISE auf den ersten Wert des Streams.
// Anfragenketten lassen sich dann mit async / await schreiben,
// lesbarer als eine Kaskade von subscribe. Eine Fehlerantwort lehnt
// das Promise mit einer HttpErrorResponse ab: ein einfaches try / catch.
//
// Ein Cookie gehört zu einem Rechner (localhost) und zu einem Pfad (/api): Es
// ist daher ALLEN Beispielen gemeinsam. Sobald Sie hier angemeldet sind, sind es die Beispiele
// 24 und 25 ebenfalls.
// =========================================================================

import { Component, computed, inject, signal } from '@angular/core';
import { HttpClient, HttpErrorResponse } from '@angular/common/http';
import { DomSanitizer } from '@angular/platform-browser';
import { FormsModule } from '@angular/forms';
import { firstValueFrom } from 'rxjs';

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 ngx-translate)
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.',
};

@Component({
  selector: 'app-root',
  imports: [FormsModule],
  templateUrl: './app.html',
})
export class App {
  private readonly http = inject(HttpClient);
  private readonly sanitizer = inject(DomSanitizer);

  protected readonly user = signal<User | null>(null);
  protected readonly doctors = signal<Doctor[]>([]);
  protected readonly captcha = signal<Captcha | null>(null);
  protected readonly svg = computed(() => this.sanitizer.bypassSecurityTrustHtml(this.captcha()?.svg ?? ''));
  protected readonly login = signal('admin');
  protected readonly password = signal('');
  protected readonly captchaAnswer = signal('');
  protected readonly error = signal<string | null>(null);
  protected readonly ready = signal(false); // ist die anfängliche Prüfung abgeschlossen?

  constructor() {
    this.checkSession().catch(() => {
      this.error.set('Is the RdvMedecins JSON server running (port 8080)?');
      this.ready.set(true);
    });
  }

  protected async loadCaptcha(): Promise<void> {
    this.captcha.set(await firstValueFrom(this.http.get<Captcha>('/api/captcha')));
    this.captchaAnswer.set('');
  }

  // 1. wer ist angemeldet? 200 -> der Benutzer; 401 -> niemand
  private async checkSession(): Promise<void> {
    try {
      this.user.set(await firstValueFrom(this.http.get<User>('/api/auth/me')));
      await this.loadDoctors();
    } catch (e) {
      if (!(e instanceof HttpErrorResponse) || e.status !== 401) {
        throw e; // kein 401: der Server antwortet nicht
      }
      await this.loadCaptcha();
    }
    this.ready.set(true);
  }

  // 2. der Login; post(url, body): der Body wird als JSON gesendet
  protected async logIn(): Promise<void> {
    this.error.set(null);
    try {
      const u = await firstValueFrom(
        this.http.post<User>('/api/auth/login', {
          login: this.login(),
          password: this.password(),
          captchaId: this.captcha()?.id,
          captcha: this.captchaAnswer(),
        }),
      );
      this.user.set(u);
      this.password.set('');
      await this.loadDoctors();
    } catch (e) {
      // e.error: der JSON-Body der Fehlerantwort
      const apiError = (e as HttpErrorResponse).error as ApiError | null;
      const key = apiError?.key ?? 'ERRORS.SERVER_UNREACHABLE';
      this.error.set(`${(e as HttpErrorResponse).status} - ${MESSAGES[key] ?? key}`);
      await this.loadCaptcha(); // jedes Bild wird nur einmal verwendet
    }
  }

  // 3. eine geschützte Anfrage
  private async loadDoctors(): Promise<void> {
    this.doctors.set(await firstValueFrom(this.http.get<Doctor[]>('/api/doctors')));
  }

  // 4. der Logout
  protected async logOut(): Promise<void> {
    await firstValueFrom(this.http.post('/api/auth/logout', {}));
    this.user.set(null);
    this.doctors.set([]);
    await this.loadCaptcha();
  }
}
  • Zeilen 30–50: die Formate der mit dem Server ausgetauschten Daten, einschließlich derer für alle Fehler der API (Zeilen 46–50);
  • Zeilen 53–57: die wenigen Nachrichten, die dieses Beispiel benötigt, auf Englisch; Beispiel 25 wird [ngx-translate] verwenden;
  • Zeile 28: [firstValueFrom(observable)] gibt ein Promise für den ersten Wert des Stroms zurück. Eine HTTP-Anfrage erzeugt nur einen Wert, die Antwort: Wir können dann Anfrageketten mit [async] / [await] schreiben, die lesbarer sind als eine Kaskade von [subscribe]. Eine Fehlerantwort weist das Promise zurück: Ein einfaches [try / catch] fängt sie ab;
  • Zeilen 91–102: Beim Start [GET /api/auth/me]: Sind wir bereits angemeldet? Nach dem Neuladen der Seite (F5) hat die [Angular] -Anwendung alles vergessen; der Server hingegen liest den Cookie. 200: der Benutzer; 401: niemand – in diesem Fall werden das Anmeldeformular und sein CAPTCHA angezeigt (Zeile 99);
  • Zeile 96: Jeder andere Fehler bedeutet, dass der Server nicht antwortet; er wird dem Entwickler gemeldet (Zeilen 79–82);
  • Zeilen 105–126: die Anmeldung:
    • Zeile 109: [http.post(url, body)]: das Objekt [body] wird als JSON gesendet, mit dem Header [Content-Type: application/json];
    • Zeile 116: Bei Erfolg hat der Server den Token-Cookie gesetzt. Unser Code sieht ihn NIE: Geben Sie [document.cookie] in der Browser-Konsole ein; er ist nicht vorhanden ([HttpOnly]);
    • Zeile 121: Schlägt die Anfrage fehl, [error] enthält den JSON-Antwortkörper, der den Grund erklärt. Wir zeigen die Meldung an (Zeile 123) und fordern ein neues Bild an (Zeile 124): Jedes Bild kann nur einmal verwendet werden;
  • Zeilen 129–131: eine geschützte Anfrage. Zur Authentifizierung ist keine Aktion erforderlich: Der Browser sendet den Cookie automatisch mit, weil die Anfrage an denselben Origin wie die Seite geht;
  • Zeilen 134–139: Abmeldung – der Server löscht den Cookie. Der Body [{}] wird mitgesendet, damit die Anfrage ein POST mit JSON ist.

Ein Cookie gehört zu einem Rechner (localhost) und einem Pfad (/api); er wird daher von ALLEN Beispielen gemeinsam genutzt. Sobald Sie hier angemeldet sind, sind Sie es auch in den Beispielen 24 und 25.

Das Anmeldeformular:

<div class="container py-4" style="max-width: 640px">
  <h1 class="h3 mb-3">Example 23 - logging in to the server</h1>
  @if (!ready()) {
    <p class="text-muted">Checking the session...</p>
  } @else if (user(); as u) {
    <!-- angemeldet -->
    <div class="card p-3">
      <p>Logged in: <strong>{{ u.name }}</strong> ({{ u.login }}), role <span class="badge text-bg-primary">{{ u.role }}</span></p>
      <h2 class="h6">GET /api/doctors</h2>
      <ul>
        @for (m of doctors(); track m.id) {
          <li>{{ m.title }} {{ m.firstName }} {{ m.lastName }}</li>
        }
      </ul>
      <p class="small text-muted">Reload the page (F5): you stay logged in.</p>
      <button class="btn btn-outline-secondary align-self-start" (click)="logOut()">Log out</button>
    </div>
  } @else {
    <!-- nicht angemeldet: das Formular -->
    <form class="card p-3" (ngSubmit)="logIn()">
      <div class="mb-2">
        <label class="form-label" for="login">Login</label>
        <input id="login" name="login" class="form-control" autocomplete="username" [(ngModel)]="login">
      </div>
      <div class="mb-2">
        <label class="form-label" for="password">Password</label>
        <input id="password" name="password" type="password" class="form-control" autocomplete="current-password"
               [(ngModel)]="password">
      </div>
      <div class="mb-3">
        <label class="form-label" for="captcha">Copy the characters of the image</label>
        <div class="d-flex align-items-center gap-3 mb-2">
          <div [innerHTML]="svg()"></div>
          <a href="#" class="small" (click)="$event.preventDefault(); loadCaptcha()">Another image</a>
        </div>
        <input id="captcha" name="captcha" class="form-control" autocomplete="off" [(ngModel)]="captchaAnswer">
      </div>
      <button class="btn btn-primary">Log in</button>
      <p class="small text-muted mt-2 mb-0">Accounts: admin, pelissier, martin... (password = login).</p>
    </form>
  }
  @if (error()) {
    <div class="alert alert-danger mt-3">{{ error() }}</div>
  }
</div>
  • Zeile 3: Solange die erste Prüfung nicht abgeschlossen ist, wissen wir nicht, was angezeigt werden soll;
  • Zeilen 5–17: angemeldet: der Benutzer und die Liste der Ärzte;
  • Zeilen 20–40: nicht angemeldet: das Formular, mit [ngModel] (Beispiel 05);
  • Zeile 34: [$event.preventDefault()] verhindert, dass der Link seiner Adresse (#) folgt.

[npm start 23-login]. Mit einem falschen Passwort (der Server befindet sich im Testmodus: Jedes CAPTCHA akzeptiert die Antwort [test]):

Image

Mit dem richtigen Passwort, gefolgt von einer Aktualisierung der Seite (F5): Sie bleiben angemeldet.

Image

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

In Beispiel 23 wiederholte jede Anfrage dieselben Schritte: das Präfix /api, [firstValueFrom], das Lesen des Fehler-Bodys und die Auswahl einer Meldung. Dieses Beispiel fasst sie in wenigen Dateien zusammen, die im [common]-Ordner des Workspace liegen, weil auch Beispiel 25 sie verwendet:

1
2
3
4
5
6
examples-angular/common/
├── types.ts                the JSON objects of the API
├── api-error.ts            a class for all the API errors
├── errors.interceptor.ts   an HTTP interceptor
├── api.service.ts          one-line requests
└── login-bar.ts            the login, in a bar

Die Datei [tsconfig.app.json] des Beispiels fügt diesen Ordner zu den zu kompilierenden Dateien hinzu:

1
2
3
4
{
  "extends": "../tsconfig.json",
  "include": ["src/**/*.ts", "../common/**/*.ts"]
}

8.3.1. Die Typen

Die Typen der JSON-Objekte der API, die im vorherigen Kapitel beschrieben wurden:

// =========================================================================
// common/types.ts - die zwischen den Beispielen und der RdvMedecins-API ausgetauschten JSON-Objekte
// (siehe das 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 Kunde (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;
}

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": {...} }
// HttpClient meldet sie mit einer HttpErrorResponse, deren Eigenschaft error
// diesen JSON-Body enthält ... oder etwas anderes: null (keine Antwort), Text
// (eine Fehlerseite des Proxys, wenn der JSON-Server gestoppt ist). Wir
// wandeln all das in EINE Klasse um, ApiError, die den vom Server gesendeten Übersetzungsschlüssel
// trägt (und gegebenenfalls dessen Parameter und
// den Fehler jedes Felds).
// =========================================================================

import { HttpErrorResponse } from '@angular/common/http';

export class ApiError extends Error {
  constructor(
    public readonly statusCode: number, // 0: der Server hat nicht geantwortet
    public readonly key: string, // z. B.: 'ERRORS.LOGIN_TAKEN'
    public readonly params: Record<string, string> = {},
    public readonly fields: Record<string, string> = {},
  ) {
    super(key);
    this.name = 'ApiError';
  }
}

// jeder Fehler -> ein ApiError
export function toApiError(e: unknown): ApiError {
  if (e instanceof ApiError) {
    return e;
  }
  if (!(e instanceof HttpErrorResponse)) {
    return new ApiError(0, 'ERRORS.SERVER_ERROR');
  }
  // der JSON-Body des Fehlers, falls vorhanden und von der richtigen Form
  const body = (typeof e.error === 'object' && e.error !== null ? e.error : {}) as {
    key?: string;
    params?: Record<string, string>;
    fields?: Record<string, string>;
  };
  // kein key: nicht unser Server hat geantwortet (Proxy, Netzwerk)
  const key = body.key ?? (e.status === 0 || e.status >= 500 ? 'ERRORS.SERVER_UNREACHABLE' : 'ERRORS.SERVER_ERROR');
  return new ApiError(e.status, key, body.params, body.fields);
}
  • Zeilen 16–26: eine Fehlerklasse, die die Antwort des Servers enthält: den HTTP-Code, den Meldungsschlüssel, seine Parameter und den Fehler für jedes Feld. Der Code 0 bedeutet „keine Antwort“;
  • Zeilen 29–45: die Umwandlung eines beliebigen Fehlers in [ApiError]:
    • Zeile 37: Der Antwortkörper wird nur verwendet, wenn er ein Objekt ist. Wenn der JSON-Server nicht läuft, antwortet der Proxy mit Text;
    • Zeile 43: Ohne Schlüssel hat nicht unser Server geantwortet.

8.3.3. Ein Interceptor

Ein Interceptor ist eine Funktion, durch die die Anfragen von [HttpClient] und ihre Antworten laufen. Er kann die Anfrage vor dem Senden verändern (zum Beispiel einen Header hinzufügen) oder die Antwort bei ihrer Rückkehr.

// =========================================================================
// common/errors.interceptor.ts - ein HTTP-INTERCEPTOR
// -------------------------------------------------------------------------
// Ein Interceptor ist eine Funktion, durch die ALLE Anfragen
// von HttpClient (und ihre Antworten) laufen. Sie erhält die Anfrage (req) und den Rest
// der Kette (next):
//   - next(req) sendet die Anfrage und liefert das Observable der Antwort;
//   - die Anfrage kann zuvor geändert werden (req.clone({...})), oder die Antwort
//     danach (RxJS-Operatoren auf dem Observable).
// Dieser hier wandelt jeden Fehler in einen ApiError um (catchError): Der Rest
// der Anwendung hat nie wieder mit HttpErrorResponse zu tun.
// Er wird in der Konfiguration der Anwendung deklariert:
//     provideHttpClient(withInterceptors([errorsInterceptor]))
// =========================================================================

import { HttpInterceptorFn } from '@angular/common/http';
import { catchError, throwError } from 'rxjs';
import { toApiError } from './api-error';

export const errorsInterceptor: HttpInterceptorFn = (req, next) =>
  next(req).pipe(catchError((e: unknown) => throwError(() => toApiError(e))));
  • Zeile 20: Ein Interceptor erhält die Anfrage ([req]) und den Rest der Kette ([next]). [next(req)] sendet die Anfrage und gibt das Observable der Antwort zurück;
  • Zeile 21: Der Operator [catchError] ersetzt alle Fehler im Datenstrom durch einen [ApiError]. Der Rest der Anwendung muss sich nie wieder mit [HttpErrorResponse] befassen.

8.3.4. Der Service ApiService

// =========================================================================
// common/api.service.ts - Anfragen an die API in einer Zeile
// -------------------------------------------------------------------------
// In Beispiel 23 wiederholte jede Anfrage dieselben Schritte: Präfix /api,
// firstValueFrom, Lesen des Fehler-Bodys ... Wir fassen sie hier zusammen:
//
//   const doctors = await this.api.get<Person[]>('/doctors');
//   await this.api.post('/appointments', { day, slotId, clientId });
//
//   - bei Erfolg liefert das Promise den JSON-Body, TYPISIERT;
//   - bei einem Fehler wird es mit einem ApiError ABGELEHNT (dank des
//     Interceptors errors.interceptor.ts).
// Verwendet von den Beispielen 24 und 25; die Fallstudie übernimmt sein Prinzip.
// =========================================================================

import { inject, Injectable } from '@angular/core';
import { HttpClient } from '@angular/common/http';
import { firstValueFrom } from 'rxjs';

@Injectable({ providedIn: 'root' })
export class ApiService {
  private readonly http = inject(HttpClient);

  get<T>(url: string): Promise<T> {
    return firstValueFrom(this.http.get<T>(`/api${url}`));
  }

  // ein POST hat immer einen JSON-Body (der Server lehnt einen POST ohne Body ab)
  post<T>(url: string, body: unknown = {}): Promise<T> {
    return firstValueFrom(this.http.post<T>(`/api${url}`, body));
  }

  put<T>(url: string, body: unknown): Promise<T> {
    return firstValueFrom(this.http.put<T>(`/api${url}`, body));
  }

  delete<T>(url: string, body?: unknown): Promise<T> {
    return firstValueFrom(this.http.delete<T>(`/api${url}`, { body: body }));
  }
}
  • Zeilen 24–39: eine Methode für jedes HTTP-Verb. Jede fügt das Präfix /api hinzu und gibt ein Promise für den Antwortkörper zurück, typisiert als: [api.get<Person[]>('/doctors')] gibt ein [Promise<Person[]>] zurück. Im Fehlerfall wird das Promise mit einem [ApiError] abgelehnt;
  • Zeile 29: [post] sendet standardmäßig den Body [{}]: Der Server weist einen POST ab, der nicht in JSON vorliegt.

8.3.5. Die API-Zugriffsschicht

// =========================================================================
// 24-api-service/src/app/rdvmedecins.service.ts - die Zugriffsschicht auf die API
// -------------------------------------------------------------------------
// Eine typisierte Methode pro Route der API. Die Komponenten kennen weder
// die URLs noch HttpClient noch das JSON-Format: Sie rufen Methoden auf.
// Es ist das clientseitige Äquivalent der DAO-Schicht auf der Serverseite: Ändert sich die API
// (eine URL, ein Feldname), wird nur diese Datei geändert.
// =========================================================================

import { inject, Injectable } from '@angular/core';
import { HttpResourceRequest } from '@angular/common/http';
import { ApiService } from '../../../common/api.service';
import { Person } from '../../../common/types';

@Injectable({ providedIn: 'root' })
export class RdvMedecinsService {
  private readonly api = inject(ApiService);

  getDoctors(): Promise<Person[]> {
    return this.api.get<Person[]>('/doctors');
  }

  getClients(): Promise<Person[]> {
    return this.api.get<Person[]>('/clients');
  }

  // die BESCHREIBUNG der Anfrage des Terminkalenders für httpResource (siehe app.ts);
  // params baut "?doctorId=1&day=2030-01-15" und kodiert dabei, was kodiert werden muss
  scheduleRequest(doctorId: number, day: string): HttpResourceRequest {
    return { url: '/api/schedule', params: { doctorId, day } };
  }

  book(day: string, slotId: number, clientId?: number): Promise<{ id: number }> {
    return this.api.post<{ id: number }>('/appointments', { day, slotId, clientId });
  }

  cancelAppointment(appointmentId: number): Promise<Record<string, never>> {
    return this.api.delete<Record<string, never>>(`/appointments/${appointmentId}`);
  }
}

Eine Methode pro Route der API. Die Komponenten kennen die Adressen, den [HttpClient] oder das JSON-Format nicht mehr: Sie rufen Methoden auf. Das ist das clientseitige Gegenstück zur serverseitigen Datenzugriffsschicht: Ändert sich die API, muss nur diese Datei angepasst werden.

  • Zeilen 29–31: die Beschreibung der Terminkalender-Anfrage, nicht die Anfrage selbst: Sie wird von [httpResource] verwendet (siehe unten). [params] erzeugt die Zeichenkette [?doctorId=1&day=2030-01-15] und kodiert dabei die Zeichen, die kodiert werden müssen.

8.3.6. Die Anmeldeleiste

Das Formular aus Beispiel 23, auf eine Leiste reduziert und mithilfe von [ApiService] neu geschrieben:

// =========================================================================
// common/login-bar.ts - Login / Logout in einer Leiste
// -------------------------------------------------------------------------
// Das Formular aus Beispiel 23, auf eine Leiste reduziert und mit
// ApiService neu geschrieben. Die Komponente löst userChange mit dem angemeldeten
// Benutzer (oder null) bei jeder Änderung aus - auch beim
// Start, nachdem GET /api/auth/me abgefragt wurde.
//
// ViewEncapsulation.None: Die Stile der Komponente gelten für die GESAMTE
// Seite. Hier notwendig: Das <svg> des Captchas, das per [innerHTML] eingefügt wird,
// trägt nicht die Attribute, die der "gekapselte" Stil von Angular verlangt.
// =========================================================================

import { Component, computed, inject, output, signal, ViewEncapsulation } from '@angular/core';
import { FormsModule } from '@angular/forms';
import { DomSanitizer } from '@angular/platform-browser';
import { ApiService } from './api.service';
import { ApiError } from './api-error';
import { Captcha, User } from './types';

@Component({
  selector: 'app-login-bar',
  imports: [FormsModule],
  encapsulation: ViewEncapsulation.None,
  styles: `
    .login-bar-captcha svg {
      display: block;
      height: 32px;
      width: auto;
    }
  `,
  template: `
    <div class="alert alert-secondary d-flex flex-wrap align-items-center gap-2 py-2">
      @if (user(); as u) {
        <span>Logged in: <strong>{{ u.name }}</strong> <span class="badge text-bg-primary ms-1">{{ u.role }}</span></span>
        <button class="btn btn-sm btn-outline-secondary ms-auto" (click)="logOut()">Log out</button>
      } @else {
        <form class="d-flex flex-wrap align-items-center gap-2 w-100" (ngSubmit)="logIn()">
          <input name="login" class="form-control form-control-sm w-auto" placeholder="login" autocomplete="username"
                 [(ngModel)]="login">
          <input name="password" type="password" class="form-control form-control-sm w-auto" placeholder="password"
                 autocomplete="current-password" [(ngModel)]="password">
          <div class="login-bar-captcha" [innerHTML]="svg()"></div>
          <input name="captcha" class="form-control form-control-sm w-auto" placeholder="captcha" autocomplete="off" size="8"
                 [(ngModel)]="captchaAnswer">
          <button class="btn btn-sm btn-primary">Log in</button>
          @if (error()) {
            <span class="text-danger small">{{ error() }}</span>
          }
        </form>
      }
    </div>
  `,
})
export class LoginBar {
  readonly userChange = output<User | null>();

  private readonly api = inject(ApiService);
  private readonly sanitizer = inject(DomSanitizer);
  protected readonly user = signal<User | null>(null);
  private readonly captcha = signal<Captcha | null>(null);
  protected readonly svg = computed(() => this.sanitizer.bypassSecurityTrustHtml(this.captcha()?.svg ?? ''));
  protected readonly login = signal('admin');
  protected readonly password = signal('');
  protected readonly captchaAnswer = signal('');
  protected readonly error = signal<string | null>(null);

  constructor() {
    this.start();
  }

  private async start(): Promise<void> {
    try {
      this.change(await this.api.get<User>('/auth/me'));
    } catch {
      this.change(null); // 401: niemand ist angemeldet
      await this.newCaptcha().catch(() => this.error.set('Is the JSON server running (port 8080)?'));
    }
  }

  private async newCaptcha(): Promise<void> {
    this.captcha.set(await this.api.get<Captcha>('/captcha'));
    this.captchaAnswer.set('');
  }

  private change(u: User | null): void {
    this.user.set(u);
    this.userChange.emit(u);
  }

  protected async logIn(): Promise<void> {
    this.error.set(null);
    try {
      const u = await this.api.post<User>('/auth/login', {
        login: this.login(),
        password: this.password(),
        captchaId: this.captcha()?.id,
        captcha: this.captchaAnswer(),
      });
      this.password.set('');
      this.change(u);
    } catch (e) {
      this.error.set(e instanceof ApiError ? `${e.statusCode} ${e.key}` : String(e));
      await this.newCaptcha();
    }
  }

  protected async logOut(): Promise<void> {
    await this.api.post('/auth/logout');
    this.change(null);
    await this.newCaptcha();
  }
}
  • Zeile 56: Die Komponente sendet [userChange] mit dem angemeldeten Benutzer (oder [null]) bei jeder Änderung, auch beim Start;
  • Zeile 74: Mit [ApiService] passt eine Anfrage in eine einzige Zeile; im Fehlerfall (401) springt der Ablauf zu [catch];
  • Zeile 103: [instanceof] unterscheidet einen Fehler der API von einer anderen Anomalie;
  • Zeile 24: [ViewEncapsulation.None]: Die Stile der Komponente gelten für die gesamte Seite. Standardmäßig [Angular] beschränkt die Stile einer Komponente auf ihr Template, indem es ihren Elementen spezifische Attribute hinzufügt. Das [<svg>] , das durch [[innerHTML]] eingefügt wird, hat diese Attribute nicht: Ohne diese Option würde die Regel in den Zeilen 26–30 nicht darauf angewendet.

8.3.7. Die Konfiguration

// =========================================================================
// 24-api-service/src/app/app.config.ts
// -------------------------------------------------------------------------
// provideHttpClient(withInterceptors([...])): HttpClient wird standardmäßig
// jeder Anwendung bereitgestellt; er wird nur deklariert, um ihn zu KONFIGURIEREN, hier durch
// Hinzufügen des Interceptors, der die Fehler in ApiError umwandelt.
// =========================================================================

import { ApplicationConfig } from '@angular/core';
import { provideHttpClient, withInterceptors } from '@angular/common/http';
import { errorsInterceptor } from '../../../common/errors.interceptor';

export const appConfig: ApplicationConfig = {
  providers: [provideHttpClient(withInterceptors([errorsInterceptor]))],
};
  • Zeile 14: [HttpClient] wird standardmäßig bereitgestellt; er wird nur deklariert, um ihn zu konfigurieren, in diesem Fall durch Hinzufügen des Interceptors.

8.3.8. Die Seite

// =========================================================================
// 24-api-service/src/app/app.ts - ein Terminkalender mit der API-Zugriffsschicht
// -------------------------------------------------------------------------
// Melden Sie sich an (obere Leiste), wählen Sie einen Arzt und einen Tag: 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 ist maßgeblich.
//
// httpResource: eine GET-Anfrage, beschrieben durch eine Funktion, die
// Signale liest (hier doctorId und day). Angular sendet sie beim Start und
// SENDET SIE ERNEUT, sobald sich eines dieser Signale ändert. Das Ergebnis ist ein
// Objekt aus Signalen: value() (die Antwort), isLoading(), error()... und
// reload(), um sie bei Bedarf erneut zu senden.
// =========================================================================

import { Component, computed, effect, inject, signal } from '@angular/core';
import { httpResource } from '@angular/common/http';
import { FormsModule } from '@angular/forms';
import { LoginBar } from '../../../common/login-bar';
import { ApiError } from '../../../common/api-error';
import { Schedule, ScheduleSlot, Person, User } from '../../../common/types';
import { RdvMedecinsService } from './rdvmedecins.service';

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')}`;
}

@Component({
  selector: 'app-root',
  imports: [FormsModule, LoginBar],
  templateUrl: './app.html',
})
export class App {
  private readonly rdv = inject(RdvMedecinsService);

  protected readonly user = signal<User | null>(null);
  protected readonly doctors = signal<Person[]>([]);
  protected readonly clients = signal<Person[]>([]);
  protected readonly doctorId = signal<number | null>(null);
  protected readonly day = signal(tomorrow());
  protected readonly clientId = signal<number | null>(null);
  protected readonly message = signal<{ type: 'success' | 'danger'; text: string } | null>(null);

  protected readonly isManager = computed(() => this.user() !== null && this.user()?.role !== 'USER');

  // undefined: keine Anfrage (kein Arzt gewählt oder niemand angemeldet)
  protected readonly schedule = httpResource<Schedule>(() => {
    const id = this.doctorId();
    return id === null || this.user() === null ? undefined : this.rdv.scheduleRequest(id, this.day());
  });

  // der Fehler der letzten Anfrage des Terminkalenders als ApiError
  protected readonly scheduleError = computed(() => {
    const e = this.schedule.error();
    return e instanceof ApiError ? `${e.statusCode} ${e.key}` : null;
  });

  constructor() {
    // eine neue Wahl von Arzt oder Tag löscht die vorherige Meldung
    effect(() => {
      this.doctorId();
      this.day();
      this.message.set(null);
    });
  }

  protected 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 API-Fehler wird zu einer Meldung (mangels Wörterbuch hier sein key)
  private report(e: unknown): void {
    this.message.set({ type: 'danger', text: e instanceof ApiError ? `${e.statusCode} ${e.key}` : String(e) });
  }

  // Login / Logout: wir (neu) laden, was diese Rolle sehen darf
  protected async onUserChange(u: User | null): Promise<void> {
    this.user.set(u);
    this.doctors.set([]);
    this.clients.set([]);
    if (u === null) {
      return;
    }
    try {
      this.doctors.set(await this.rdv.getDoctors());
      // die Patientenliste: nur für ADMIN und DOCTOR (ein USER erhielte 403)
      this.clients.set(this.isManager() ? await this.rdv.getClients() : []);
    } catch (e) {
      this.report(e);
    }
  }

  protected async book(c: ScheduleSlot): Promise<void> {
    try {
      await this.rdv.book(this.day(), c.id, this.isManager() ? (this.clientId() ?? undefined) : undefined);
      this.message.set({ type: 'success', text: `Slot ${this.timeRange(c)} booked.` });
    } catch (e) {
      this.report(e);
    }
    this.schedule.reload();
  }

  protected async cancel(c: ScheduleSlot): Promise<void> {
    try {
      await this.rdv.cancelAppointment(c.appointmentId as number);
      this.message.set({ type: 'success', text: `Appointment of ${this.timeRange(c)} cancelled.` });
    } catch (e) {
      this.report(e);
    }
    this.schedule.reload();
  }
}
  • Zeile 45: ADMIN oder DOCTOR;
  • Zeilen 48–51: [httpResource] beschreibt eine GET-Anfrage über eine Funktion, die Signale liest (hier [doctorId], [day] und [user]). [Angular] sendet die Anfrage zunächst und sendet sie erneut, sobald sich eines dieser Signale ändert. Die Funktion gibt [undefined] zurück, wenn keine Anfrage zu senden ist. Das Ergebnis ist eine Sammlung von Signalen: [value()] (die Antwort), [isLoading()], [error()], [hasValue()] … und eine Methode, [reload()], um die Anfrage bei Bedarf erneut zu senden. Läuft beim Ändern der Signale noch eine Anfrage, wird sie verworfen, wie bei [switchMap] (Beispiel 19);
  • Zeilen 54–57: der Fehler der letzten Terminkalender-Anfrage. Anfragen von [httpResource] laufen ebenfalls durch den Interceptor: Der Fehler ist ein [ApiError];
  • Zeilen 61–65: eine Funktion, die die vorherige Meldung löscht, wenn sich der Arzt oder der Tag ändert;
  • Zeilen 79–93: Jedes Mal, wenn sich ein Benutzer an- oder abmeldet, wird das (neu) geladen, was diese Rolle einsehen darf. Ein Patient würde für die Kundenliste einen 403-Fehler erhalten: Wir fordern sie gar nicht erst an;
  • Zeilen 95–103: eine Reservierung, gefolgt – UNABHÄNGIG VOM ERGEBNIS – von einem Neuladen des Terminkalenders (Zeile 102). Der Stand des Servers ist maßgeblich: Wurde der Zeitraum in der Zwischenzeit von jemand anderem belegt, zeigt der aktualisierte Terminkalender dies an;
  • Zeile 97: Ein Administrator reserviert für den ausgewählten Patienten; ein Patient reserviert für sich selbst.
<div class="container py-4">
  <h1 class="h3 mb-3">Example 24 - an API access layer</h1>
  <app-login-bar (userChange)="onUserChange($event)" />

  @if (user()) {
    <div class="row g-2 mb-3">
      <div class="col-sm-5">
        <select class="form-select" [(ngModel)]="doctorId">
          <option [ngValue]="null" disabled>-- choose a doctor --</option>
          @for (m of doctors(); track m.id) {
            <option [ngValue]="m.id">{{ m.title }} {{ m.firstName }} {{ m.lastName }}</option>
          }
        </select>
      </div>
      <div class="col-sm-3"><input type="date" class="form-control" [(ngModel)]="day"></div>
      @if (isManager()) {
        <div class="col-sm-4">
          <select class="form-select" [(ngModel)]="clientId">
            <option [ngValue]="null">-- patient to book for --</option>
            @for (c of clients(); track c.id) {
              <option [ngValue]="c.id">{{ c.title }} {{ c.firstName }} {{ c.lastName }}</option>
            }
          </select>
        </div>
      }
    </div>

    @if (message(); as m) {
      <div class="alert" [class]="'alert-' + m.type">{{ m.text }}</div>
    }
    @if (scheduleError()) {
      <div class="alert alert-danger">{{ scheduleError() }}</div>
    }
    @if (schedule.isLoading()) {
      <p class="small text-muted">loading the schedule...</p>
    }

    <!-- hasValue(): eine Antwort liegt vor (value() ist nicht undefined) -->
    @if (schedule.hasValue()) {
      @let a = schedule.value();
      <!-- info: der vom Server gesendete Schlüssel, wenn ein Patient bereits einen bevorstehenden Termin hat -->
      @if (a.info) {
        <div class="alert alert-info">{{ a.info }}</div>
      }
      <table class="table table-sm align-middle">
        <caption class="caption-top">Schedule of {{ a.day }} - {{ a.doctor.title }} {{ a.doctor.firstName }} {{ a.doctor.lastName }}</caption>
        <tbody>
          @for (c of a.slots; track c.id) {
            <tr>
              <td>{{ timeRange(c) }}</td>
              <td>
                @if (c.free) {
                  <span class="badge text-bg-success">Free</span>
                } @else if (c.patient; as p) {
                  <span class="badge" [class]="c.mine ? 'text-bg-primary' : 'text-bg-secondary'">{{ p.title }} {{ p.firstName }} {{ p.lastName }}</span>
                } @else {
                  <span class="badge text-bg-secondary">Booked</span>
                }
              </td>
              <td class="text-end">
                <!-- die Buttons folgen den vom Server berechneten Rechten -->
                @if (c.bookable) {
                  <button class="btn btn-sm btn-outline-success" (click)="book(c)">Book</button>
                }
                @if (c.appointmentId !== null) {
                  <button class="btn btn-sm btn-outline-danger" (click)="cancel(c)">Cancel</button>
                }
              </td>
            </tr>
          }
        </tbody>
      </table>
    }
  }
</div>
  • Zeile 3: die Anmeldeleiste;
  • Zeile 34: [isLoading()]: Eine Anfrage läuft;
  • Zeile 39: [hasValue()]: Eine Antwort liegt vor;
  • Zeile 40: [@let] verhindert, dass [schedule.value()] wiederholt wird;
  • Zeile 57: ein belegter Zeitraum, für den der Server den Patienten nicht gesendet hat (aus Sicht eines Patienten);
  • Zeilen 62–67: Die Schaltflächen folgen den vom Server berechneten Berechtigungen.

[npm start 24-api-service]. Der Administrator reserviert den Zeitraum 8:40 Uhr für Alice DURAND:

Image

Derselbe Terminkalender aus Sicht des Patienten Martin: Der Zeitraum ist reserviert, ohne Angabe eines Patientennamens.

Image

8.4. Beispiel 25: Vom Server zurückgegebene Fehler

Dieses Beispiel zeigt die Verwaltung von Kunden durch den Administrator. Das Formular führt im Browser keine Validierung durch: Alles wird an den Server gesendet, der – im Fall einer Ablehnung – mit einem 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" }

Sie müssen dann die allgemeine Meldung anzeigen und den Fehler für jedes Feld unterhalb dieses Feldes platzieren, in der Sprache des Benutzers.

Die Wörterbücher enthalten die Fehlercodes des Servers:

{
  "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."
  }
}
{
  "FORM": {
    "TITLE_ADD": "Add a patient",
    "TITLE_EDIT": "Edit a patient",
    "TITLE": "Title",
    "FIRSTNAME": "First name",
    "LASTNAME": "Last name",
    "LOGIN": "Login",
    "PASSWORD": "Password",
    "SAVE": "Save",
    "CANCEL": "Cancel",
    "EDIT": "Edit",
    "DELETE": "Delete",
    "DELETE_CONFIRM": "Delete patient {{name}}, their account and their appointments?",
    "ADDED": "Patient {{name}} has been added (login: {{login}}).",
    "UPDATED": "Patient {{name}} has been updated.",
    "DELETED": "Patient {{name}} has been deleted.",
    "ADMIN_ONLY": "Log in with the admin account: only the ADMIN role manages patients."
  },
  "ERRORS": {
    "INVALID_FORM": "The form contains errors.",
    "INVALID_TITLE": "Choose a title from the list.",
    "FIRSTNAME_REQUIRED": "First name is required.",
    "FIRSTNAME_TOO_LONG": "First name must not exceed 20 characters.",
    "LASTNAME_REQUIRED": "Last name is required.",
    "LASTNAME_TOO_LONG": "Last name must not exceed 20 characters.",
    "INVALID_LOGIN": "30 characters max: unaccented lowercase letters, digits, dot, hyphen, underscore.",
    "PASSWORD_TOO_LONG": "Password must not exceed 72 characters.",
    "LOGIN_TAKEN": "This login is already used by another account.",
    "PATIENT_ALREADY_EXISTS": "A patient with this first and last name already exists.",
    "PATIENT_NOT_FOUND": "This patient does not exist (anymore).",
    "CONCURRENT_UPDATE": "This record was changed meanwhile by another user. Reload it before trying again.",
    "FORBIDDEN": "Your role does not allow this action.",
    "AUTH_REQUIRED": "Please log in first.",
    "SESSION_EXPIRED": "Your session has expired: please log in again.",
    "SERVER_UNREACHABLE": "The server does not respond.",
    "SERVER_ERROR": "An unexpected error occurred."
  }
}
// =========================================================================
// 25-server-errors/src/app/i18n/i18n.ts - ngx-translate, wie in Beispiel 21
// =========================================================================

import { Provider } from '@angular/core';
import { provideTranslateLoader, provideTranslateService, TranslateLoader, TranslationObject } from '@ngx-translate/core';
import { Observable, of } from 'rxjs';
import fr from './fr.json';
import en from './en.json';

class DictionariesLoader implements TranslateLoader {
  getTranslation(language: string): Observable<TranslationObject> {
    return of(language === 'en' ? en : fr);
  }
}

export function provideI18n(): Provider[] {
  return provideTranslateService({ loader: provideTranslateLoader(DictionariesLoader), fallbackLang: 'en', lang: 'en' });
}

Die Anwendungskonfiguration vereint die in den vorherigen Beispielen vorgestellten Elemente:

// =========================================================================
// 25-server-errors/src/app/app.config.ts
// -------------------------------------------------------------------------
//   - HttpClient und der Fehler-Interceptor (siehe Beispiel 24);
//   - ngx-translate (siehe Beispiel 21);
//   - die Bootstrap-Klassen der Felder (siehe Beispiel 07). Hier gibt es kein
//     "touched": Ein Feld erhält einen roten Rand, sobald es einen Fehler trägt,
//     also sobald der SERVER einen gemeldet hat.
// =========================================================================

import { ApplicationConfig } from '@angular/core';
import { provideHttpClient, withInterceptors } from '@angular/common/http';
import { provideSignalFormsConfig } from '@angular/forms/signals';
import { errorsInterceptor } from '../../../common/errors.interceptor';
import { provideI18n } from './i18n/i18n';

export const appConfig: ApplicationConfig = {
  providers: [
    provideHttpClient(withInterceptors([errorsInterceptor])),
    provideI18n(),
    provideSignalFormsConfig({ classes: { 'is-invalid': (field) => field.state().invalid() } }),
  ],
};
  • Zeile 19: der HTTP-Client und sein Interceptor (Beispiel 24);
  • Zeile 20: [ngx-translate] (Beispiel 21);
  • Zeile 21: die [Bootstrap]-Feldklassen (Beispiel 07). Hier wird ein Feld rot hervorgehoben, sobald es einen Fehler enthält – das heißt, sobald der Server einen gemeldet hat.

Die Seite:

// =========================================================================
// 25-server-errors/src/app/app.ts - die Fehler des SERVERS anzeigen
// -------------------------------------------------------------------------
// Die Verwaltung der Kunden (Admin-Konto). Dieses Formular
// führt ABSICHTLICH keine Validierung im Browser durch: Sein Schema ist leer.
// Alles wird an den Server gesendet, der im Fall einer Ablehnung mit einem JSON-Fehler
// antwortet (vom Interceptor 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)
//
// submit(form, action): die Aktion sendet das Modell an den Server. Liefert sie
// FEHLER (ein Array) zurück, hängen die Signal-Formulare diese
// an die bezeichneten Felder (fieldTree): Sie erscheinen in f.lastName().errors(),
// wie die Fehler eines Validators. Ihre Meldung ist hier der vom
// Server gesendete KEY, den das Template übersetzt (ngx-translate). Probieren Sie: einen leeren
// Nachnamen, einen Titel "Dr", einen Namensvetter (Alice DURAND), einen bereits vergebenen Login
// (martin), denselben Datensatz in zwei Tabs geändert...
// =========================================================================

import { Component, computed, inject, signal } from '@angular/core';
import { FormField, form, submit, ValidationError } from '@angular/forms/signals';
import { TranslatePipe, TranslateService } from '@ngx-translate/core';
import { ApiService } from '../../../common/api.service';
import { LoginBar } from '../../../common/login-bar';
import { ApiError } from '../../../common/api-error';
import { Person, User } from '../../../common/types';
// der Bestätigungsdialog aus Beispiel 16, unverändert wiederverwendet
import { ConfirmationService } from '../../../16-confirmation/src/app/confirmation/confirmation.service';
import { ConfirmDialog } from '../../../16-confirmation/src/app/confirmation/confirm-dialog';

interface ClientInput {
  title: string;
  firstName: string;
  lastName: string;
  login: string;
  password: string;
  version: number;
}

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

@Component({
  selector: 'app-root',
  imports: [FormField, TranslatePipe, LoginBar, ConfirmDialog],
  templateUrl: './app.html',
})
export class App {
  private readonly api = inject(ApiService);
  private readonly confirmation = inject(ConfirmationService);
  protected readonly translate = inject(TranslateService);

  protected readonly user = signal<User | null>(null);
  protected readonly clients = signal<Person[]>([]);
  protected readonly isAdmin = computed(() => this.user()?.role === 'ADMIN');

  // das Formular: editedId === null -> Anlegen, andernfalls Aktualisieren
  protected readonly editedId = signal<number | null>(null);
  protected readonly model = signal<ClientInput>({ ...EMPTY });
  protected readonly f = form(this.model); // kein Validator: der Server validiert
  // die allgemeine Meldung des letzten Fehlers und die eines Erfolgs
  protected readonly pageError = signal<ApiError | null>(null);
  protected readonly success = signal<{ key: string; params: Record<string, string> } | null>(null);

  protected async onUserChange(u: User | null): Promise<void> {
    this.user.set(u);
    this.clients.set([]);
    if (u?.role === 'ADMIN') {
      await this.reload();
    }
  }

  private async reload(): Promise<void> {
    this.clients.set(await this.api.get<Person[]>('/clients'));
  }

  protected newForm(): void {
    this.editedId.set(null);
    this.model.set({ ...EMPTY });
    this.f().reset(); // der Zustand der Felder (und ihre Fehler) beginnt bei null
    this.clearMessages();
  }

  protected edit(c: Person): void {
    this.editedId.set(c.id);
    // die zusammen 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
    this.model.set({ title: c.title, firstName: c.firstName, lastName: c.lastName, login: c.login ?? '', password: '', version: c.version });
    this.f().reset();
    this.clearMessages();
  }

  private clearMessages(): void {
    this.pageError.set(null);
    this.success.set(null);
  }

  // der Fehler JEDES Felds, vom Server zurückgegeben -> ein Fehler des Formulars
  private fieldErrors(e: ApiError): ValidationError.WithOptionalFieldTree[] {
    const fields = Object.keys(this.model()) as (keyof ClientInput)[];
    return Object.entries(e.fields)
      .filter(([field]) => fields.includes(field as keyof ClientInput))
      .map(([field, key]) => ({ kind: 'server', message: key, fieldTree: this.f[field as keyof ClientInput] }));
  }

  protected async save(event: SubmitEvent): Promise<void> {
    event.preventDefault();
    this.clearMessages();
    const id = this.editedId();
    await submit(this.f, async () => {
      try {
        const body = this.model();
        const client =
          id === null
            ? await this.api.post<Person>('/clients', body)
            : await this.api.put<Person>(`/clients/${id}`, body);
        this.newForm(); // Formular geleert, Meldungen gelöscht...
        // ... außer dieser
        this.success.set({
          key: id === null ? 'FORM.ADDED' : 'FORM.UPDATED',
          params: { name: `${client.firstName} ${client.lastName}`, login: client.login ?? '' },
        });
        await this.reload();
        return null;
      } catch (e) {
        if (!(e instanceof ApiError)) {
          throw e;
        }
        this.pageError.set(e); // die allgemeine Meldung
        return this.fieldErrors(e); // der Fehler jedes Felds
      }
    });
  }

  protected async remove(c: Person): Promise<void> {
    const name = `${c.firstName} ${c.lastName}`;
    if (!(await this.confirmation.confirm(this.translate.instant('FORM.DELETE_CONFIRM', { name })))) {
      return;
    }
    this.clearMessages();
    try {
      await this.api.delete(`/clients/${c.id}`);
      this.success.set({ key: 'FORM.DELETED', params: { name } });
    } catch (e) {
      this.pageError.set(e instanceof ApiError ? e : null);
    }
    await this.reload();
  }
}
  • Zeilen 30–31: das Bestätigungsfenster aus Beispiel 16, unverändert wiederverwendet: Eine gut entworfene Komponente ist wiederverwendbar;
  • Zeile 61: ein Signal-Formular (Beispiel 06), ohne Schema: kein Validator;
  • Zeilen 63–64: die allgemeine Meldung zum letzten Fehler und die Erfolgsmeldung;
  • Zeilen 85–92: Um einen Datensatz zu bearbeiten, kopieren Sie seine Werte in das Formular, einschließlich der Versionsnummer: Der Datensatz wird mit der Änderung aktualisiert (optimistisches Sperren). [reset()] setzt den Zustand der Felder und ihre Fehler zurück;
  • Zeilen 107–134: das Speichern des Datensatzes. [submit(form, action)] führt die Aktion aus, die das Formular an den Server sendet: POST für eine Erstellung (Zeile 116), PUT für eine Änderung (Zeile 117). Während der Ausführung ist [f().submitting()] true;
  • Zeile 125: [null]: kein Fehler;
  • Zeilen 130–131: Bei einer Ablehnung wird die allgemeine Meldung beibehalten, und die Feldfehler werden zurückgegeben. Das Validierungssystem des Formulars ordnet sie dann den bezeichneten Feldern zu: Sie erscheinen in [f.lastName().errors()], genau wie Validatorfehler; sie verschwinden, sobald der Benutzer das Feld ändert;
  • Zeilen 100–105: die Umwandlung. Jeder Fehler benennt sein Feld ([fieldTree], Zeile 104); seine Meldung ist der vom Server gesendete Schlüssel . Zeile 103 ignoriert ein im Formular unbekanntes Feld;
  • Zeile 138: [translate.instant(key, params)]: die Übersetzung eines Schlüssels im Code;
  • Zeile 146: Auch das Löschen eines Kunden kann abgelehnt werden.
<div class="container py-4">
  <div class="d-flex justify-content-between align-items-center mb-3">
    <h1 class="h3 mb-0">Example 25 - the errors returned by the server</h1>
    <select #language class="form-select form-select-sm w-auto" (change)="translate.use(language.value)">
      <option value="fr">FR</option>
      <option value="en" selected>EN</option>
    </select>
  </div>
  <app-login-bar (userChange)="onUserChange($event)" />
  @if (user() && !isAdmin()) {
    <p class="alert alert-warning">{{ 'FORM.ADMIN_ONLY' | translate }}</p>
  }

  @if (isAdmin()) {
    <div class="row g-4">
      <div class="col-lg-6">
        <table class="table table-sm align-middle">
          <tbody>
            @for (c of clients(); track c.id) {
              <tr>
                <td>{{ c.title }} {{ c.firstName }} {{ c.lastName }}</td>
                <td><code>{{ c.login }}</code></td>
                <td class="text-end text-nowrap">
                  <button class="btn btn-sm btn-outline-primary me-1" (click)="edit(c)">{{ 'FORM.EDIT' | translate }}</button>
                  <button class="btn btn-sm btn-outline-danger" (click)="remove(c)">{{ 'FORM.DELETE' | translate }}</button>
                </td>
              </tr>
            }
          </tbody>
        </table>
      </div>

      <div class="col-lg-6">
        <form class="card p-3" novalidate (submit)="save($event)">
          <h2 class="h5">{{ (editedId() === null ? 'FORM.TITLE_ADD' : 'FORM.TITLE_EDIT') | translate }}</h2>
          <div class="mb-2">
            <label class="form-label" for="title">{{ 'FORM.TITLE' | translate }}</label>
            <!-- eine Option "Dr", die der Server ablehnen wird: um ERRORS.INVALID_TITLE zu sehen -->
            <select id="title" class="form-select" [formField]="f.title">
              <option>Mr</option><option>Mme</option><option>Melle</option><option>Dr</option>
            </select>
            <!-- die Meldung eines Server-Fehlers ist ein KEY: wir übersetzen ihn -->
            <div class="invalid-feedback">{{ f.title().errors()[0]?.message ?? '' | translate }}</div>
          </div>
          <div class="row g-2 mb-2">
            <div class="col-sm-6">
              <label class="form-label" for="firstName">{{ 'FORM.FIRSTNAME' | translate }}</label>
              <input id="firstName" class="form-control" [formField]="f.firstName">
              <div class="invalid-feedback">{{ f.firstName().errors()[0]?.message ?? '' | translate }}</div>
            </div>
            <div class="col-sm-6">
              <label class="form-label" for="lastName">{{ 'FORM.LASTNAME' | translate }}</label>
              <input id="lastName" class="form-control" [formField]="f.lastName">
              <div class="invalid-feedback">{{ f.lastName().errors()[0]?.message ?? '' | translate }}</div>
            </div>
          </div>
          <div class="row g-2 mb-3">
            <div class="col-sm-6">
              <label class="form-label" for="login">{{ 'FORM.LOGIN' | translate }}</label>
              <input id="login" class="form-control" [formField]="f.login">
              <div class="invalid-feedback">{{ f.login().errors()[0]?.message ?? '' | translate }}</div>
            </div>
            <div class="col-sm-6">
              <label class="form-label" for="password">{{ 'FORM.PASSWORD' | translate }}</label>
              <input id="password" type="password" class="form-control" autocomplete="new-password" [formField]="f.password">
              <div class="invalid-feedback">{{ f.password().errors()[0]?.message ?? '' | translate }}</div>
            </div>
          </div>
          <div class="d-flex gap-2">
            <!-- submitting(): true, solange die Aktion von submit() läuft -->
            <button class="btn btn-primary" [disabled]="f().submitting()">{{ 'FORM.SAVE' | translate }}</button>
            <button type="button" class="btn btn-secondary" (click)="newForm()">{{ 'FORM.CANCEL' | translate }}</button>
          </div>
          @if (success(); as s) {
            <div class="alert alert-success mt-3 mb-0">{{ s.key | translate: s.params }}</div>
          }
          <!-- die allgemeine Meldung und der HTTP-Status, zum Verständnis -->
          @if (pageError(); as e) {
            <div class="alert alert-danger mt-3 mb-0">
              {{ e.key | translate: e.params }} <span class="small text-muted">({{ e.statusCode }} {{ e.key }})</span>
            </div>
          }
        </form>
      </div>
    </div>
  }
</div>
<app-confirm-dialog />
  • Zeile 4: Sprachauswahl;
  • Zeile 40: ein Titel „Dr.“, den der Server ablehnen wird; siehe [ERRORS.INVALID_TITLE];
  • Zeile 43 und folgende: unter jedem Feld der erste Fehler; seine Meldung ist ein Schlüssel, den die Pipe [translate] übersetzt. [?? '']: kein Fehler, kein Text;
  • Zeile 71: Die Schaltfläche ist während des Absendens deaktiviert;
  • Zeile 80: die allgemeine Meldung in der aktuellen Sprache, mit ihren Parametern, gefolgt vom HTTP-Status und vom Schlüssel zur Verdeutlichung;
  • Zeile 88: das Bestätigungsfenster.

Ein Wechsel der Sprache übersetzt auch bereits angezeigte Fehlermeldungen neu: Wir haben nur die Schlüssel behalten.

[npm start 25-server-errors]; als admin angemeldet, senden wir den Titel „Dr“, einen zu langen Vornamen, einen leeren Nachnamen und einen ungültigen Benutzernamen ab:

Image

Wir beginnen mit einem leeren Formular: der Titel „Dr“, der Vorname „Jean“ und ein leerer Nachname. Der Server lehnt den Titel und den Nachnamen ab; wir korrigieren dann den Titel und geben einen Nachnamen ein: Die Fehler dieser beiden Felder verschwinden sofort, ohne dass erneut abgesendet werden muss. Die allgemeine Meldung bleibt bis zum nächsten Absenden angezeigt:

Image

Ein Namensvetter (Alice DURAND existiert bereits): Der Server liefert eine 409-Antwort und markiert die Felder Vorname und Nachname. Der Benutzername „martin“, der bereits vergeben ist, wird nicht markiert: Der Server bricht bei der ersten verletzten Validierungsregel ab. Anschließend wechseln wir ins Französische: Die bereits angezeigten Meldungen werden neu übersetzt (der Seitentitel und die Anmeldeleiste, die auf Englisch geschrieben sind, nicht):

Image

Versuchen Sie auch, denselben Datensatz in zwei Tabs zu bearbeiten: Das zweite Speichern erhält [ERRORS.CONCURRENT_UPDATE].