Dokumentation, Mocks und Codegenerierung

Dokumentation, Mocks und Codegenerierung

0:00 Bis hierher haben wir Arbeit in den Vertrag gesteckt. Jetzt kommt der Teil, in dem sich diese Arbeit auszahlt. Aus einem maschinenlesbaren Vertrag fällt deutlich mehr heraus, als die meisten Teams tatsächlich abholen: eine lesbare Dokumentation, ein Mock Server, mit dem Consumer sofort loslegen können, generierte Clients.

0:18 In diesem Modul geht es darum, was sich lohnt, was man besser von Hand macht — und vor allem darum, wie man verhindert, dass Vertrag, Code und Dokumentation langsam auseinanderlaufen.

Dokumentation, Mocks und Codegenerierung

0:29 Drei Themen. Zuerst Dokumentation und Mock Server — die beiden Artefakte mit dem besten Verhältnis von Aufwand zu Nutzen. Dann Codegenerierung, bei der ich Sie zu einer differenzierten Haltung einladen möchte, denn beim Client ist sie fast immer ein Gewinn und beim Server nicht immer. Und zum Schluss das Thema Drift: Wie Sie technisch sicherstellen, dass Ihre Anwendung tatsächlich das tut, was der Vertrag behauptet.

Dokumentation und Mock Server

0:53 Fangen wir mit dem an, was am schnellsten Wirkung zeigt. Ein Mock Server ist in Minuten gestartet und verändert die Zusammenarbeit zwischen Frontend und Backend grundlegend. Und die Dokumentation, die dabei nebenbei herausfällt, ist meist besser als die, die jemand von Hand pflegen würde — weil sie nicht altert. Schauen wir uns beides an.

1:13 Der praktische Effekt lässt sich an einem Bild festmachen: Ein Mock Server ist wie das Modell einer Wohnung, bevor gebaut wird. Die Möbel passen hinein, die Wege lassen sich gehen, obwohl noch kein Stein steht. Für Ihr Frontend-Team heißt das: Es wartet nicht mehr auf das Backend. Es entwickelt gegen Antworten, die aus Ihrem Vertrag und Ihren Beispielen entstehen. Und wenn der echte Dienst später kommt, verhält er sich gleich — sofern er den Vertrag einhält.

1:39 Genau darum kümmert sich das dritte Kapitel dieses Moduls. Die Kette zeigt eine Richtung, und die ist entscheidend: Alles fließt aus dem Vertrag heraus, nichts zurück. Solange das so bleibt, kann nichts driften. Sobald jemand anfängt, in der erzeugten Dokumentation nachzubessern oder im generierten Client eine Zeile zu reparieren, ist die Richtung durchbrochen — und ab da gibt es wieder zwei Wahrheiten.

2:03 Behalten Sie dieses Bild im Kopf, wenn im nächsten Kapitel die Frage kommt, wo Codegenerierung sinnvoll ist und wo nicht. Beispiele sind der Teil eines Vertrags, den man am ehesten weglässt, weil er Arbeit macht und nichts prüft. Und sie sind zugleich der Teil mit der größten Hebelwirkung: Sie tragen die Dokumentation, sie speisen den Mock, und wenn Sie sie gegen das eigene Schema validieren, altern sie nicht still.

2:26 Der letzte Punkt ist eine Empfehlung, die überrascht: Die OpenAPI-Initiative rät, die Beschreibung selbst den Nutzern zugänglich zu machen — nicht nur die hübsche Seite. Denn dann können Consumer eigene Clients und Bindings erzeugen. Der zweite Punkt ist der, der später am meisten kostet: Ein Mock, der immer erfolgreich antwortet.

2:45 Das Frontend entwickelt dann eine Anwendung ohne Fehlerbehandlung, und die fehlt genau dann, wenn es zählt. Ergänzen Sie Beispiele für die Fehlerfälle aus Modul 4 — der Mock kann sie liefern. Der vierte Punkt ist eine Falle des Erfolgs: Wenn der Mock zu gut funktioniert, testet irgendwann niemand mehr gegen den echten Dienst. Dann ist alles grün und nichts bewiesen.

Codegenerierung mit Augenmaß

3:07 Kommen wir zum umstrittensten Thema dieses Moduls. Codegenerierung hat einen zwiespältigen Ruf, und der ist verdient — allerdings nicht pauschal, sondern je nach Artefakt. Die Antwort lautet nicht ja oder nein, sondern hängt vom Artefakt ab: Beim Client ist Generierung fast immer ein Gewinn, beim Server längst nicht immer.

3:27 Der Unterschied zwischen Client und Server ist grundlegend. Ein erzeugter Client ist ein abgeschlossenes Stück Code, das Sie benutzen und nie anfassen — Änderungen kommen aus dem Vertrag nach. Ein erzeugter Server-Stub dagegen ist ein Gerüst, in das Sie Ihre Logik hineinschreiben. Und beim nächsten Lauf muss der Generator wieder hinein, ohne Ihre Arbeit zu zerstören.

3:48 Das ist der Punkt, an dem viele Projekte irgendwann aufhören zu generieren und den erzeugten Stand von Hand weiterpflegen. Erzeugen ist billig, pflegen nicht. Die rechte Spalte ist die eigentliche Botschaft. Client-SDK erzeugen lohnt fast immer — mit der Einschränkung, dass Sie nicht hineinschreiben dürfen. Server-Stubs lohnen am Projektanfang, wenn noch nichts da ist, und werden im Bestand mühsam. Modellklassen sind der unstrittigste Fall, solange keine Logik in ihnen landet.

4:17 Und die Fußnote fasst die Regel zusammen, die alles einfacher macht: Erzeugtes gehört in den Build, nicht als Kopie ins Repository. Sobald es eingecheckt ist, wird es früher oder später von Hand angefasst. Vier Regeln, die zusammen genau das absichern. Nicht nachbearbeiten, im Build erzeugen — das sind die beiden zentralen.

4:37 Der dritte Punkt ist eine praktische Warnung, die man einmal erlebt haben muss: Die operationId bestimmt die Methodennamen im erzeugten Client. Wenn Sie sie ändern, benennen Sie bei jedem Consumer eine Methode um, ohne dass sich fachlich irgendetwas geändert hätte. Deshalb gehören operationIds zu den Dingen, die man einmal sorgfältig festlegt und danach in Ruhe lässt.

5:00 Der erste Punkt ist der Klassiker und der Anfang vom Ende jeder Generierung: Der Client wird eingecheckt und dann von Hand repariert. Ab dem Moment ist die nächste Erzeugung eine Bedrohung statt einer Aktualisierung. Der vierte Punkt ist ein Organisationsthema, das man früh regeln sollte: Wenn jedes Consumerteam seinen eigenen Client mit eigenen Einstellungen erzeugt, haben Sie fünf leicht verschiedene Clients und fünf verschiedene Fehlerbilder.

5:24 Ein SDK je Sprache, an einer Stelle gepflegt, ist deutlich billiger.

Drift verhindern

5:29 Und jetzt zum Kern des ganzen zweiten Tages. Ein Vertrag ist nur so viel wert, wie die Zusicherung, dass die Implementierung sich daran hält. Sehen wir uns an, wie man das prüft, statt es zu hoffen. Wir haben zwei Tage in einen Vertrag investiert — und was bislang fehlt, ist der Beweis, dass die Anwendung ihn auch einhält. Diese Lücke schließen wir jetzt.

5:51 Drift ist ein passendes Wort, denn es beschreibt keine Katastrophe, sondern ein langsames Abdriften. Niemand entscheidet, dass der Vertrag jetzt falsch sein soll. Es passiert Änderung für Änderung, jede für sich harmlos. Nach einem halben Jahr behaupten Vertrag, Code und Dokumentationsseite drei verschiedene Dinge, und niemand weiß mehr, welches stimmt.

6:12 Die Antwort der OpenAPI-Initiative darauf besteht aus zwei Teilen: eine einzige Quelle der Wahrheit — und Prüfungen, die diese Wahrheit gegen die Wirklichkeit halten. Die ersten vier Schritte sind Fleißarbeit und schnell eingerichtet. Der fünfte ist der, auf den es ankommt und der am häufigsten fehlt: ein Konformitätstest, der die laufende Anwendung gegen den Vertrag prüft.

6:34 Ohne ihn haben Sie einen sorgfältig gepflegten Vertrag und keinerlei Beweis, dass Ihre Anwendung ihn erfüllt. Es ist genau die Lücke, die morgen Contract Tests schließen — mit einem anderen Ansatz, aber demselben Ziel. Die Fußnote bringt es auf den Punkt: Ohne diesen Schritt bleibt der Vertrag eine Behauptung. Linting hat den Ruf, Kosmetik zu prüfen, und das wird ihm nicht gerecht.

6:57 Der zweite Punkt betrifft Ihre Hausregeln, aber der dritte ist substanziell: Antworten ohne Schema und Endpunkte ohne Fehlerfall. Das sind keine Formfehler, sondern Lücken im Vertrag — Stellen, an denen ein Consumer raten muss. Und der vierte ist ein echtes Sicherheitsthema: eine Operation, an der die Sicherheitsangabe fehlt.

7:16 Im laufenden System ist der Endpunkt vielleicht geschützt, im Vertrag steht es nicht — und der Vertrag ist Ihr Inventar. Die ersten beiden Punkte beschreiben denselben Mechanismus in zwei Ausprägungen: Eine Prüfung, die nicht aufhält, wird ignoriert. Ob sie nur lokal läuft oder auf Warnung steht, macht keinen Unterschied — das Ergebnis ist eine Prüfung ohne Wirkung.

7:38 Der dritte Punkt ist die halbe Umsetzung des Konformitätstests: Nur der Erfolgsfall wird geprüft, und die Fehlerantworten bleiben unbewiesen. Und der vierte beschreibt, was immer zuerst driftet, nämlich separat gepflegte Dokumentation. Sie ist der erste Kandidat für die Erzeugung aus dem Vertrag.

Übung

7:56 In der Übung drehen wir die gewohnte Reihenfolge um. Der Consumer entsteht zuerst, gegen einen Mock — und der Provider kommt später. Genau so, wie Design-first es ermöglicht. Das Ziel ist dabei ausdrücklich nicht ein grünes Ergebnis, sondern eine Liste dessen, was Ihr Vertrag bisher nicht sagt. Sie holen jetzt ab, was in Ihrem Vertrag steckt. Aus der Hofkiste-Beschreibung entstehen Dokumentation, ein Mock Server und ein TypeScript-Client, der gegen den Mock läuft.

8:24 Das Erfolgskriterium hat einen dritten Teil, der wichtiger ist als die ersten beiden: Der Linting-Lauf soll mindestens drei benannte Schwachstellen Ihres Vertrags melden. Es geht also nicht darum, dass alles grün ist — es geht darum, dass Sie sehen, was Ihr Vertrag noch nicht sagt. Als Erweiterung erzwingen Sie im Mock eine Fehlerantwort.

8:44 Beachten Sie, dass Schritt eins die Beispiele für Erfolgs- und Fehlerfall verlangt. Ohne sie liefert der Mock leere Hüllen, und der Rest der Übung wird zäh. Schritt vier und fünf gehören zusammen: erst die Meldungen bewerten, dann die drei wichtigsten beheben. Bewusst nicht alle — ein Linting-Lauf produziert beim ersten Mal gern dreißig Meldungen, und die alle abzuarbeiten ist Fleiß ohne Erkenntnis.

9:08 Die Frage, welche drei wichtig sind, ist die eigentliche Übung. Der erste Punkt ist ein Einrichtungsfehler mit realem Risiko: Ein Client, der gegen die Produktionsadresse gebaut wird, weil sie im Vertrag stand. Der zweite Punkt hängt an Schritt fünf des vorigen Kapitels — nicht validierte Beispiele lassen den Mock Unsinn liefern, und Sie suchen den Fehler im Client.

9:29 Und der dritte ist die Reaktion, die man vermeiden sollte: Meldungen abschalten statt beheben. Wer das einmal tut, hat sein Linting zu einer Liste von Ausnahmen gemacht.