Ein JSON-Beispiel zeigt Formen und primitive Werte, die in einer Antwort vorkamen. Den vollständigen API-Vertrag beweist es nicht. Die Umwandlung in TypeScript ist trotzdem nützlich: Sie spart Abschreiben und macht Unsicherheit durch Vereinigungen, optionale Eigenschaften und unknown[] sichtbar.
Diese Anleitung gibt zwei synthetische Datensätze an das JSON-zu-TypeScript-Werkzeug. Enthalten sind null, eine fehlende Eigenschaft, ein verschachteltes Objekt mit optionalem Mitglied, Zahlen und leere Arrays. Das Ergebnis bleibt ein kompilierbarer Entwurf.
Grenzen der Stichprobe benennen
Hat dieselbe Eigenschaft beobachtbar verschiedene Typen, kann der Generator eine Union bilden. Fehlt sie in einem Objekt, wird sie optional. Explizites null bleibt enthalten. Diese Aussagen sind durch die Eingabe belegt.
Abwesenheit in einer kleinen Stichprobe beweist nicht, dass ein Feld nie existiert; ständige Anwesenheit beweist keine Pflicht. Ein leeres Array liefert keinen Elementtyp und wird ehrlich zu unknown[], nicht zu any[] oder einem erfundenen Fachtyp. Deklarationen helfen dem Compiler, prüfen aber keine künftige Netzwerkantwort zur Laufzeit.
Ein Beispiel, das Unsicherheit zeigt
Verwende exakt:
[
{
"id": 1,
"tag": "alpha",
"active": true,
"notes": [],
"meta": { "source": "api" }
},
{
"id": 2,
"tag": null,
"notes": [],
"meta": { "source": "cache", "age": 3 }
}
]
Wähle Wurzelname ApiResponse und type. Die Wurzel beschreibt ein Array zusammengeführter Objekte. id ist number, tag ist null | string, active ist wegen der Abwesenheit im zweiten Objekt optional, notes ist unknown[], und meta.age ist optional. Die Ausgabe ist deterministisch und kompilierbar; Leerraum ist kein semantisches Testergebnis.
Erzeugen, kompilieren und herausfordern
Füge das Beispiel ein, nenne die Wurzel ApiResponse, wähle type und erzeuge. Kopiere die Ausgabe in eine .ts-Datei eines streng geprüften Projekts. Ergänze einen passenden Wert für beide beobachteten Datensätze und führe den Compiler aus; es dürfen keine Diagnosen entstehen.
Füge danach absichtlich eine Zeichenkette als id ein. Der Compiler muss diese Zuweisung ablehnen. Das belegt statische Prüfung, nicht Laufzeitvalidierung einer HTTP-Antwort. Unbekannte Netzwerkdaten müssen nach dem JSON-Parse durch Schema oder Type Guard, bevor sie als ApiResponse gelten.
Wiederhole mit interface. Objektformen können Interfaces sein, ein Wurzelarray oder primitiver Wert benötigt jedoch weiterhin einen Alias. Vergleiche Bedeutung statt jedes Schlüsselwort. Lade die .ts-Datei herunter und kompiliere genau diese Fassung.
Wie die vorhandene Evidenz zusammengeführt wird
Der Generator betrachtet alle Objekte eines Arrays, nicht nur das erste. Er vereinigt Eigenschaftsmengen, kennzeichnet Abwesenheit mit ? und ordnet beobachtete Typen stabil. Verschachtelte Objekte bleiben Inline-Objekttypen. Arrays untersuchen alle Elemente; heterogene Elemente bilden eine Union, leere Arrays unknown[].
JSON-Zahlen werden number; die Stichprobe beweist weder Ganzzahligkeit noch Wertebereich. Zeichenketten bleiben string; es werden keine Datumswerte, Enums, URL-Brands oder Literaltypen geraten. Explizites null unterscheidet sich von fehlend. Unter strictNullChecks muss der Aufrufer die Union behandeln.
Eigenschaftsnamen, die keine Bezeichner sind, werden zitiert. Der Wurzelname selbst muss ein gültiger TypeScript-Bezeichner sein. Alphabetisch deterministische Felder machen wiederholte Generierung prüfbar: Ein Diff soll neue Eingabeevidenz statt zufälliger Traversierung zeigen.
Eingabe- und Erzeugungsfehler lösen
Ungültiges JSON muss an der Quelle korrigiert werden: nachgestellte Kommas, unzitierte Schlüssel, falsche Klammern oder kopierte Logpräfixe. Die JSON-Fehleranleitung bietet einen Ablauf. Ein JavaScript-Objektliteral ist erst nach gültiger JSON-Darstellung eine verlässliche Eingabe.
Ein ungültiger Wurzelname enthält etwa Leerzeichen oder Bindestrich, beginnt mit einer Ziffer oder ist sonst kein Bezeichner. Verwende ApiResponse, keine URL. Interne JSON-Schlüssel dürfen abweichen, weil sie zitiert werden.
Mehr als 200 KiB UTF-8 oder eine Tiefe über 50 wird abgelehnt. Reduziere auf repräsentative synthetische Datensätze, statt willkürlich Klammern zu löschen. Tief rekursive Nutzdaten brauchen ein entworfenes Modell, nicht einen riesigen Inline-Typ.
Aus dem Entwurf einen Vertrag machen
Vergleiche mit offizieller API-Spezifikation und Antworten für Erfolg, leer, Teilberechtigung, Altbestand und Fehler. Ändere Optionalität und Unions anhand dokumentierten Verhaltens. Benenne wiederverwendbare verschachtelte Konzepte und verweise in Kommentaren auf die Vertragsversion.
Verbinde statische Typen mit Laufzeitvalidierung an der Vertrauensgrenze. TypeScript-Typen werden in JavaScript gelöscht. Eine Type Assertion beruhigt den Compiler, ohne ein Byte zu prüfen. Parse JSON, validiere unknown und gib erst dann einen typisierten Wert weiter.
Nutze keine echten Kundenantworten. Obwohl die Berechnung lokal läuft, können Fixture, Download, Commit oder Screenshot Daten offenlegen. Minimiere und ersetze Kennungen. Die Datenschutzanleitung für Entwicklerwerkzeuge erläutert den weiteren Umgang.
Grenzen stichprobenbasierter Typen
Das Werkzeug sieht nur geliefertes JSON. Es entdeckt keine unbeobachteten Varianten, bedingten Pflichten, Wertebereiche, semantischen Formate oder künftigen API-Änderungen. Es liest kein OpenAPI, validiert keine Laufzeitwerte, erzeugt keine Codecs und garantiert keine repräsentative Stichprobe.
Alle Zahlen werden number; Zeichenketten werden keine Daten oder Enums; leere Arrays werden unknown[]; heterogene Arrays nutzen Unions; Eigenschaften werden nur bei beobachteter Abwesenheit optional. Eine inferierte Union erkennt nicht automatisch ein fachliches Diskriminatorfeld. Prüfe außerdem exactOptionalPropertyTypes, denn JSON kann undefined nicht darstellen. Grenzen sind 200 KiB und Tiefe 50.
Abschließende TypeScript-Prüfung
Nutze gültiges synthetisches JSON und einen gültigen Wurzelnamen. Liefere mehrere Objekte, wenn Optionalität oder Unions wichtig sind. Prüfe jedes ?, null, jede Union, Verschachtelung und jedes unknown[]. Wähle Interface oder Typ passend zum Projekt und akzeptiere einen Alias für Nichtobjekt-Wurzeln.
Kompiliere den exakten Download mit strengen Projekteinstellungen. Ergänze eine gültige und absichtlich ungültige Zuweisung. Vergleiche mit der Dokumentation und validiere nicht vertrauenswürdige Daten zur Laufzeit. Füge gültige leere und teilweise gefüllte Fälle zur Stichprobe hinzu. Bei Vertragsänderungen generiere neu, prüfe den Diff und aktualisiere Typ, Laufzeitvalidator und Fixture gemeinsam.
Teste eine Eigenschaft mit Bindestrich und bestätige ihre Zitierung. Verwende außerdem eine primitive Wurzel und ein Wurzelarray im Interface-Modus; beide brauchen einen Alias, weil ein Interface keine beliebige Wurzel beschreibt. So wird die Auswahl im Bedienfeld nicht als starre Zusage missverstanden.
Lege für das feste Beispiel eine gültige Zuweisung mit tag: null und eine mit active an. Ergänze absichtliche Fehler für Zeichenketten-id, falschen meta.age-Typ und Zugriff auf notes ohne Prüfung. Der Compiler meldet statische Fehler; der Laufzeitvalidator muss separat unerwartete Netzwerkdaten ablehnen.
Bewerte jede optionale Eigenschaft fachlich. Sie kann wegen fehlender Stichprobenevidenz optional erscheinen, obwohl die API sie garantiert, oder stets vorhanden wirken, obwohl Berechtigungen sie ausblenden. Korrigiere den Entwurf anhand des Vertrags und notiere die Fälle. Wiederhole die Prüfung bei jeder API-Version.
Leere Arrays bleiben unknown[], bis Elemente oder ein Schema den Typ belegen. Ersetze unknown nicht durch any, nur um Fehler zu vermeiden. Grenze Werte mit einem Guard ein oder setze nach Prüfung den dokumentierten Elementtyp. unknown markiert eine offene Entscheidung und schützt vor ungeprüften Methodenaufrufen.
Bei großen verschachtelten Objekten können benannte Typen lesbarer sein. Extrahiere sie nur für stabile Fachbegriffe. Die alphabetische Reihenfolge unterstützt reproduzierbare Diffs; eine redaktionelle Gruppierung darf Optionalität oder Nullbarkeit nicht verdecken. Bewahre das synthetische Fixture als Herkunftsnachweis.
Prüfe die generierte Datei mit genau derselben TypeScript-Version und denselben strengen Optionen wie die Anwendung. Ein separates Playground-Ergebnis reicht nicht, wenn exactOptionalPropertyTypes, Modulauflösung oder Bibliotheken abweichen. Lege einen kleinen Kompilierungstest im Projekt ab, der eine gültige Nutzung akzeptiert und eine markierte ungültige Nutzung bewusst zurückweist.
Wenn die API eine offizielle OpenAPI- oder JSON-Schema-Datei bietet, ist sie die bessere Vertragsquelle. Nutze die Inferenz dann zum schnellen Vergleich: Abweichungen zwischen Stichprobe und Schema sind Hinweise, keine automatische Entscheidung. Kläre, ob Dokumentation veraltet, die Antwort fehlerhaft oder das Beispiel unvollständig ist, bevor du den Typ änderst.
Behandle heruntergeladenen TypeScript-Code wie Quellcode. Prüfe Dateinamen, Lizenzhinweise und Formatierung, bevor du ihn eincheckst. Der Generator führt den Inhalt nicht aus, doch spätere manuelle Ergänzungen können Logik enthalten. Code Review und CI bleiben notwendig; lokal erzeugt bedeutet nicht automatisch fachlich geprüft.
Quellen: TypeScript Handbook: Object Types, TypeScript Handbook: Unions und RFC 8259: JSON.