JSON bis TypeScript: Typen, die der Realität entsprechen

Warum handgeschriebene Schriften driften

Aus der Dokumentation oder aus dem Speicher geschriebene Schnittstellen sind tendenziell optimistisch. Sie markieren alles, was vorhanden ist, gehen davon aus, dass immer ein Nullable-Feld vorhanden ist, und übersehen stillschweigend das verschachtelte Objekt, das nur auf Premium-Konten erscheint. TypeScript erzwingt dann eine Form, die der Server nie versprochen hat, und die ersten `undefined` tauchen in der Produktion und nicht zur Kompilierungszeit auf. Das Generieren aus realen Antworten kehrt den Prozess um: Der Compiler prüft eine beobachtete Form statt einer erhofften.

Lesen der generierten Datei

Eine nützliche Konvertierung benennt verschachtelte Objekte nach ihren Schlüsseln, behält die Array-Elementtypen bei und drückt die Unsicherheit explizit aus. Achten Sie auf die drei Markierungen, die die gesamte Bedeutung tragen:

                export interface Order {
  id: string;
  total: number;
  coupon?: string;            // absent in some responses
  shippedAt: string | null;   // present but null until shipped
  items: Array<OrderItem>;
}
              

Der Unterschied zwischen `coupon?: string` und `shippedAt: string | null` ist nicht kosmetischer Natur. Optional bedeutet, dass der Schlüssel fehlen kann; null bedeutet, dass der Schlüssel ohne Wert vorhanden ist. APIs führen beides aus, oft in derselben Nutzlast, und wenn man sie zusammenführt, wird eine Nullprüfung in den Code verschoben, der eine Zeichenfolge annimmt.

Verwenden Sie mehr als eine Probe

Eine einzige Antwort markiert alles, was erforderlich ist. Fügen Sie zwei oder drei Antworten ein – idealerweise eine von einem leeren Konto und eine von einem vollständigen – und die optionalen Schlüssel werden sichtbar: Ein Feld, das in einer Stichprobe fehlt, wird zu `?`, und ein Feld, das manchmal null ist, wird zu einer Vereinigung mit `null`. Dies ist das kostengünstigste verfügbare Korrektheits-Upgrade und der Grund dafür, dass generierte Typen neu generiert werden sollten, wenn sich API ändert, anstatt nur einmal geschrieben zu werden.

Lassen Sie niemals zu, dass eine generierte Schnittstelle die einzige Beschreibung Ihres API ist. Behalten Sie daneben einen Schema- oder Vertragstest bei, damit ein Serverwechsel einen Build und nicht eine Benutzersitzung zum Scheitern bringt.

Wo die Typen hingehören

• Ein dedizierter `types/`- oder `api/`-Ordner, der nicht über Komponenten verteilt ist.
• Eine Datei pro Endpunkt oder pro Ressource, mit einem Kommentar, der den Endpunkt und das Datum der Erfassung nennt.
• Ein Regenerationshinweis: Welcher Anruf hat die Nutzlast erzeugt, sodass die nächste Person sie wiederholen kann?
• Ein Export, der sowohl von der Abrufschicht als auch von den Komponenten verbraucht wird, sodass eine Änderung genau eine Stelle beschädigt.

Aktivieren Sie den strikten Modus

Generierte Typen zahlen sich nur aus, wenn `strict` aktiviert ist, denn das macht einen optionalen Schlüssel zu einem tatsächlichen Fehler, wenn direkt darauf zugegriffen wird. Koppeln Sie generierte Schnittstellen mit `unknown` an der Abrufgrenze und grenzen Sie sie vor der Verwendung ein: `JSON.parse` gibt `any` zurück, daher sollte eine Umwandlung in die generierte Schnittstelle der Punkt sein, an dem Sie validiert haben, und nicht dort, wo Sie hoffen.

Generieren Sie aus Nutzdaten, die Sie nicht hochladen würden

API-Antworten sind die sensibelsten JSON-Antworten, mit denen die meisten Entwickler umgehen – Kontodaten, Bestellungen, Token. Wenn Sie die Konvertierung von JSON zu TypeScript im Browser ausführen, wird die Nutzlast lokal analysiert und nie übertragen. Sie können also eine echte Antwort einfügen, ohne sie vorher zu redigieren, und das Tool funktioniert weiterhin offline.