JSON in TypeScript umwandeln: ? und | in Interfaces lesen

VeröffentlichtToolJSON → TypeScript-Typen generieren

Inhalt
  1. Probleme beim manuellen Tippen von Typen für JSON mit Arrays
  2. So leiten Sie Typen allein aus einem JSON-Beispiel ab
  3. Häufig verwechselte Schreibweisen im Ergebnis
  4. Zusammenfassung
  5. Häufig gestellte Fragen

Wenn Sie anhand eines JSON-Beispiels aus einer API-Antwort ein TypeScript-interface von Hand tippen, kommt irgendwann der Moment, in dem unklar wird, an welchen Schlüssel ein Fragezeichen (?) gehört.

Fragezeichen und Union (|) sind keine Gefühlssache, sondern Ergebnis fester Regeln. Wer sie kennt, kann automatisch erzeugten Code mit bloßem Auge prüfen.

In diesem Artikel gehen wir diese Regeln an einem konkreten JSON durch und zeigen, warum verschachtelte Objekte nicht in einem großen interface landen, sondern auf mehrere aufgeteilt werden.

Kurzfassung ① Schlüssel, die nur in einem Teil der Array-Elemente vorkommen, erhalten ein optionales ?; kommt der Schlüssel in allen Elementen vor, entfällt es. ② Hat derselbe Schlüssel je nach Element Werte unterschiedlicher Art (Typen), werden diese zu einer Union (|) zusammengefasst. ③ Verschachtelte Objekte und Objekte in Arrays erhalten einen vom Schlüsselnamen abgeleiteten Namen und werden in eigene interfaces ausgelagert.

Probleme beim manuellen Tippen von Typen für JSON mit Arrays

Häufig liegt keine API-Dokumentation vor, sondern nur ein einziges Beispiel einer echten Antwort, aus dem Sie die Typen ableiten müssen. Bei der Antwort einer Bestellliste kann das Array items pro Produkt unterschiedliche Felder enthalten.

Manche Produkte haben einen Rabattsatz (discountRate), andere nicht.

Typische Fehleinschätzungen beim Schreiben von Hand

Schreiben Sie das interface von Hand, passieren meist zwei Fehler.

Entweder machen Sie alle Felder optional (?), womit die Typsicherheit verloren geht. Oder Sie markieren ein Feld als Pflichtfeld, das tatsächlich nur in einem Teil der Elemente vorkommt – dann gibt es einen Kompilierfehler, sobald Sie ein anderes Antwortbeispiel verwenden.

Auch die Frage, wie weit verschachtelte Kundendaten (customer) oder Array-Elemente (items) im selben interface bleiben und ab wann sie ausgelagert werden, lässt sich von Hand schwer entscheiden.

Alle drei Entscheidungen – optional oder nicht, Union oder nicht, auslagern oder nicht – ergeben sich tatsächlich rein mechanisch aus der JSON-Struktur.

So leiten Sie Typen allein aus einem JSON-Beispiel ab

Auch ohne Tool kommen Sie mit der folgenden Reihenfolge von Hand zum selben Ergebnis.

  1. Notieren Sie die Schlüssel des obersten Objekts.
  2. Unterscheiden Sie bei jedem Schlüssel, ob der Wert ein primitiver Wert (String, Zahl, Boolean, null), ein Objekt oder ein Array ist.
  3. Bei primitiven Werten übernehmen Sie den Typ unverändert.
  4. Objektwerte lagern Sie in ein eigenes interface aus, dessen Name der in PascalCase umgewandelte Schlüsselname ist.
  5. Bei Arrays betrachten Sie alle enthaltenen Elemente zusammen als Vergleichsmenge (Stichprobe) und prüfen für jedes Element, ob ein Schlüssel vorhanden ist und von welcher Art der Wert ist.
  6. Schlüssel, die nur in einem Teil der Stichprobe vorkommen, erhalten ein Fragezeichen (?). Gibt es für den vorhandenen Wert mehrere Arten, verbinden Sie diese mit |.

Probieren wir es mit einem echten JSON:

{
  "orderId": 1024,
  "customer": { "name": "Max Mustermann", "email": "max@example.com" },
  "couponCode": "WELCOME10",
  "items": [
    { "productId": "A1", "price": 12000, "discountRate": 0.1 },
    { "productId": "A2", "price": 8000, "discountRate": null },
    { "productId": "A3", "price": 15000 }
  ]
}

orderId ist nur eine Zahl, also number; couponCode ist nur ein String, also string. customer ist ein Objekt und wird unter eigenem Namen ausgelagert.

Der Schlüsselname customer wird in PascalCase zu Customer. Da name und email darin beide Strings sind, ergibt sich { name: string; email: string }.

Die Elemente von items als Stichprobe vergleichen

items ist ein Array, also vergleichen wir die drei Elemente als Stichprobe. productId und price kommen in allen drei Elementen vor und haben jeweils nur eine Wertart (String bzw. Zahl), bleiben also string und number.

Bei discountRate steht im ersten Element eine Zahl, im zweiten null, und im dritten fehlt der Schlüssel ganz.

Da das Vorhandensein variiert, kommt ein Fragezeichen hinzu. Weil der vorhandene Wert entweder eine Zahl oder null ist, werden beide zur Union zusammengefasst: discountRate?: number | null.

Auch das Objekt im Array braucht einen Namen. Setzen wir items in den Singular item und wandeln es um, erhalten wir Item. Zusammengefasst sieht das von Hand erstellte Ergebnis so aus:

interface Customer {
  name: string;
  email: string;
}

interface Item {
  productId: string;
  price: number;
  discountRate?: number | null;
}

interface Root {
  orderId: number;
  customer: Customer;
  couponCode: string;
  items: Item[];
}

Bei nur drei Array-Elementen ist der Vergleich von Hand machbar. Echte API-Antworten enthalten aber Dutzende oder Hunderte Elemente und deutlich mehr Schlüssel. Je mehr es sind, desto eher übersieht man beim Vergleich mit bloßem Auge einen Schlüssel.

Probieren Sie es mit unserem Tool aus.

JSON → TypeScript-Typen generieren

Die Umwandlung erfolgt direkt im Browser. Das eingegebene JSON wird weder an einen Server gesendet noch gespeichert.

Häufig verwechselte Schreibweisen im Ergebnis

SituationErgebnisGrund
Schlüssel nur in einem Teil der Array-Elemente vorhandenkey?: TKommt nur in einem Teil der Stichprobe vor → optional
Derselbe Schlüssel mit Werten unterschiedlicher Artkey: A | BWertetyp unterscheidet sich je Stichprobe → Union
Nur teilweise vorhanden und Wertart unterschiedlichkey?: A | BVorhandensein und Wertart variieren gleichzeitig
Zwei verschiedene Objekte mit völlig identischer Schlüssel- und TypstrukturDasselbe interface wird wiederverwendetIdentische Strukturen werden unter einem Namen zusammengefasst
Verschachteltes Objekt / Objekt in einem ArrayAuslagerung in ein eigenes, benanntes interfaceDer Name wird vom Schlüsselnamen abgeleitet (PascalCase)

Ein wichtiger Hinweis: Fragezeichen und Union werden nur berechnet, wenn mehrere Stichproben zum Vergleich vorliegen. Fügen Sie ein einzelnes Objekt ohne jedes Array ein, gibt es nur einen Vergleichswert, und es erscheinen weder Fragezeichen noch Union.

Wenn Sie mehrere Antwortbeispiele gemeinsam prüfen möchten, packen Sie das oberste JSON selbst in ein Array und fügen mehrere Fälle auf einmal ein.

Den Namen des obersten Typs können Sie im Eingabefeld ändern (Standard: Root). Außerdem lässt sich per Option wählen, ob mit interface oder type deklariert wird und ob das Schlüsselwort export ergänzt wird (standardmäßig aktiviert).

Welche Deklarationsart Sie auch wählen: Die oben beschriebenen Regeln für optionale Felder, Unions und Auslagerung gelten unverändert.

Zusammenfassung

  • Ob ein Feld optional (?) ist, hängt davon ab, ob der Schlüssel nur in einem Teil der Stichprobe vorkommt.
  • Ob eine Union (|) entsteht, hängt davon ab, ob sich die Wertart des Schlüssels je Stichprobe unterscheidet.
  • Treffen beide Bedingungen zu, werden sie wie in key?: A | B gemeinsam angezeigt.
  • Verschachtelte Objekte und Objekte in Arrays werden mit einem vom Schlüsselnamen abgeleiteten Namen zu eigenen interfaces; bei gleicher Struktur werden sie wiederverwendet.
  • Fügen Sie nur ein einzelnes Objekt ohne Array ein, gibt es nur einen Vergleichswert, und Fragezeichen und Union erscheinen nicht.
JSON → TypeScript-Typen generieren

Die Umwandlung erfolgt direkt im Browser. Das eingegebene JSON wird weder an einen Server gesendet noch gespeichert.

Häufig gestellte Fragen

Wann genau wird ein Feld optional (?)?

Dann, wenn der Schlüssel nur in einem Teil der Array-Elemente (der Stichprobe) existiert. Kommt der Schlüssel in allen Elementen vor, wird er nicht optional, auch wenn der Wert null ist; dass null als Wertart vorkommt, wird stattdessen über die Union angezeigt.

Wann entsteht eine Union (|)?

Wenn sich der Wertetyp (String, Zahl, Boolean, null, Objekt usw.) desselben Schlüssels von Stichprobe zu Stichprobe unterscheidet, werden die Arten mit | verbunden. Gibt es nur eine Art, erscheint ein einfacher Typ ohne Union.

Warum werden verschachtelte Objekte aufgeteilt und nicht in ein einziges interface gepackt?

Objektwerte und Objekte in Arrays erhalten einen Namen, der aus dem in PascalCase umgewandelten Schlüsselnamen entsteht, und werden in ein eigenes interface (oder type) ausgelagert.

Sind die Objekte an zwei verschiedenen Stellen auch in Schlüsseln und Typen völlig identisch aufgebaut, wird nichts Neues angelegt, sondern dasselbe interface wiederverwendet.

Wird das eingegebene JSON auf einem Server gespeichert?

Nein. Das Parsen des JSON und die Typableitung laufen vollständig im Browser und werden bei jeder Eingabe sofort ausgeführt. Ihre Eingaben werden weder an einen Server gesendet noch gespeichert.

Dieser Artikel basiert auf unserem koreanischen Original. Koreanisches Original lesen

Ähnliche Artikel

  1. JSON zu YAML: Regeln für Arrays und EinrückungWie aus JSON-Arrays YAML-Listen mit Bindestrich werden, was 2 oder 4 Leerzeichen Einrückung ändern und welche Fehler bei Kubernetes und Docker oft passieren.
  2. JSONPath-Syntax erklärt: Was $, [*] und .. auswählenWas $, .Eigenschaft, [Zahl], [*] und .. in JSONPath auswählen, gezeigt an einem Beispiel-JSON. Dazu: warum Filterausdrücke und Slices hier nicht greifen.
  3. JWT dekodieren: Aufbau, Payload lesen und exp in DatumJWT ist nur Base64URL-kodiert, nicht verschlüsselt. So lesen Sie Header und Payload aus und wandeln exp und iat in ein lesbares Datum um.
  4. JWT-Signatur prüfen: Warum die Verifizierung fehlschlägtSo funktioniert die JWT-Prüfung mit HMAC-SHA256: Aufbau des Tokens, Signaturberechnung und die zwei Ursachen für fehlgeschlagene Verifizierung.
  5. line-clamp in CSS: Warum es nicht funktioniert und wie es gehtWenn line-clamp nicht greift, fehlt meist display: -webkit-box. Der Artikel zeigt per Code, warum ein- und mehrzeiliges Abschneiden verschiedene Properties nutzen.
  6. Aufzählungszeichen umwandeln: Markdown, HTML und eigene SymboleSo wandeln Sie Fließtext oder Listen in Markdown-Listen, HTML-Listen mit ul und li oder eigene Aufzählungszeichen um – samt typischer Stolperstellen.

Passende Tools