Startseite / Artikel

Praktische Hinweise: Typen von Frontend und Backend mit TypeScript synchron halten

Schritt-für-Schritt-Anleitung zu den Praktischen Hinweisen: Aufrechterhaltung der Synchronisation von Frontend- und Backend-Typen mit TypeScript – Verträge, Überprüfungen sowie Code-Slots für Teams, die dieses Muster einsetzen.

Verlag: REACTAPP.TOP7 Min. Lesezeit1637 Wörter

Quellen: Keeping Frontend and Backend Types in Sync with Typescript Magic

Nutzen Sie dies als für Entwickler zugängliche Neuformulierung der Ideen aus „Keeping Frontend and Backend Types in Sync with Typescript Magic“: klare Phasen, geordnete Codeabschnitte sowie Wiederherstellungshinweise, die auch bei Übergaben erhalten bleiben.

Der Fehler ohne Stack-Trace

Der Fehler, der in Phasen aufgeteilt wird, funktioniert am besten, wenn er als messbare Größe betrachtet wird. Erfassen Sie vor der Erweiterung des Umfangs ein „goldenes“ Transkript, einen Fehlerfall sowie die Notizen zur Rücksetzung. Erfassen Sie außerdem Zeiten sowie Kosten für Tokens oder Abfragen neben den funktionalen Ergebnissen. Eine frühzeitige Sichtbarkeit der Kosten verhindert überraschende Rechnungen, wenn der Prozess von einer Demo in gemeinsame Umgebungen übergeht. Halten Sie die Render-Arbeit kostengünstig und verschieben Sie aufwändige Berechnungen erst nach Messung hinter die Memoisierung – eine vorzeitige Memoisierung kann fehlerhafte Props verbergen.

// backend/src/topics/topics.service.ts
async findAll(): Promise<TopicRow[]> {
  return this.prisma.topic.findMany({ select: TOPIC_SELECT });
}
// frontend/src/types.ts
export interface TopicRow {
  id: string;
  code: string;
  requiresKey: boolean;
  // ...
}

Warum das dringend wurde

Die Herangehensweise, dies als dringenden Fall zu behandeln, funktioniert am besten, wenn sie als messbare Ebene betrachtet wird. Erfassen Sie einen gelungenen Transkriptbeispiel, einen Fehlerfall sowie die Notizen zur Rücksetzung, bevor Sie den Umfang erweitern. Bewahren Sie die Konfiguration außerhalb des Anwendungscode auf. Umgebungsdateien, Geheimdatenspeicher und Feature-Flags sollten an einem Ort zusammengefasst sein, den Betreuer ohne das Durchlesen des gesamten Systems überprüfen können. Halten Sie die Render-Arbeit kostengünstig und verschieben Sie aufwändige Berechnungen erst nach Messung hinter die Memoisierung – eine vorzeitige Memoisierung kann fehlerhafte Props verbergen.

Die Idee

Die Ideenphase funktioniert am besten, wenn sie als messbarer Bereich betrachtet wird. Erfassen Sie einen erfolgreichen Fallbeispiel, einen Fehlerfall sowie die Notizen zur Rücksetzung, bevor Sie den Umfang erweitern. Dokumentieren Sie gleichzeitig den erfolgreichen Ablauf und den Notfallweg. Wiederholungsversuche, menschliche Kontrollen sowie die Handhabung von Fehlern gehören zum Produkt selbst und nicht zu späteren Optimierungen. Halten Sie die Renderarbeiten kostengünstig und verschieben Sie aufwändige Berechnungen erst nach Messung hinter die Memoisierung – eine vorzeitige Memoisierung kann fehlerhafte Eigenschaften verbergen.

// backend/contract/assert.ts

/** The wire shape of a server value: JSON.stringify turns Date into string. */
export type Jsonify<T> = T extends Date
  ? string
  : T extends (infer U)[]
    ? Jsonify<U>[]
    : T extends object
      ? { [K in keyof T]: Jsonify<T[K]> }
      : T;
/** Invariant (not merely assignable) equality - catches widened optionals. */
export type Equal<A, B> =
  (<T>() => T extends A ? 1 : 2) extends (<T>() => T extends B ? 1 : 2)
    ? true
    : false;
export type Expect<T extends true> = T;
/** The element type of a service method that resolves to an array. */
export type RowOf<T> = Jsonify<Awaited<T>> extends (infer U)[] ? U : never;
/** The resolved wire shape of a service method. */
export type ResultOf<T> = Jsonify<Awaited<T>>;
/** The row type of a paginated `{ rows, total }` service method. */
export type PagedRowOf<T> =
  Jsonify<Awaited<T>> extends { rows: (infer U)[] } ? U : never;
// backend/contract/api-contract.ts
import type { Equal, Expect, PagedRowOf, RowOf } from './assert';
import type { TopicsService } from '../src/topics/topics.service';
import type { ContactRequestsService } from '../src/contact-requests/contact-requests.service';
import type { TopicRow, ContactRequestRow } from '../../frontend/src/types';

// GET /topics
export type _Topics = Expect<
  Equal<RowOf<ReturnType<TopicsService['findAll']>>, TopicRow>
>;
// GET /contact-requests (paginated)
export type _ContactRequests = Expect<
  Equal<PagedRowOf<ReturnType<ContactRequestsService['findAll']>>, ContactRequestRow>
>;

Die Magie des Tippen, erklärt

Die „Typing Magic explained“-Methode funktioniert am besten, wenn sie als messbarer Prozess betrachtet wird. Erfassen Sie vor der Erweiterung des Umfangs einen erfolgreichen Fall, einen Fehlerfall sowie die Notizen zur Rücksetzung. Ziehen Sie kleine, testbare Einheiten vor großen Skripten vor. Wenn ein Schritt fehlschlägt, sollte der Fehler auf eine einzige Verantwortung verweisen und nicht auf einen verworrenen Ablauf. Halten Sie die Render-Arbeit kostengünstig und verschieben Sie aufwändige Berechnungen erst nach Messung hinter die Memoisierung – eine vorzeitige Memoisierung kann Fehler mit veralteten Daten verbergen.

export type _Topics = Expect<
  Equal<RowOf<ReturnType<TopicsService['findAll']>>, TopicRow>
>;
type Equal<A, B> = A extends B ? (B extends A ? true : false) : false; // too loose
(<T>() => T extends A ? 1 : 2) extends <T>() => T extends B ? 1 : 2
export type RowOf<T> = Jsonify<Awaited<T>> extends (infer U)[] ? U : never;

Verschließen Sie es mit der Methode, nicht mit der Abfrage

Die Phase „Von der Quelle zur Ausführungsstufe“ funktioniert am besten, wenn sie als messbare Ebene betrachtet wird. Erfassen Sie ein „goldenes Transkript“, einen Fehlerfall sowie eine Notiz zur Rücksetzung, bevor Sie den Umfang erweitern. Betrachten Sie diese Phase als Vertrag zwischen Eingaben und validierten Ausgaben. Benennen Sie die Artefakte, definieren Sie Erfolgskontrollen und lehnen Sie stille, unvollständige Abschlüsse ab. Halten Sie die Renderarbeiten kostengünstig und verschieben Sie aufwändige Berechnungen erst nach Messung hinter die Memoisierung – eine vorzeitige Memoisierung kann veraltete Eigenschaftsbugs verbergen. Die Phase „Von der Quelle zur Ausführungsstufe“ funktioniert am besten, wenn sie als messbare Ebene betrachtet wird. Erfassen Sie ein „goldenes Transkript“, einen Fehlerfall sowie eine Notiz zur Rücksetzung, bevor Sie den Umfang erweitern. Halten Sie die Konfiguration außerhalb des Anwendungscode. Umgebungsdateien, Geheimdatenspeicher sowie Feature-Flags sollten an einem Ort gespeichert sein, den Betreuer ohne Durchsicht des gesamten Systems prüfen können.

// Wrong: misses everything the method does after the query
Equal<Jsonify<TopicSelectResult>, TopicRow>
// Right: whatever the method actually resolves to
Equal<RowOf<ReturnType<TopicsService['findAll']>>, TopicRow>

In Betrieb nehmen

In der Phase „In Betrieb nehmen“ sollten die Eingaben, der Verantwortliche für den Schritt sowie die Abbruchkriterien definiert werden, bevor der Code geändert wird. Die Operator sollten in der Lage sein, den Schritt von einem bekannten Checkpoint aus erneut auszuführen, ohne auf versteckten Zuständen schließen zu müssen. Dokumentieren Sie gemeinsam den erfolgreichen Ablauf sowie den Notfallweg. Wiederholungsversuche, menschliche Überprüfungen und die Handhabung von Fehlern gehören zum Produkt selbst und nicht zu späteren Optimierungen. Platzieren Sie den Zustand zusammen mit dem Komponenten, der für die Änderung verantwortlich ist. Das Hinzufügen aller Daten zu einem globalen Speicher erschwert die Erkennung von Zeitproblemen.

// backend/tsconfig.contract.json
{
  "extends": "./tsconfig.json",
  "compilerOptions": {
    "noEmit": true,
    "rootDir": "..",              // program spans both packages
    "module": "preserve",
    "moduleResolution": "bundler" // resolve the way the frontend's bundler does
  },
  "include": ["src/**/*", "contract/**/*", "../frontend/src/types.ts"]
}
{ "scripts": { "check:contract": "tsc -p tsconfig.contract.json" } }

Fehler abrufen

Für die Fehlerstufe beim Lesen sollten Eingaben, der Verantwortliche für den Schritt sowie die Abbruchkriterien vor dem Ändern des Codes definiert werden. Die Operator sollten in der Lage sein, den Schritt von einem bekannten Checkpoint aus erneut auszuführen, ohne auf versteckte Zustände schließen zu müssen. Man sollte kleine, testbare Einheiten vor umfangreichen Skripten bevorzugen. Wenn ein Schritt fehlschlägt, sollte der Fehler auf eine einzige Verantwortung verweisen und nicht auf ein verworrenes Ablaufschema. Der Zustand sollte zusammen mit dem Komponenten gespeichert werden, der die Änderung verantwortet. Das Hinzufügen aller Daten in einen globalen Speicher erschwert das Erkennen von Zeitproblemen.

type P1 = A extends B ? true : false;        // false => server is narrower / has extra
type P2 = B extends A ? true : false;        // false => frontend is wider
type Extra = Exclude<keyof A, keyof B>;      // fields the server sends, frontend lacks
type Missing = Exclude<keyof B, keyof A>;    // fields the frontend invented

Was es kostet und wo es nicht ankommt

Für die Abschnitte „Was kostet es“ und „Phase“ sollten vor dem Ändern des Codes die Eingaben, der Verantwortliche für den Schritt sowie die Abbruchkriterien definiert werden. Die Operator sollten in der Lage sein, den Schritt von einem bekannten Checkpoint aus erneut auszuführen, ohne auf versteckte Zustände schließen zu müssen. Betrachten Sie diese Phase als Vertrag zwischen den Eingaben und den validierten Ausgaben. Benennen Sie die Artefakte, definieren Sie Erfolgskontrollen und lehnen Sie stille, unvollständige Abschlüsse ab. Platzieren Sie den Zustand zusammen mit dem Komponenten, der für die Mutation verantwortlich ist. Das Hinzufügen aller Daten zu einem globalen Speicher erschwert das Erkennen von Zeitproblemen. Für die Abschnitte „Was kostet es“ und „Phase“ sollten vor dem Ändern des Codes die Eingaben, der Verantwortliche für den Schritt sowie die Abbruchkriterien definiert werden. Die Operator sollten in der Lage sein, den Schritt von einem bekannten Checkpoint aus erneut auszuführen, ohne auf versteckte Zustände schließen zu müssen. Halten Sie die Konfiguration außerhalb des Anwendungscode. Umgebungsdateien, Geheimdatenspeicher und Feature-Flags sollten an einem Ort gespeichert werden, den die Operator überprüfen können, ohne den gesamten Ablauf durchlesen zu müssen.

Der Kernpunkt

Während der Phase „Der Kernpunkt“ sollten Sie zunächst den Vertrag aufschreiben: erforderliche Eingaben, Erfolgsignal sowie das Vorgehen bei teilweisen Fehlern. Diese Checkliste sorgt dafür, dass spätere Codeänderungen transparent bleiben. Dokumentieren Sie gleichzeitig den erfolgreichen Ablauf sowie den Notfallweg. Wiederholungsversuche, menschliche Überprüfungen und die Handhabung von Fehlern gehören zum Produkt selbst, nicht zu späteren Optimierungen. Betrachten Sie Auswirkungen als Synchronisierung mit der Außenwelt – nicht als Ersatz für berechnete Werte während der Darstellung.

Operative Checkliste

Während der Phase „Operative Checkliste“ sollten Sie zunächst den Vertrag aufschreiben: erforderliche Eingaben, Erfolgssignal sowie das Vorgehen bei teilweisen Fehlern. Diese Checkliste sorgt dafür, dass spätere Codeänderungen transparent bleiben.

Notieren Sie neben den funktionalen Ergebnissen auch die Laufzeiten sowie die Kosten für Tokens oder Abfragen. Eine frühzeitige Sichtbarkeit der Kosten verhindert überraschende Rechnungen, wenn der Ablauf von einer Demo in gemeinsame Umgebungen übergeht.

Betrachten Sie Effekte als Synchronisierung mit der Außenwelt und nicht als Ersatz für berechnete Werte während der Renderung.

Festlegen Sie die Abhängigkeitsversionen und speichern Sie den Bilddigest, mit dem die Demo ausgeführt wurde. Reproduzierbarkeit ist besser als „Stammeswissen“.

Lassen Sie die Konfiguration außerhalb des Anwendungscode liegen. Umgebungsdateien, Geheimdatenspeicher und Feature-Flags sollten an einem Ort zusammengefasst sein, den Betreiber überprüfen können, ohne den gesamten Ablauf durchzulesen.

Betrachten Sie Effekte als Synchronisierung mit der Außenwelt und nicht als Ersatz für berechnete Werte während der Renderung.

Vor der Einführung neuer Komponenten sollten Sie die Versionen einfrieren, ein „goldenes Transkript“ für den kritischen Ablauf erstellen und die Rollback-Schritte überprüfen. Gemeinsam genutzte Umgebungen benötigen Rate Limits, Überprüfungen der Nutzerzuordnung sowie einen klaren Verantwortlichen für den Wechsel von Geheimdaten. Wählen Sie langweilige Zuverlässigkeit statt cleverer, einmaliger Demos.

Batch-Hinweis für 99a16b87e27d: Halten Sie die Anbieter-Schlüssel außerhalb des Repositories, legen Sie eine Obergrenze für Tokens pro Sitzung fest und speichern Sie die Transkripte neben den Evaluierungs-Dateien, damit spätere Modellwechsel vergleichbar bleiben.