Skip to content

8. Kommunikation mit dem Server

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

8.1. Beispiel 17: Eine erste HTTP-Anfrage

8.1.1. Der Vite-Proxy

Die Beispielseite stammt von http://localhost:5173 (dem [Vite]-Server); die API liegt 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 heißt CORS). Außerdem [fetch] sendet keine Cookies (und damit nicht das Token) an einen anderen Ursprung, sofern dies nicht angefordert wird ([credentials: 'include']) UND der Server es ebenfalls über CORS akzeptiert.

Anstatt den Server für andere Ursprünge zu öffnen, leiten wir die Anfragen an die API über den Vite-Server um. Das ist der Proxy, der in [vite.config.ts] deklariert ist:

1
2
3
4
5
6
  server: {
    port: 5173,
    proxy: {
      '/api': 'http://localhost:8080',
    },
  },

Der Browser sendet [GET http://localhost:5173/api/captcha]; [Vite] leitet die Anfrage an [http://localhost:8080/api/captcha] weiter und sendet 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 kein [Vite] 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

<!--
  =========================================================================
  17-fetch/src/App.vue - a first HTTP request to the server
  -------------------------------------------------------------------------
  The RdvMedecins JSON server must be running (port 8080). We ask it for
  a captcha: GET /api/captcha -> { "id": "...", "svg": "<svg ...>" }.

    - fetch(url): the browser function that sends an HTTP request.
      It returns a PROMISE: we wait for the response with await;
    - response.ok: true for a 2xx code; response.json() reads the JSON
      body (another promise);
    - the address is RELATIVE (/api/captcha): the request goes to the
      server of the page, Vite (port 5173), which forwards it to the JSON server
      (port 8080) thanks to its proxy (see vite.config.ts);
    - three states to display: in progress, succeeded, failed.
  =========================================================================
-->
<script setup lang="ts">
import { onMounted, ref } from 'vue';

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

const captcha = ref<Captcha | null>(null);
const loading = ref(false);
const error = ref<string | null>(null);
const requestCount = ref(0);

async function load(): Promise<void> {
  loading.value = true;
  error.value = null;
  try {
    const response = await fetch('/api/captcha');
    requestCount.value++;
    if (!response.ok) {
      // der Server hat geantwortet, aber mit einem Fehler (4xx, 5xx) - oder es ist
      // Vite, das mit 502/504 antwortet, weil der JSON-Server gestoppt ist
      throw new Error(`the server responded ${response.status} ${response.statusText}`);
    }
    captcha.value = (await response.json()) as Captcha;
  } catch (e) {
    // fetch selbst schlägt fehl, wenn keine Antwort eintrifft (Netzwerk ausgefallen ...)
    error.value = e instanceof Error ? e.message : String(e);
    captcha.value = null;
  } finally {
    loading.value = false;
  }
}

// bei der ersten Anzeige wird ein CAPTCHA geladen
onMounted(load);
</script>

<template>
  <div class="container py-4" style="max-width: 640px">
    <h1 class="h3 mb-3">Example 17 - a first HTTP request</h1>
    <div class="card p-3">
      <p v-if="loading" class="text-muted">Loading...</p>
      <div v-else-if="error" class="alert alert-danger mb-3">
        Unable to get a captcha: {{ error }}.<br>
        Is the RdvMedecins JSON server running (port 8080)?
      </div>
      <template v-else-if="captcha">
        <!-- v-html: inserts a string as HTML (here, the SVG image).
             To be used ONLY for safe content: this SVG is built by
             OUR server. With user input, v-html would open
             the door to script injection ({{ }}, for its part, escapes everything). -->
        <div class="captcha mb-2" v-html="captcha.svg"></div>
        <p class="small text-muted">id: <code>{{ captcha.id }}</code></p>
      </template>
      <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>
</template>

<style scoped>
/* :deep(svg): Die Regel erreicht das von v-html eingefügte <svg>, das "scoped" sonst ignorieren würde */
.captcha :deep(svg) {
  border: 1px solid #dee2e6;
  border-radius: 0.375rem;
}
</style>
  • Zeile 22: das Format der Antwort von [GET /api/captcha];
  • Zeilen 27–29: die drei Zustände einer Anfrage: in Bearbeitung, erfolgreich (das CAPTCHA) und Fehler;
  • Zeile 36: [fetch(url)], die Browser-Funktion, die eine HTTP-Anfrage sendet. Sie liefert ein Promise; [await] hält die Funktion [async] an, bis das Promise aufgelöst ist, ohne die Seite zu blockieren. Die Adresse ist relativ: Die Anfrage geht an den Server der Seite, [Vite], der sie weiterleitet;
  • Zeile 38: [fetch] meldet KEINEN Fehler, wenn der Server eine 404- oder 500-Antwort liefert: Es hat ja eine Antwort erhalten. Wir müssen selbst [response.ok] prüfen (true bei einem 2xx-Code). Wenn der JSON-Server nicht läuft, [Vite] antwortet mit einem 5xx-Fehler;
  • Zeile 43: [response.json()] liest den Body und wandelt ihn in ein Objekt um (noch ein Promise). [as Captcha] teilt [TypeScript] das Format des Objekts mit: Der Compiler kann nicht prüfen, was der Server senden wird;
  • Zeile 44: [fetch] selbst schlägt fehl, wenn keine Antwort eintrifft (Netzwerk ausgefallen);
  • Zeile 48: In jedem Fall ist die Anfrage nicht mehr in Bearbeitung;
  • Zeile 54: Bei der ersten Anzeige wird ein CAPTCHA geladen;
  • Zeile 71: [v-html] fügt eine Zeichenkette wie HTML ein (hier das SVG-Bild). Nur für sichere Inhalte verwenden: Dieses SVG wird von UNSEREM Server erzeugt. Bei Benutzereingaben [v-html] könnte das Einschleusen von Skripten in die Seite ermöglichen; die [{{ }}]-Token hingegen maskieren alles;
  • Zeile 82: [:deep(...)]: Eine [scoped]-Regel wirkt normalerweise nur auf Elemente des Templates; das von [<svg>] per [v-html] eingefügte Element gehört nicht dazu.

Image

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

<!--
  =========================================================================
  18-login/src/App.vue - logging in to the RdvMedecins server
  -------------------------------------------------------------------------
    1. at startup: GET /api/auth/me - are we already logged in?
       (after an F5, the client has forgotten everything; the server reads the cookie);
    2. login: POST /api/auth/login, JSON body { login, password,
       captchaId, captcha }. On success, the server sets the httpOnly
       cookie of the JWT token: our code NEVER sees it (try
       document.cookie in the console: it is not there);
    3. protected request: GET /api/doctors. The browser attaches the cookie
       by itself (same origin);
    4. logout: POST /api/auth/logout - the server deletes the cookie.

  A cookie belongs to a machine (localhost) and to a path (/api): it
  is therefore shared by ALL the examples. Once logged in here, examples 19 and 20
  are logged in too.
  =========================================================================
-->
<script setup lang="ts">
import { onMounted, reactive, ref } from 'vue';

interface User {
  login: string;
  name: string;
  role: 'ADMIN' | 'DOCTOR' | 'USER';
}
interface Doctor {
  id: number;
  title: string;
  firstName: string;
  lastName: 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 20 verwendet vue-i18n)
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.',
};

const user = ref<User | null>(null);
const doctors = ref<Doctor[]>([]);
const captcha = ref<{ id: string; svg: string } | null>(null);
const input = reactive({ login: 'admin', password: '', captcha: '' });
const error = ref<string | null>(null);
const ready = ref(false); // ist die initiale Prüfung abgeschlossen?

async function loadCaptcha(): Promise<void> {
  captcha.value = await (await fetch('/api/captcha')).json();
  input.captcha = '';
}

// 1. Wer ist angemeldet? 200 -> der Benutzer; 401 -> niemand
async function checkSession(): Promise<void> {
  const response = await fetch('/api/auth/me');
  if (response.ok) {
    user.value = await response.json();
    await loadDoctors();
  } else {
    await loadCaptcha();
  }
  ready.value = true;
}

// 2. Anmeldung
async function logIn(): Promise<void> {
  error.value = null;
  const response = await fetch('/api/auth/login', {
    method: 'POST',
    // der Server lehnt (415) einen POST ab, der nicht JSON ist
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
      login: input.login,
      password: input.password,
      captchaId: captcha.value?.id,
      captcha: input.captcha,
    }),
  });
  if (response.ok) {
    user.value = await response.json();
    input.password = '';
    await loadDoctors();
    return;
  }
  // ein Fehler: Der JSON-Body sagt, welcher; jedes Bild kann nur einmal verwendet werden
  const e = (await response.json()) as ApiError;
  error.value = `${response.status} - ${MESSAGES[e.key] ?? e.key}`;
  await loadCaptcha();
}

// 3. eine geschützte Anfrage
async function loadDoctors(): Promise<void> {
  const response = await fetch('/api/doctors');
  doctors.value = response.ok ? await response.json() : [];
}

// 4. Abmeldung
async function logOut(): Promise<void> {
  await fetch('/api/auth/logout', { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: '{}' });
  user.value = null;
  doctors.value = [];
  await loadCaptcha();
}

onMounted(() => {
  checkSession().catch(() => {
    error.value = 'Is the RdvMedecins JSON server running (port 8080)?';
    ready.value = true;
  });
});
</script>

<template>
  <div class="container py-4" style="max-width: 640px">
    <h1 class="h3 mb-3">Example 18 - logging in to the server</h1>
    <p v-if="!ready" class="text-muted">Checking the session...</p>

    <!-- angemeldet -->
    <div v-else-if="user" class="card p-3">
      <p>Logged in: <strong>{{ user.name }}</strong> ({{ user.login }}),
        role <span class="badge text-bg-primary">{{ user.role }}</span></p>
      <h2 class="h6">GET /api/doctors</h2>
      <ul>
        <li v-for="m in doctors" :key="m.id">{{ 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>

    <!-- nicht angemeldet: das Formular -->
    <form v-else class="card p-3" @submit.prevent="logIn">
      <div class="mb-2">
        <label class="form-label" for="login">Login</label>
        <input id="login" v-model="input.login" class="form-control" autocomplete="username">
      </div>
      <div class="mb-2">
        <label class="form-label" for="password">Password</label>
        <input id="password" v-model="input.password" type="password" class="form-control" autocomplete="current-password">
      </div>
      <div class="mb-3">
        <label class="form-label" for="captcha">Type the characters shown in the image</label>
        <div class="d-flex align-items-center gap-3 mb-2">
          <div v-if="captcha" v-html="captcha.svg"></div>
          <a href="#" class="small" @click.prevent="loadCaptcha">Another image</a>
        </div>
        <input id="captcha" v-model="input.captcha" class="form-control" autocomplete="off">
      </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>

    <div v-if="error" class="alert alert-danger mt-3">{{ error }}</div>
  </div>
</template>
  • Zeile 35: das Format aller Fehler der API;
  • Zeile 42: die wenigen für dieses Beispiel nötigen Meldungen, auf Englisch; Beispiel 20 verwendet [vue-i18n];
  • Zeilen 61–69: Beim Start [GET /api/auth/me]: Sind wir bereits angemeldet? Nach dem Neuladen der Seite (F5) hat die [Vue.js]-Anwendung alles vergessen; der Server hingegen liest das Cookie. 200: der Benutzer; 401: niemand;
  • Zeilen 73–96: die Anmeldung:
    • Zeile 76: [fetch(url, options)]: Methode, Header und Body;
    • Zeile 78: Der Server weist einen POST ab, der nicht im JSON-Format vorliegt;
    • Zeile 79: der Body, in JSON-Text umgewandelt;
    • Zeile 87: Bei Erfolg hat der Server das Token-Cookie gesetzt. Unser Code sieht es NIE: Geben Sie [document.cookie] in der Browser-Konsole ein; dort ist es nicht vorhanden ([HttpOnly]);
    • Zeile 93: Schlägt die Anfrage fehl, erklärt der Body den Grund. Wir zeigen die Meldung an und fordern ein neues Bild an: Jedes Bild wird nur einmal verwendet;
  • Zeilen 99–102: eine geschützte Anfrage. Wir müssen nichts tun, um uns zu authentifizieren: Der Browser fügt das Cookie automatisch hinzu, weil die Anfrage an denselben Ursprung wie die Seite geht (standardmäßig sendet [fetch] Cookies bei Anfragen an denselben Ursprung);
  • Zeilen 105–110: Abmeldung – der Server löscht das Cookie. Der Body ['{}'] wird mitgesendet, damit die Anfrage ein JSON-POST ist.

Das Anmeldeformular:

Image

Mit einem falsch eingegebenen CAPTCHA (der Server befindet sich im Testmodus: Jedes CAPTCHA akzeptiert die Antwort [test]):

Image

Angemeldet:

Image

Laden Sie die Seite neu (F5): Sie bleiben angemeldet. Öffnen Sie anschließend Beispiel 19: Auch dort sind Sie angemeldet. Ein Cookie gehört zu einem Rechner (hier [localhost]) und einem Pfad (hier [/api]), die allen Beispielen gemeinsam sind.

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

Beispiel 18 wiederholte bei jedem Aufruf von [fetch] dieselben Schritte: das Präfix [/api], den Header [Content-Type], [JSON.stringify], die Prüfung von [response.ok] und das Lesen des Fehler-Bodys. Wir fassen sie in einer einzigen Funktion im Ordner [common] zusammen (gemeinsam genutzt von den Beispielen 19 und 20):

// =========================================================================
// common/api.ts - EINE Funktion für alle Anfragen an die API
// -------------------------------------------------------------------------
// In Beispiel 18 wiederholte jeder fetch-Aufruf dieselben Handgriffe:
// Präfix /api, Header Content-Type, JSON.stringify, Test von response.ok,
// Lesen des Fehler-Bodys ... Sie sind hier ein für alle Mal gebündelt:
//
//   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, der den
//     vom Server gesendeten Übersetzungsschlüssel trägt (und gegebenenfalls dessen
//     Parameter und den Fehler jedes Feldes).
// Verwendet von den Beispielen 19 und 20; die Fallstudie übernimmt das Prinzip.
// =========================================================================

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

type Method = 'GET' | 'POST' | 'PUT' | 'DELETE';

export async function request<T>(method: Method, url: string, body?: unknown): Promise<T> {
  let response: Response;
  try {
    response = await fetch(`/api${url}`, {
      method,
      // ein Body -> JSON (der Server lehnt einen POST ab, der keiner ist)
      headers: body !== undefined ? { 'Content-Type': 'application/json' } : {},
      body: body !== undefined ? JSON.stringify(body) : undefined,
    });
  } catch {
    // keine Antwort (Netzwerk ausgefallen ...)
    throw new ApiError(0, 'ERRORS.SERVER_UNREACHABLE');
  }

  // der Body wird als Text gelesen und dann konvertiert: Eine leere Antwort oder eine,
  // die kein JSON ist (JSON-Server gestoppt: Vite antwortet),
  // darf die Anwendung nicht zum Absturz bringen
  const text = await response.text();
  let data: unknown = null;
  try {
    data = text ? JSON.parse(text) : null;
  } catch {
    data = null;
  }

  if (!response.ok) {
    const e = (data ?? {}) as { key?: string; params?: Record<string, string>; fields?: Record<string, string> };
    throw new ApiError(response.status, e.key ?? 'ERRORS.SERVER_UNREACHABLE', e.params, e.fields);
  }
  return data as T;
}

// Kurzformen, im Gebrauch lesbarer
export const api = {
  get: <T>(url: string) => request<T>('GET', url),
  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 18–27: 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“;
  • Zeile 32: eine generische Funktion: [T] ist der Typ des Bodys, der im Erfolgsfall erwartet wird. [request<Person[]>('GET', '/doctors')] liefert ein [Promise<Person[]>];
  • Zeile 38: ein Body, und nur in diesem Fall, begleitet vom JSON-Header;
  • Zeilen 49–55: Der Body wird als Text gelesen und dann umgewandelt. Eine leere oder nicht JSON-konforme Antwort (Server nicht erreichbar: [Vite] antwortet mit Text) darf die Anwendung nicht abstürzen lassen;
  • Zeilen 57–60: Ein Fehlschlag führt zu einem [ApiError]: Das von [request] zurückgegebene Promise wird abgelehnt. Der aufrufende Code fängt dies über [try / catch] ab;
  • Zeilen 65–70: Kurzformen, besser lesbar: [api.get<T>(url)], [api.post<T>(url, body)] ... [api.post] sendet standardmäßig den Body [{}].

Die Objekttypen des JSON der API, im vorigen Kapitel beschrieben:

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

Eine Anmeldekomponente, mit [api.ts] neu geschrieben und auf eine Leiste reduziert:

<!--
  =========================================================================
  common/LoginBar.vue - logging in / out, in one bar
  -------------------------------------------------------------------------
  The component of example 18, reduced to a bar and rewritten with
  common/api.ts. It emits 'change' with the logged-in user (or null)
  each time the user changes - including at startup, after having
  queried GET /api/auth/me.
  =========================================================================
-->
<script setup lang="ts">
import { onMounted, reactive, ref } from 'vue';
import { api, ApiError } from './api';
import type { Captcha, User } from './types';

const emit = defineEmits<{ change: [user: User | null] }>();

const user = ref<User | null>(null);
const captcha = ref<Captcha | null>(null);
const input = reactive({ login: 'admin', password: '', captcha: '' });
const error = ref<string | null>(null);

async function newCaptcha(): Promise<void> {
  captcha.value = await api.get<Captcha>('/captcha');
  input.captcha = '';
}

function setUser(u: User | null): void {
  user.value = u;
  emit('change', u);
}

onMounted(async () => {
  try {
    setUser(await api.get<User>('/auth/me'));
  } catch {
    setUser(null); // 401: Niemand ist angemeldet
    await newCaptcha().catch(() => (error.value = 'Is the JSON server running (port 8080)?'));
  }
});

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

async function logOut(): Promise<void> {
  await api.post('/auth/logout');
  setUser(null);
  await newCaptcha();
}
</script>

<template>
  <div class="alert alert-secondary d-flex flex-wrap align-items-center gap-2 py-2">
    <template v-if="user">
      <span>Logged in: <strong>{{ user.name }}</strong> <span class="badge text-bg-primary">{{ user.role }}</span></span>
      <button class="btn btn-sm btn-outline-secondary ms-auto" @click="logOut">Log out</button>
    </template>
    <form v-else class="d-flex flex-wrap align-items-center gap-2 w-100" @submit.prevent="logIn">
      <input v-model="input.login" class="form-control form-control-sm w-auto" placeholder="login" autocomplete="username">
      <input v-model="input.password" type="password" class="form-control form-control-sm w-auto" placeholder="password" autocomplete="current-password">
      <div v-if="captcha" class="captcha" v-html="captcha.svg"></div>
      <input v-model="input.captcha" class="form-control form-control-sm w-auto" placeholder="captcha" autocomplete="off" size="8">
      <button class="btn btn-sm btn-primary">Log in</button>
      <span v-if="error" class="text-danger small">{{ error }}</span>
    </form>
  </div>
</template>

<style scoped>
/* das CAPTCHA-Bild, verkleinert, damit es in die Leiste passt */
.captcha :deep(svg) {
  display: block;
  height: 32px;
  width: auto;
}
</style>
  • Zeile 16: Die Komponente sendet [change] mit dem angemeldeten Benutzer (oder [null]) bei jeder Änderung, auch beim Start;
  • Zeile 35: Mit [api.ts] passt eine Anfrage in eine Zeile; bei einem Fehlschlag (401) wird zu [catch] gewechselt;
  • Zeile 54: [instanceof] unterscheidet einen API-Fehler von einer anderen Anomalie.

Oberhalb von [api.ts]eine Funktion pro Route der API:

// =========================================================================
// 19-api-service/src/rdvmedecins.service.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 Pendant zur DAO-Schicht auf der Serverseite: Ändert sich die API
// (eine URL, ein Feldname), wird nur diese Datei angepasst.
// =========================================================================

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 baut "?doctorId=1&day=2030-01-15" und kodiert dabei, 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}`),
};

Dies ist das clientseitige Gegenstück zur DAO-Schicht des Servers: Die Komponenten kennen weder URL, [fetch] noch das JSON-Format; sie rufen typisierte Funktionen auf. Ändert sich die API, ändert sich nur diese Datei.

  • Zeile 18: [URLSearchParams] erzeugt die Zeichenkette [doctorId=1&day=2030-01-15] und kodiert dabei die Zeichen, die kodiert werden müssen.

Die Seite:

<!--
  =========================================================================
  19-api-service/src/App.vue - a schedule, with the API access layer
  -------------------------------------------------------------------------
  Log in (top bar), choose a doctor and a day: the schedule
  is displayed. ADMIN and DOCTOR can book for a patient and cancel;
  a patient (martin...) books for themselves. Each action ends with
  a reload of the schedule: it is the SERVER that is authoritative.
  =========================================================================
-->
<script setup lang="ts">
import { computed, ref, watch } from 'vue';
import LoginBar from '../../common/LoginBar.vue';
import { ApiError } from '../../common/api';
import type { Schedule, ScheduleSlot, Person, User } from '../../common/types';
import { rdvmedecins } from './rdvmedecins.service';

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

const isManager = computed(() => user.value !== null && user.value.role !== 'USER');

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

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

async function loadSchedule(): Promise<void> {
  if (doctorId.value === null) {
    return;
  }
  try {
    schedule.value = await rdvmedecins.getSchedule(doctorId.value, day.value);
  } catch (e) {
    schedule.value = null;
    report(e);
  }
}

// der Terminkalender folgt der Wahl des Arztes und des Tages
watch([doctorId, day], () => {
  message.value = null;
  loadSchedule();
});

async function book(c: ScheduleSlot): Promise<void> {
  try {
    await rdvmedecins.book(day.value, c.id, isManager.value ? (clientId.value ?? undefined) : undefined);
    message.value = { type: 'success', text: `Slot ${timeRange(c)} booked.` };
  } catch (e) {
    report(e);
  }
  await loadSchedule();
}

async function cancel(c: ScheduleSlot): Promise<void> {
  try {
    await rdvmedecins.cancelAppointment(c.appointmentId as number);
    message.value = { type: 'success', text: `Appointment of ${timeRange(c)} cancelled.` };
  } catch (e) {
    report(e);
  }
  await loadSchedule();
}
</script>

<template>
  <div class="container py-4">
    <h1 class="h3 mb-3">Example 19 - an API access layer</h1>
    <LoginBar @change="onUserChange" />

    <template v-if="user">
      <div class="row g-2 mb-3">
        <div class="col-sm-5">
          <select v-model="doctorId" class="form-select">
            <option :value="null" disabled>-- choose a doctor --</option>
            <option v-for="m in doctors" :key="m.id" :value="m.id">{{ m.title }} {{ m.firstName }} {{ m.lastName }}</option>
          </select>
        </div>
        <div class="col-sm-3"><input v-model="day" type="date" class="form-control"></div>
        <div v-if="isManager" class="col-sm-4">
          <select v-model="clientId" class="form-select">
            <option :value="null">-- patient to book for --</option>
            <option v-for="c in clients" :key="c.id" :value="c.id">{{ c.title }} {{ c.firstName }} {{ c.lastName }}</option>
          </select>
        </div>
      </div>

      <div v-if="message" class="alert" :class="`alert-${message.type}`">{{ message.text }}</div>
      <!-- info: der vom Server gesendete Schlüssel, wenn ein Patient bereits einen bevorstehenden Termin hat -->
      <div v-if="schedule?.info" class="alert alert-info">{{ schedule.info }}</div>

      <table v-if="schedule" class="table table-sm align-middle">
        <caption class="caption-top">Schedule of {{ schedule.day }} - {{ schedule.doctor.title }} {{ schedule.doctor.firstName }} {{ schedule.doctor.lastName }}</caption>
        <tbody>
          <tr v-for="c in schedule.slots" :key="c.id">
            <td>{{ timeRange(c) }}</td>
            <td>
              <span v-if="c.free" class="badge text-bg-success">Free</span>
              <span v-else-if="c.patient" class="badge" :class="c.mine ? 'text-bg-primary' : 'text-bg-secondary'">
                {{ c.patient.title }} {{ c.patient.firstName }} {{ c.patient.lastName }}
              </span>
              <span v-else class="badge text-bg-secondary">Booked</span>
            </td>
            <td class="text-end">
              <!-- die Buttons folgen den vom Server berechneten Rechten -->
              <button v-if="c.bookable" class="btn btn-sm btn-outline-success" @click="book(c)">Book</button>
              <button v-if="c.appointmentId !== null" class="btn btn-sm btn-outline-danger" @click="cancel(c)">Cancel</button>
            </td>
          </tr>
        </tbody>
      </table>
    </template>
  </div>
</template>
  • Zeile 27: ADMIN oder DOCTOR;
  • Zeilen 45–60: Bei jeder An- oder Abmeldung eines Benutzers werden die Inhalte, die diese Rolle einsehen darf, (neu) geladen. Ein Patient erhielte für die Client-Liste einen 403-Fehler: Wir fordern sie gar nicht erst an;
  • Zeile 75: [watch] kann mehrere Quellen überwachen: Der Terminkalender wird neu geladen, wenn sich der Arzt ODER der Tag ändert;
  • Zeilen 80–87: eine Reservierung, gefolgt, WAS AUCH GESCHIEHT, von einer Aktualisierung des Terminkalenders. Der Datensatz des Servers ist maßgeblich: Wurde das Zeitfenster inzwischen von jemand anderem belegt, zeigt der aktualisierte Terminkalender dies an;
  • Zeilen 141 und 142: Die Schaltflächen spiegeln die vom Server berechneten Berechtigungen wider;
  • Zeile 137: ein gebuchtes Zeitfenster, dem der Server keinen Patienten zugeordnet hat (aus Sicht eines Patienten).

Als [admin] angemeldet, wählen Sie einen Arzt, einen Patienten und buchen ein Zeitfenster:

Image

Buchen Sie für denselben Patienten ein zweites Zeitfenster: Der Server lehnt ab. Da dieses Beispiel kein Wörterbuch enthält, wird der Rohschlüssel angezeigt:

Image

8.4. Beispiel 20: Vom Server zurückgegebene Fehler

Letztes Beispiel vor der Fallstudie: die Client-Verwaltung, abgewickelt über das ADMIN-Formular. Dieses Formular führt keine Validierung im Browser durch: Alles wird an den Server gesendet, der die Daten validiert und im Fall einer Ablehnung mit dem Fehler für jedes Feld antwortet. Beispiel 06 zeigte den alternativen Ansatz; dieser hat einen erheblichen Vorteil: Die Regeln existieren nur an EINER Stelle – dem Server – und der Client kann sie nicht übersehen. Der Nachteil: ein Roundtrip zum Server, bevor die Fehler angezeigt werden.

Die Wörterbücher verwenden 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."
  }
}

([locales/en.json] enthält dieselben Codes, auf Englisch.)

import { createApp } from 'vue';
import { createI18n } from 'vue-i18n';
import 'bootstrap/dist/css/bootstrap.min.css';
import App from './App.vue';
import fr from './locales/fr.json';
import en from './locales/en.json';

// dieselbe Konfiguration wie in Beispiel 16, in kürzerer Form
const i18n = createI18n({ legacy: false, locale: 'en', fallbackLocale: 'en', messages: { fr, en } });

createApp(App).use(i18n).mount('#app');

Die Seite:

<!--
  =========================================================================
  20-server-errors/src/App.vue - displaying the errors of the SERVER
  -------------------------------------------------------------------------
  The management of the clients (admin account). This form DELIBERATELY
  does no validation in the browser: everything is sent to the
  server, which answers, in case of refusal, with a JSON error:

    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)

  The client translates each key (vue-i18n) and places each message under its
  field, the general message at the bottom of the form. Try: an empty last name, a
  title modified in the developer tools, a namesake (Alice DURAND),
  a login already taken (martin), the same record modified in two tabs...
  =========================================================================
-->
<script setup lang="ts">
import { computed, reactive, ref } from 'vue';
import { useI18n } from 'vue-i18n';
import LoginBar from '../../common/LoginBar.vue';
import { api, ApiError } from '../../common/api';
import type { Person, User } from '../../common/types';
// der Bestätigungsdialog aus Beispiel 12, unverändert wiederverwendet
import ConfirmDialog from '../../12-confirmation/src/components/ConfirmDialog.vue';
import { useConfirmation } from '../../12-confirmation/src/composables/useConfirmation';

const { t, locale } = useI18n();
const { confirm } = useConfirmation();

const user = ref<User | null>(null);
const clients = ref<Person[]>([]);
const isAdmin = computed(() => user.value?.role === 'ADMIN');

// das Formular: editedId === null -> Anlegen, andernfalls Aktualisieren
const editedId = ref<number | null>(null);
const input = reactive({ title: 'Mr', firstName: '', lastName: '', login: '', password: '', version: 0 });
// die vom Server zurückgegebenen Fehler
const fieldErrors = ref<Record<string, string>>({});
const pageError = ref<ApiError | null>(null);
const success = ref<string | null>(null);

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

async function reload(): Promise<void> {
  clients.value = await api.get<Person[]>('/clients');
}

function newForm(): void {
  editedId.value = null;
  Object.assign(input, { title: 'Mr', firstName: '', lastName: '', login: '', password: '', version: 0 });
  clearErrors();
}

function edit(c: Person): void {
  editedId.value = c.id;
  // die zusammen mit dem Datensatz gelesene VERSION geht mit der Aktualisierung zurück: Hat jemand
  // den Datensatz zwischenzeitlich geändert, antwortet der Server mit 409 CONCURRENT_UPDATE
  Object.assign(input, { title: c.title, firstName: c.firstName, lastName: c.lastName, login: c.login ?? '', password: '', version: c.version });
  clearErrors();
}

function clearErrors(): void {
  fieldErrors.value = {};
  pageError.value = null;
  success.value = null;
}

// der Text eines Fehlers in der aktuellen Sprache, mit seinen Parametern
function errorText(e: ApiError): string {
  return t(e.key, e.params);
}

async function save(): Promise<void> {
  clearErrors();
  const body = { ...input };
  try {
    const client =
      editedId.value === null
        ? await api.post<Person>('/clients', body)
        : await api.put<Person>(`/clients/${editedId.value}`, body);
    const message = t(editedId.value === null ? 'FORM.ADDED' : 'FORM.UPDATED', {
      name: `${client.firstName} ${client.lastName}`,
      login: client.login ?? '',
    });
    newForm(); // Formular geleert, Meldungen gelöscht ...
    success.value = message; // ... außer dieser
    await reload();
  } catch (e) {
    if (!(e instanceof ApiError)) {
      throw e;
    }
    // der Fehler jedes Feldes und die allgemeine Meldung
    fieldErrors.value = e.fields;
    pageError.value = e;
  }
}

async function remove(c: Person): Promise<void> {
  const name = `${c.firstName} ${c.lastName}`;
  if (!(await confirm(t('FORM.DELETE_CONFIRM', { name })))) {
    return;
  }
  clearErrors();
  try {
    await api.delete(`/clients/${c.id}`);
    success.value = t('FORM.DELETED', { name });
  } catch (e) {
    pageError.value = e instanceof ApiError ? e : null;
  }
  await reload();
}
</script>

<template>
  <div class="container py-4">
    <div class="d-flex justify-content-between align-items-center mb-3">
      <h1 class="h3 mb-0">Example 20 - the errors returned by the server</h1>
      <select v-model="locale" class="form-select form-select-sm w-auto">
        <option value="fr">FR</option>
        <option value="en">EN</option>
      </select>
    </div>
    <LoginBar @change="onUserChange" />
    <p v-if="user && !isAdmin" class="alert alert-warning">{{ t('FORM.ADMIN_ONLY') }}</p>

    <div v-if="isAdmin" class="row g-4">
      <div class="col-lg-6">
        <table class="table table-sm align-middle">
          <tbody>
            <tr v-for="c in clients" :key="c.id">
              <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)">{{ t('FORM.EDIT') }}</button>
                <button class="btn btn-sm btn-outline-danger" @click="remove(c)">{{ t('FORM.DELETE') }}</button>
              </td>
            </tr>
          </tbody>
        </table>
      </div>

      <div class="col-lg-6">
        <form class="card p-3" novalidate @submit.prevent="save">
          <h2 class="h5">{{ editedId === null ? t('FORM.TITLE_ADD') : t('FORM.TITLE_EDIT') }}</h2>
          <div class="mb-2">
            <label class="form-label" for="title">{{ t('FORM.TITLE') }}</label>
            <!-- eine Option "Dr", die der Server ablehnen wird: um ERRORS.INVALID_TITLE zu sehen -->
            <select id="title" v-model="input.title" class="form-select" :class="{ 'is-invalid': fieldErrors.title }">
              <option>Mr</option><option>Mme</option><option>Melle</option><option>Dr</option>
            </select>
            <div class="invalid-feedback">{{ fieldErrors.title && t(fieldErrors.title) }}</div>
          </div>
          <div class="row g-2 mb-2">
            <div class="col-sm-6">
              <label class="form-label" for="firstName">{{ t('FORM.FIRSTNAME') }}</label>
              <input id="firstName" v-model="input.firstName" class="form-control" :class="{ 'is-invalid': fieldErrors.firstName }">
              <div class="invalid-feedback">{{ fieldErrors.firstName && t(fieldErrors.firstName) }}</div>
            </div>
            <div class="col-sm-6">
              <label class="form-label" for="lastName">{{ t('FORM.LASTNAME') }}</label>
              <input id="lastName" v-model="input.lastName" class="form-control" :class="{ 'is-invalid': fieldErrors.lastName }">
              <div class="invalid-feedback">{{ fieldErrors.lastName && t(fieldErrors.lastName) }}</div>
            </div>
          </div>
          <div class="row g-2 mb-3">
            <div class="col-sm-6">
              <label class="form-label" for="login">{{ t('FORM.LOGIN') }}</label>
              <input id="login" v-model="input.login" class="form-control" :class="{ 'is-invalid': fieldErrors.login }">
              <div class="invalid-feedback">{{ fieldErrors.login && t(fieldErrors.login) }}</div>
            </div>
            <div class="col-sm-6">
              <label class="form-label" for="password">{{ t('FORM.PASSWORD') }}</label>
              <input id="password" v-model="input.password" type="password" class="form-control" autocomplete="new-password"
                     :class="{ 'is-invalid': fieldErrors.password }">
              <div class="invalid-feedback">{{ fieldErrors.password && t(fieldErrors.password) }}</div>
            </div>
          </div>
          <div class="d-flex gap-2">
            <button class="btn btn-primary">{{ t('FORM.SAVE') }}</button>
            <button type="button" class="btn btn-secondary" @click="newForm">{{ t('FORM.CANCEL') }}</button>
          </div>
          <div v-if="success" class="alert alert-success mt-3 mb-0">{{ success }}</div>
          <!-- die allgemeine Meldung und der HTTP-Status, zum Verständnis -->
          <div v-if="pageError" class="alert alert-danger mt-3 mb-0">
            {{ errorText(pageError) }} <span class="small text-muted">({{ pageError.statusCode }} {{ pageError.key }})</span>
          </div>
        </form>
      </div>
    </div>
  </div>
  <ConfirmDialog />
</template>
  • Zeile 26: das Bestätigungsfenster aus Beispiel 12, unverändert wiederverwendet – eine gut entworfene Komponente ist wiederverwendbar;
  • Zeilen 40 und 41: die vom Server zurückgegebenen Fehler: der Fehler für jedes Feld und die allgemeine Meldung;
  • Zeilen 62–68: Um einen Datensatz zu ändern, werden seine Werte in das Formular kopiert, einschließlich der Versionsnummer: Sie wird mit der Änderung gespeichert (optimistisches Sperren);
  • Zeilen 77–79: die Fehlermeldung in Alltagssprache, zusammen mit ihren Parametern;
  • Zeilen 81–102: [POST] für eine Erstellung, [PUT] für eine Änderung. Wird die Anfrage abgelehnt, werden die zurückgegebenen Fehler gespeichert; das Template erledigt den Rest;
  • Zeile 157: ein Titel, den der Server ablehnen wird, um [ERRORS.INVALID_TITLE] zu sehen;
  • Zeilen 164 und 165: Ein abgelehntes Feld wird rot hervorgehoben, und sein übersetzter Fehlercode wird darunter angezeigt;
  • Zeile 126: Ein Sprachwechsel übersetzt auch die bereits angezeigten Fehlermeldungen neu: Nur die Schlüssel wurden behalten.

Ein falsch ausgefülltes Formular:

Image

Ein doppelter Name (Alice DURAND existiert bereits): Der Server liefert eine 409-Antwort und kennzeichnet die Felder Vorname und Nachname:

Image

Derselbe Fehler, auf Französisch:

Image

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