Von der Schnittstellenbeschreibung bis zum geprüften Objekt

Ein Typ ist eine Behauptung, keine Prüfung

TypeScript prüft, ob dein Code in sich stimmig ist. Was zur Laufzeit über das Netz kommt, sieht der Compiler nie. Deshalb liefert eine Antwort in TypeScript zunächst any oder unknown, und jedes as an dieser Stelle ist eine Behauptung, die niemand kontrolliert. Genau dort entsteht der Unterschied zwischen einem Programm, das bei falschen Daten eine verständliche Meldung zeigt, und einem, das an beliebiger Stelle stehen bleibt.

Die Prüfung an der Grenze kostet Rechenzeit, und das ist bei sehr großen Listen ein reales Argument. Der übliche Kompromiss: Antworten mit begrenzter Größe vollständig prüfen, bei sehr großen Sammlungen die Hülle prüfen und die Einträge stichprobenartig. Was du nicht tun solltest, ist die Prüfung wegzulassen und stattdessen in jeder Komponente defensiv auf Existenz zu testen, denn dann steht die Fehlerbehandlung an fünfzig Stellen und die Fehlerursache an keiner.

Erzeugte Typen gegen handgeschriebene

Handgeschriebene Typen sind vertretbar, wenn du zwei Endpunkte anbindest, die sich nicht ändern, und niemand sonst an ihnen arbeitet. Sobald mehrere Teams beteiligt sind, kippt die Rechnung, weil eine Änderung am Backend keine Spur im Frontend hinterlässt. Erzeugte Typen drehen das um: Nach jeder Erzeugung zeigt der Compiler an, wo die neue Beschreibung nicht mehr zum vorhandenen Code passt.

Die Grenzen liegen in der Qualität der Beschreibung. Wenn eine OpenAPI-Datei jedes Feld als optional oder als beliebiges Objekt beschreibt, sind auch die erzeugten Typen nutzlos. Achte besonders auf nullable-Angaben, denn ein Feld, das als Zeichenkette beschrieben ist und in Wirklichkeit null sein kann, produziert die unangenehmsten Fehler. Solche Abweichungen findet man nicht durch Lesen, sondern durch die Laufzeitprüfung, die dann meldet, dass Beschreibung und Wirklichkeit auseinandergehen.

Der Vollständigkeit halber: Es gibt Werkzeuge, die aus der Beschreibung gleich den ganzen Client samt Prüfschemata erzeugen. Das nimmt Arbeit ab und bindet dich an deren Vorstellung von Fehlerbehandlung, Zwischenspeicher und Abbruch. Für kleine Anbindungen lohnt der eigene dünne Client, für große Schnittstellenlandschaften spart die vollständige Erzeugung mehr, als sie an Freiheit kostet.

Wo die Laufzeitprüfung hingehört und wo nicht

Die Prüfung gehört an die Systemgrenze, also in die Funktion, die die Antwort entgegennimmt. Danach ist der Typ garantiert und der Rest der Anwendung arbeitet ohne zusätzliche Absicherung. Mit Zod schreibst du das Schema einmal und leitest den Typ daraus ab, sodass es keine zweite Quelle geben kann, die sich unbemerkt davon entfernt. safeParse ist dabei die richtige Variante, weil das Ergebnis den Fehlerfall mitführt, statt eine Ausnahme zu werfen, die irgendwo weiter oben gefangen wird.

Zwei Dinge lohnen sich an dieser Stelle zusätzlich. Erstens die Umwandlung: Ein ISO-Datum kommt als Zeichenkette an, und wenn es die Prüfung ohnehin anfasst, kann sie daraus direkt ein Date machen. Zweitens die Meldung: Der Fehlerpfad aus der Prüfung nennt das betroffene Feld, und dieser Pfad gehört ins Protokoll. Damit steht in der Fehlermeldung, welches Feld nicht gepasst hat, und nicht nur, dass die Antwort unerwartet war.

Nicht sinnvoll ist die Prüfung in Komponenten, in jedem Reducer oder rund um Daten, die deine eigene Anwendung erzeugt hat. Innerhalb des Systems gilt der Typ. Wer überall prüft, verlangsamt die Anwendung und verwässert die Aussage, denn dann sagt eine fehlgeschlagene Prüfung nicht mehr, dass eine fremde Quelle etwas anderes geliefert hat.

Was passiert, wenn sich die Schnittstelle ändert

Änderungen sind der Normalfall, und die Frage ist nur, wer sie zuerst bemerkt. Additive Änderungen, also neue Felder und neue optionale Parameter, sind ungefährlich. Gefährlich sind Umbenennungen, verschärfte Pflichtfelder, geänderte Typen und neue Werte in einer Aufzählung, denn genau diese Fälle sehen in der Antwort harmlos aus.

Der Abgleich in der Pipeline ist die billigste Absicherung: Typen neu erzeugen, mit den eingecheckten vergleichen, bei Unterschied abbrechen. Das kostet einen Schritt und liefert im Fehlerfall eine Zeile, die genau sagt, welches Feld sich geändert hat. Für neue Werte in einer Aufzählung hilft zusätzlich, im Code über alle Fälle zu verzweigen und den nicht behandelten Fall vom Compiler bemängeln zu lassen, statt einen Standardzweig zu bauen, der alles Unbekannte still schluckt.

Wenn Backend und Frontend getrennt ausgerollt werden, gehört noch eine Regel dazu: Die Beschreibung ändert sich zuerst, dann das Frontend, dann fällt das alte Feld weg. Wer diese Reihenfolge einhält, braucht keine Absprache über Zeitpunkte, und wer sie nicht einhält, braucht sie bei jeder Änderung neu.

GraphQL verschiebt die Frage, es beantwortet sie nicht

Bei GraphQL ist das Schema Teil des Servers, es kann also nicht veralten. Die erzeugten Typen beziehen sich nicht nur auf Objekte, sondern auf deine konkreten Abfragen, sodass jedes Feld, das du nicht abgefragt hast, im Typ auch nicht auftaucht. Das ist der eigentliche Vorteil gegenüber REST: Der Typ beschreibt genau das, was du angefordert hast.

Bleiben zwei Punkte, die Teams regelmäßig überraschen. Erstens die Nullbarkeit: In GraphQL ist alles voreingestellt nullbar, und ein Fehler in einem Teilbaum liefert Daten und Fehler gleichzeitig. Deine Anbindung muss also mit einer Antwort umgehen, die teilweise gefüllt ist. Zweitens die Frage, wer Abfragen kontrolliert: Ein Client kann sehr teure Abfragen stellen, deshalb arbeiten viele Teams mit fest hinterlegten Abfragen, was den Vorteil der freien Zusammenstellung wieder einschränkt.

Für die Typisierung heißt das: Der Weg ist derselbe, nur die Quelle ist eine andere. Schema holen, Typen für die eigenen Abfragen erzeugen, Antwort an der Grenze auf Vollständigkeit prüfen, Fehlerfeld auswerten. Wer das bei REST eingeübt hat, überträgt es in einem Nachmittag.