Aufgabe 20 - Typisierten Client generieren und Vertragsbruch provozieren

Worum geht es?

Sie erzeugen die Typen Ihres Frontends aus der OpenAPI-Beschreibung, bündeln den Zugriff auf die API an einer einzigen Stelle und brechen dann absichtlich den Vertrag (siehe Kapitel Getrennte Systeme). Der Unterschied, um den es geht, ist der zwischen einem Fehler am Dienstagnachmittag im Editor und einem Fehler am Freitag im Betrieb.

Was Sie dafür brauchen

Kapitel Getrennte Systeme, Abschnitte Den Vertrag typsicher halten und Betrieb getrennter Systeme.
Die openapi.yaml aus Aufgabe 16 und die Anwendungen aus Aufgabe 19.
openapi-typescript oder den Generator Ihrer Klasse.

Welche Kompetenzen Sie erwerben und zeigen

Sie erzeugen einen typisierten Client aus dem Schnittstellenvertrag und binden den Schritt in das Projekt ein.
Sie bündeln den API-Zugriff an einer Stelle im Frontend.
Sie begründen die Reihenfolge beim Ausliefern additiver und entfernender Änderungen.

Pädagogische Einordnung

Reproduktion: Typen erzeugen und den Befehl als Skript hinterlegen (Teil A).
Reorganisation und Transfer: den Zugriff in einem Modul bündeln (Teil B).
Reflexion, Problemlösung und Urteilsbildung: einen Vertragsbruch auslösen und die Auslieferungsreihenfolge begründen (Teil C).

Arbeitsaufträge

Die Übung ist auf etwa zwei Stunden ausgelegt.

Teil A - Typen erzeugen

Erzeugen Sie die Typen aus Ihrer Beschreibung und notieren Sie den Befehl:
Terminal-Fenster
```
npx openapi-typescript docs/openapi.yaml -o src/lib/api/schema.d.ts
```
Öffnen Sie die erzeugte Datei und suchen Sie den Typ zu einer Ihrer Ressourcen. Notieren Sie, wie die Pflichtfelder und die optionalen Felder dort unterschieden werden.
Hinterlegen Sie den Befehl als npm-Skript, etwa npm run api:types. Notieren Sie den Eintrag aus package.json.
Ändern Sie in openapi.yaml ein Feld, erzeugen Sie neu und prüfen Sie, dass sich die Typdatei ändert. Machen Sie die Änderung danach rückgängig.
Beantworten Sie in zwei bis drei Sätzen, warum die erzeugte Datei zwar im Repository liegen darf, aber niemals von Hand bearbeitet wird.

Teil B - Den Zugriff bündeln

Legen Sie ein Modul an, über das jeder API-Aufruf des Frontends läuft. Es kennt vier Dinge: die Basis-URL aus der Umgebung, die Anmeldung nach Ihrer Entscheidung aus Aufgabe 18, die Übersetzung von Fehlerantworten in Ausnahmen, und das Verhalten bei einer Wiederholung.
Schreiben Sie zwei Aufrufe Ihres Projekts über dieses Modul, einen lesenden und einen schreibenden. Verwenden Sie dabei die erzeugten Typen.
Suchen Sie in Ihrem Frontend mit grep nach der Basis-URL. Sie darf nur an einer einzigen Stelle vorkommen. Notieren Sie das Ergebnis der Suche.
Bauen Sie in das Modul die einheitliche Fehlerbehandlung: Aus einem 401 wird eine andere Ausnahme als aus einem 404 oder einem 500. Rufen Sie jeden der drei Fälle einmal auf und notieren Sie, was im Frontend ankommt.
Beschreiben Sie in drei bis vier Sätzen, was passiert, wenn der Zugriff stattdessen über die Komponenten verteilt ist. Gehen Sie auf den Umzug der API auf eine neue Adresse ein.
Bauen Sie den Typerzeugungsschritt in Ihre CI-Pipeline ein oder notieren Sie, an welcher Stelle er hingehört, falls Sie noch keine haben.

Teil C - Den Vertrag brechen

Benennen Sie in openapi.yaml ein Pflichtfeld um, das Ihr Frontend verwendet. Erzeugen Sie die Typen neu und übersetzen Sie das Frontend. Notieren Sie jede Fehlermeldung und die Datei, in der sie auftritt.
Beschreiben Sie in drei bis vier Sätzen, warum diese Meldungen genau der erwünschte Effekt sind. Vergleichen Sie dabei mit dem Fall, in dem beide Seiten ihre Typen von Hand pflegen.
Machen Sie den Gegenversuch. Entfernen Sie das Feld nur in der API, ohne die Beschreibung zu ändern, und rufen Sie das Frontend auf. Notieren Sie, wo und wann der Fehler jetzt auftritt und wie er sich äußert.
Beantworten Sie in zwei bis drei Sätzen, welchen Mechanismus es braucht, damit auch dieser Fall auffällt, und in welchem Kapitel er behandelt wird.
Machen Sie beide Änderungen rückgängig und prüfen Sie, dass alles wieder übersetzt.
Legen Sie eine Tabelle mit zwei Zeilen an: additive Änderung und entfernende Änderung. Tragen Sie zu jeder ein, welche der beiden Anwendungen zuerst ausgeliefert wird und was passiert, wenn man die Reihenfolge vertauscht.
Beschreiben Sie in vier bis fünf Sätzen den üblichen Weg, ein Feld aus einer laufenden Schnittstelle zu entfernen, ohne Aufrufer zu brechen. Gehen Sie auf die Übergangszeit und die Kennzeichnung als überholt ein.
Legen Sie beide Ergebnisse in docs/architektur.md ab, als Abschnitt Änderungen an der Schnittstelle.

Wissenscheck

Woher kommen die Typen des Frontends, und warum werden sie nicht von Hand geschrieben?
Warum darf die erzeugte Typdatei nicht bearbeitet werden?
Welche vier Aufgaben übernimmt das Modul, das den API-Zugriff bündelt?
Was passiert beim ersten umbenannten Feld, wenn beide Seiten ihre Typen selbst pflegen?
Warum wird bei einer additiven Änderung zuerst die API ausgeliefert?
Warum wird bei einer entfernenden Änderung zuerst das Frontend ausgeliefert?
Wie entfernt man ein Feld, ohne bestehende Aufrufer zu brechen?

Abgabe

Der Erzeugungsschritt liegt als npm-Skript im Repository, die erzeugte Typdatei ebenfalls. Das Zugriffsmodul mit einheitlicher Fehlerbehandlung liegt als Code vor, und die Basis-URL kommt nur an einer Stelle vor. In protokoll.md stehen die Fehlermeldungen aus dem Vertragsbruch, das Ergebnis des Gegenversuchs und die Reihenfolgetabelle. Der Abschnitt Änderungen an der Schnittstelle steht in docs/architektur.md.