JSON zu TypeScript: Generieren Sie genaue Schnittstellen aus realen API-Daten

Der Bug, der mich schließlich dazu brachte, keine handschriftlichen API-Typen mehr zu schreiben, war peinlich klein Ein Zahlungsendpunkt kehrte zurück discount: null Für Kunden ohne, und ich hatte es getippt discount: number Denn die eine Antwort, die ich beim Schreiben der Oberfläche angeschaut habe, war zufällig ein Kunde mit Rabatt TypeScript war vollkommen zufriedenDer Compiler hatte keine Möglichkeit zu wissen, dass I' d es belogen hat Drei Wochen später ein .toFixed(2) Auf diesem Gebiet wurde die Produktion genau für die Teilmenge der Benutzer eingestellt, die für meine Tests und vor allem für die Rechnung am wichtigsten waren.

Das ist das ganze Problem bei der manuellen Eingabe einer API: Sie tippen, was Sie eingeben Glauben glauben Der Endpunkt kehrt zurück, und der Compiler setzt pflichtbewusst eher Ihren Glauben als die Realität durchJede Garantie, die TypeScript Ihnen im Downstream gibt, ist nur so gut wie diese erste handgeschriebene Schnittstelle, und es gibt nichts in der Toolchain, das sie gegen eine tatsächliche Antwort prüft Sie erhalten die ganze Zeremonie des statischen Tippens ohne die Sicherheit, die wohl schlechter ist als gar keine Typen - zumindest macht untypisierter Code misstrauisch.

Typen aus einer echten Nutzlast zu generieren, dreht die Richtung, statt zu beschreiben, was man für eine Form hält, nimmt man eine Antwort, die der Server tatsächlich gesendet hat, und leitet daraus die Form ab Die Ausgabe ist mechanisch: kein Optimismus, keine Felder, die man vergessen hat, existierten, nein number Wo die Daten sagen number | null. Ich baue [Toolz.dev] (/ und setze ein browserbasiertes JSON-zu-TypeScript-Konverter Dort macht das das, aber in diesem Leitfaden geht es um die Inferenzregeln selbst - was ein Generator herausfinden kann, was er nur erahnen kann und wo man noch denken muss.

tl; dr: Um JSON in TypeScript zu konvertieren, schließen Sie aus seinem Wert auf jeden Schlüssel und #39;s-Typ (string, number, boolean, null), verschachtelte Objekte in ihre eigenen benannten Schnittstellen extrahieren und Arrays von Objekten in einer Einzelelementschnittstelle zusammenführen, wo jeder Schlüssel, der einigen Mitgliedern fehlt, optional wird Entscheiden Sie bewusst, ob null Mittel key?: T oder key: T | null- diese Wahl hängt davon ab, ob Ihre API fehlende Felder weglässt oder sie als Null sendet. Die Schlussfolgerung spiegelt nur die von Ihnen bereitgestellte Stichprobe wider. Verwenden Sie also eine repräsentative Nutzlast mit mehreren Datensätzen und behandeln Sie die Ausgabe als überprüften ersten Entwurf und nicht als fertigen Vertrag.

Warum TypeScript-Typen aus JSON generieren, anstatt sie zu schreiben?

Die ehrliche Antwort ist, dass handgeschriebene Typen driften und generierte Typen don' t. Wenn das Backend ein Feld hinzufügt, bleibt Ihre handgeschriebene Oberfläche stillschweigend falsch; keine Fehler, da zusätzliche Eigenschaften in einer Antwort für einen Typ unsichtbar sind, der sie nicht erwähnt. Wenn sich das Backend ändert id Von einer Zahl zu einer Zeichenfolge besteht Ihre Benutzeroberfläche weiterhin darauf. & #39;s eine Zahl und TypeScript stimmt immer wieder zu, bis etwas verkettet wird, anstatt hinzuzufügen.

There' s auch das einfache Tedium-Argument Eine typische REST-Antwort hat dreißig Tasten über vier Ebenen der Verschachtelung Das von Hand zu transkribieren dauert zehn Minuten rein mechanische Arbeit, und mechanische Arbeit, die von Menschen ausgeführt wird, hat eine Defektrate Sie werden einen Schlüsselnamen tippen Sie werden das eine Feld verpassen, das ' s ein Array von Objekten anstatt ein Array von Zeichenfolgen Der Generator wird nicht.

Aber der stärkste Grund ist, dass die Generation die Form herstellt Sichtbar. Fügen Sie eine Antwort in einen Konverter ein und Sie sehen sofort Dinge, die Sie & #39; d beim Lesen von rohem JSON beschönigt haben: das metadata Ist eigentlich ein tief verschachteltes Objekt, das tags Ist manchmal leer, dass in einigen Datensätzen die Hälfte der Schlüssel in Ihrer paginierten Liste fehlt Die generierte Oberfläche ist eine Zusammenfassung der realen Struktur von data's, und das Lesen ist oft die schnellste Möglichkeit, einen Endpunkt zu verstehen, den Sie geschrieben haben. & #39;t. I' habe es mehr als einmal als Dokumentationsschritt bei APIs verwendet, deren Dokumente gelogen waren.

Wo dies zu Ihren anderen Datentools passt: Wenn Sie & #39; die Nutzlast überprüfen, anstatt sie einzugeben, ist die JSON-Formater Ist der bessere erste Stopp, und wenn Sie & #39; vergleichen Sie zwei Antworten, um zu sehen, was sich zwischen den Versionen geändert hat, die json diff Antworten, die direkt.

Wie funktioniert die Typinferenz von JSON eigentlich?

JSON hat sechs Werttypen pro RFC 8259: Objekt, Array, Zeichenfolge, Zahl, true/false, und null. TypeScript' s primitive Typen bilden sich fast direkt auf vier davon ab Die interessante Arbeit ist vollständig in den anderen beiden.

Primitive sind trivial. Ein Zeichenfolgenwert impliziert string. Eine Zahl impliziert number- beachten Sie, dass JSON einen numerischen Typ hat, also gibt es & #39;s keine Informationen in den Daten, die Ihnen sagen, ob 1 Ganzzahl oder ein Float ist, und TypeScript macht & #39; unterscheidet sowieso nicht. true oder false impliziert boolean. Dieser Teil hat keine Mehrdeutigkeit.

Objekte werden zu Schnittstellen. Jeder Objektwert wird zu einer benannten Schnittstelle, und der Schlüssel, unter dem er erschien, liefert den Namen, konvertiert in PascalCase Ein Schlüssel owner Erzeugt interface Owner. Nesting rekursiv: ein Objekt im Inneren eines Objekts erzeugt eine zweite Schnittstelle, auf die von der ersten verwiesen wird Das ist wichtiger als es klingt Die Alternative - jede verschachtelte Form anonym zu inlinieren - erzeugt eine einzige unlesbare Deklaration und gibt Ihnen nichts Importables:

// Inlined: technically correct, practically useless
interface Project {
  owner: { id: number; email: string; twoFactor: boolean }
}

// Extracted: you can import and reference Owner on its own
interface Project {
  owner: Owner
}

interface Owner {
  id: number
  email: string
  twoFactor: boolean
}

Einmal Owner Als Name existiert, kann eine Funktion eingegeben werden, die nur den Besitzer übernimmt (owner: Owner) => void. Mit der Inlined-Version you'd schreiben Project['owner'] Überall, was funktioniert, sich aber schlecht liest.

Arrays sind der Ort, an dem die wahren Entscheidungen leben. Ein Array's-Typ ist die Vereinigung seiner Elementtypen, also [1, 2, 3] gibt number[] und [1, "a"] gibt (number | string)[]. Beachten Sie die Klammern in dieser zweiten - ohne sie number | string[] Bedeutet etwas ganz anderes (eine Zahl oder Eine Reihe von Zeichenfolgen) und Generatoren, die diesen Code vergessen, der kompiliert, aber das Falsche beschreibt.

Leere Arrays sind eine ehrliche Sackgasse. "tags": [] Sagt Ihnen, dass ein Schlüssel existiert und ein Array enthält; es sagt Ihnen nichts darüber, was darin enthalten ist Die richtige Ausgabe ist unknown[], und das solltest du lesen, da der Generator sich eher weigert zu raten, als als eine fertige Antwort Füllen Sie es selbst aus der Dokumentation aus, oder finden Sie ein Sample, wo das Array ist't leer.

Warum werden Arrays von Objekten zusammengeführt statt gewerkschaftlich organisiert?

Dies ist die einzige Entscheidung, die einen Generator von Ihnen trennt. & #39;d verwenden von einem Sie und #39;d nach fünf Minuten abbrechen.

Betrachten Sie eine paginierte Antwort, bei der die Aufzeichnungen & #39;t vollkommen einheitlich sind - das heißt, jede echte paginierte Antwort:

{
  "rows": [
    { "id": 1, "name": "Ada", "nickname": "The Countess" },
    { "id": 2, "name": "Grace" }
  ]
}

Behandeln Sie jedes Element unabhängig und Sie erhalten eine Vereinigung zweier Schnittstellen: rows: (Row1 | Row2)[]. Das ist Technisch Die genaueste Lektüre der Probe, und sie ist nutzlos Jeder Zugriff auf row.nickname Jetzt muss eingeengt werden, denn TypeScript can' weiß, welches Mitglied der Gewerkschaft Sie haben Erweitern Sie das auf eine Antwort mit fünfzig Datensätzen mit mehreren optionalen Feldern und Sie erhalten eine Vereinigung von Dutzenden nahezu identischer Schnittstellen Das will niemand.

Die nützliche Lektüre ist, dass diese beiden Objekte zwei Instanzen einer Entität sind und nickname Ist ein Feld Grace does't hat:

interface Row {
  id: number
  name: string
  nickname?: string
}

interface T {
  rows: Row[]
}

That' s eine Zusammenführung: sammeln Sie jeden Schlüssel, der über alle Elemente gesehen wird, und markieren Sie einen Schlüssel optional, wenn es's fehlt in einem von ihnen Es stimmt mit der tatsächlichen Produktion der Daten überein - eine Datenbanktabelle, ein Serialisierer, einige nullierbare Spalten - und es erzeugt Typen, die Sie ohne Zeremonie verwenden können Der Name des Array-Elements ist ebenfalls singularisiert, also releases Erträge Release anstatt Releases„weil releases: Releases[] Liest sich wie ein Fehler, auch wenn es 't.

Der Kompromiss ist real und es lohnt sich, ihn klar zu formulieren: Beim Zusammenführen wird davon ausgegangen, dass das Array homogen ist. Wenn Sie ein wirklich heterogenes Array haben - ein Feed von Ereignissen mit unterschiedlichen Formen, unterschieden durch a type Feld - Zusammenführen flacht verschiedene Varianten zu einer Schnittstelle, wo fast alles optional ist That' s das falsche Modell, und it' s ein Fall, wo Sie die generierte Ausgabe als Ausgangspunkt nehmen und eine richtige diskriminierte Union von Hand schreiben sollten Generatoren don' kennen Ihre Domäne nicht Diese führt Objekte zusammen und vereint alles andere, was die meiste Zeit richtig und falsch ist, so dass Sie es sofort erkennen können.

Soll null ein optionaler Schlüssel oder ein Gewerkschaftsmitglied werden?

Beide Konventionen sind vertretbar und der Unterschied ist bissig. Entscheiden Sie sich also für den Zweck, anstatt zu akzeptieren, was auch immer Ihr Tool standardmäßig akzeptiert.

Gegeben { "retiredAt": null }Es gibt zwei Lesungen:

interface A { retiredAt?: string }      // the field may be absent
interface B { retiredAt: string | null } // the field is present and may be null

Sie sind nicht austauschbar In A, retiredAt ist string | undefined Und der Schlüssel könnte auf dem Objekt gar nicht existieren In B„Der Schlüssel existiert immer und sein Wert könnte sein null. Unter strictNullChecks- welche die TypeScript-Handbuch Empfiehlt und was Sie haben sollten - beide zwingen Sie, den abwesenden Fall zu bearbeiten, erzwingen jedoch unterschiedliche Kontrollen und sie werden unterschiedlich serialisiert. JSON.stringify Unterlässt undefined Eigenschaften vollständig und emittiert null Bei Null-Eins breitet sich die Auswahl also bis zum Draht aus.

Die richtige Antwort hängt von der API's tatsächlichem Verhalten ab, das kein Generator anhand eines Beispiels sehen kann:

Ihr API's-Verhalten	Korrektes Modell	wieso
Verlässt den Schlüssel, wenn dort's kein Wert	key?: T	Der Schlüssel ist wirklich & #39;t da; optional ist genau
Schickt immer den Schlüssel null Wenn leer	key: T | null	Der Schlüssel ist immer vorhanden; ? Abwesenheit zu Unrecht zulassen würde
Inkonsistent - manchmal weggelassen, manchmal null	key?: T | null	Beide Fälle sind real; modellieren Sie beide
Sendet null Nur auf Fehlerantworten	Weder - modellieren Sie den Fehler separat	Ein nullbares Feld verbirgt eine Vereinigung von Antwortformen

Diese letzte Zeile ist diejenige, auf der es sich lohnt, innezuhalten Ein Feld, das nur in Fehlerfällen null wird, ist ein Signal, dass der Endpunkt zwei verschiedene Dinge in einer Form zurückgibt, und der Fix ist eine diskriminierte Vereinigung auf einem Statusfeld, keine nullierbare Eigenschaft Typgenerierung legt dieses Muster an; es tut & #39; t lösen es.

Der Konverter ist standardmäßig auf key?: T Weil weggelassen-wenn-abwesend ist die häufigere Konvention in den JSON APIs I & #39; mit gearbeitet haben, und weil es besser mit der oben beschriebenen Array-Zusammenführung zusammensetzt (ein Schlüssel, der in einigen Datensätzen fehlt, und ein Schlüssel, mit dem & #39; s null in einigen Datensätzen auf die gleiche Weise modelliert werden).Schalten Sie die Option aus und null Bleibt stattdessen in der Union Beides ist kein Trick; Wählen Sie diejenige aus, die Ihre API tatsächlich durchführt.

Was ist mit Schlüsseln, die & #39; t gültige TypeScript-Kennungen sind?

JSON-Objektschlüssel sind beliebige Zeichenfolgen TypeScript-Eigenschaftsnamen in einem blanken key: T Position sind nicht - es müssen gültige Kennungen sein Also "content-type", "2fa", "user.name", und "" Sind alle legale JSON-Schlüssel, die nicht unzitiert in einer Schnittstelle geschrieben werden können.

Der Fix ist ein Zitat, und it's kein Workaround - zitierte Eigenschaftsnamen sind gewöhnliches TypeScript:

interface Headers {
  "content-type": string
  "2fa": boolean
  class: string
}

Auf diese Eigenschaften wird mit Klammernotation zugegriffen (headers["content-type"]), die etwas ausführlicher, aber völlig typsicher ist Beachten Sie das class does' Es ist kein Zitat erforderlich: Reservierte Wörter sind völlig legal GrundstücksnamenObwohl sie' als Kennungen illegal sind Die Einschränkung gilt nur dort, wo TypeScript eine Kennung erwartet - weshalb dasselbe Wort behandelt werden muss, wenn es zu einer Schnittstelle wird Namedrohen

Von solchen Schlüsseln abgeleitete Schnittstellennamen erfordern mehr Arbeit als das Zitieren. 2fa PascalCases bis 2fa, die can' t eine Kennung starten, so erhält sie ein Präfix Zwei verschiedene verschachtelte Objekte beide unter Schlüsseln mit Namen owner Würden beide sein wollen OwnerSo wird die Sekunde Owner2. Das sind unschöne Details, und sie' sind genau die Details, die entscheiden, ob die erzeugte Ausgabe kompiliert oder eine Viertelstunde Handreparatur benötigt, bevor sie es tut Der Test, auf den ich den Konverter halte, ist einfach: alles Gültige einfügen, und die Ausgabe sollte unter kompilieren strict Ohne Bearbeitungen.

Schnittstellen oder Typaliase?

Der Generator emittiert entweder Die praktischen Unterschiede sind eng, aber real, und Ihre Codebasis hat wahrscheinlich bereits eine Meinung in ihrer Fusselkonfiguration kodiert.

interface User {} Unterstützt Deklarationszusammenführung - deklarieren Sie zweimal denselben Schnittstellennamen und TypeScript kombiniert sie. That' s ist für die Erweiterung von Typen aus Bibliotheken, die Sie nicht verwenden, unerlässlich. & #39; t-Steuerung und überall sonst eine Fußflinte, da zwei unabhängige Deklarationen mit demselben Namen stillschweigend zusammengeführt werden, anstatt Fehler zu machen. Schnittstellen unterstützen auch extends, die etwas bessere Fehlermeldungen als Schnittpunkttypen erzeugt, wenn eine Einschränkung fehlschlägt.

type User = {} can't fusionieren, was normalerweise eine Funktion ist, und es's Erforderlich Für alles, was & #39; t eine Objektform ist: Vereinigungen, Tupel, zugeordnete Typen, bedingte Typen Eine Wurzel, die & #39; t ein JSON-Objekt - ein Array von Zahlen, eine bloße Zeichenfolge - ist, kann nur als Alias ausgedrückt werden, also type Nums = number[] ist, was man unabhängig von der Einstellung bekommt.

Für generierte API-Typen tendiere ich zu interfaceMeistens, weil die Fehlermeldungen geringfügig besser sind und weil das Zusammenführungsrisiko theoretisch ist, wenn jeder Name in einer generierten Datei lebt Aber das ist nahe an einem Münzwurf, und die Konsistenz mit dem umgebenden Code ist wichtiger als die Vorzüge Wenn Ihre ESLint-Konfiguration hat @typescript-eslint/consistent-type-definitions So oder so einstellen, abgleichen und nicht mehr darüber nachdenken.

Wie unterscheidet sich das von JSON Schema zu TypeScript?

Diese lösen wirklich unterschiedliche Probleme und es's lohnt sich, präzise zu sein, da "JSON zu TypeScript" und "JSON Schema zu TypeScript" sind ein Wort voneinander entfernt und werden häufig verwechselt.

JSON zu TypeScript ist eine Schlussfolgerung aus einem Beispiel. Eingabe: ein Wert Der Generator beobachtet dort was' s und verallgemeinert Es kann nicht wissen, ob ein Feld benötigt wird, ob eine Zeichenfolge auf eine Enum beschränkt ist, ob eine Zahl ein Minimum hat oder ob die eine Probe, die Sie eingefügt haben, repräsentativ ist It' s Induktion aus einer einzigen Beobachtung, mit allem, was impliziert.

JSON Schema zu TypeScript ist die Übersetzung aus einer Deklaration. Eingabe: a JSON-Schema Dokument, in dem bereits Typen angegeben sind, required Arrays, Enums, Formate und Einschränkungen Der Generator ist ' t raten - it' s transliterieren einen bestehenden Vertrag in TypeScript-Syntax. required Karten auf nicht optionale Eigenschaften; ein enum Zu einer Zeichenfolgen-Wortverbindung abbilden; oneOf Zu einem Unionstyp abbildet.

Es folgt direkt die Regel: Wenn ein Schema existiert, verwenden Sie es. Ein JSON-Schema, eine OpenAPI-Spezifikation, a .proto Datei, oder ein GraphQL-Schema ist in einer Weise autoritativ, wie es eine abgetastete Antwort nie ist Inferenz ist das, wonach man greift, wenn kein Schema existiert - ein undokumentierter interner Endpunkt, eine API eines Drittanbieters, deren Dokumente veraltet sind, ein Konfigurationsdateiformat, das organisch gewachsen ist, eine Vorrichtung, gegen die man & #39; re Tests schreibt, die fairerweise muss man sagen, einen großen Teil des JSON beschreibt, mit dem sich jeder von uns tatsächlich befasst.

There's ein erwähnenswerter Mittelweg: Verwenden Sie Inferenz zu BootstrapDanach von Hand warten Die Oberfläche aus einer echten Antwort generieren, um die Form und die Feldnamen richtig zu machen, dann bearbeiten - straffen a string Zu einer wörtlichen Vereinigung, in der Sie die zulässigen Werte kennen, legen Sie eine fest unknown[] Die Probe blieb leer, teilte eine zusammengeführte Schnittstelle in eine richtige diskriminierte Vereinigung auf. Der Generator erledigt die mechanischen 90% und Sie wenden das Domänenwissen an, das er strukturell nicht haben kann.

Woher bringt Schlussfolgerung etwas falsch?

Eine kurze, ehrliche Liste Jede von diesen ist eine Einschränkung des Ansatzes, kein Bug in einem bestimmten Tool, und sie zu kennen ist der Unterschied zwischen generierten Typen gut zu verwenden und von ihnen verbrannt zu werden.

Einzelne Proben bestimmen den Typ unter. Ein Feld, das & #39;s number In Ihrer Stichprobe könnte sein null In 5% der Datensätze Ein Feld, das & #39; s in allen drei Datensätzen, die Sie eingefügt haben, vorhanden ist, könnte optional sein über den gesamten Datensatz Inferenz berichtet, was es gesehen hat Fügen Sie mehr Datensätze ein - idealerweise eine echte Seite mit Ergebnissen statt eines handverlesenen Objekts - und die Optionale werden aussagekräftig genauer.

Saiten verbergen ihre echten Typen. ISO-Zeitstempel, UUIDs, URLs und E-Mail-Adressen sind alle nur string zu einem JSON-Parser. "2026-07-16T09:00:00Z" Semantisch ein Datum ist; nichts in den Daten sagt es aus Wenn Ihre Codebasis ein Branding hat ISODateString Geben Sie you' ein, indem Sie es von Hand ersetzen.

Zahlen verlieren Präzisionsunterschiede. JSON' s Einzelnummertyp bedeutet eine ID, die & #39; s eine 64-Bit-Ganzzahl auf dem Server als JavaScript-Nummer eintrifft und möglicherweise bereits an Präzision verloren hat, bevor Ihr Generator sie jemals sieht - Number.MAX_SAFE_INTEGER Ist etwa 9 ×10¹5, und Twitter hat das bekanntermaßen auf die harte Tour gelernt Wenn Ihre API große ganze Zahlen als Zeichenfolgen sendet, dann & #39;s warum, und die generierte string Richtig ist.

Literale Werte sehen aus wie ihre allgemeinen Typen. "status": "active" Folgert string, nicht "active" | "archived" | "pending". Der engere Typ ist nützlicher und kein Sample kann es beweisen Das ist die häufigste Handbearbeitung, die ich an der erzeugten Ausgabe durchführe.

Leere Behälter sagen nichts. [] gibt unknown[] und {} Leerschnittstelle gibt Beides ist der Generator ehrlich.

Nichts davon macht Schlussfolgerungen unsicher - es macht sie zu einem Entwurf. Der Arbeitsablauf, der funktioniert, ist: generieren, lesen Sie die Ausgabe sorgfältig, beheben Sie die vier oder fünf Dinge, die Sie wissen, dass die Probe konnte' sagen, commit. That's immer noch eine Größenordnung schneller und genauer als die Transkription von dreißig Schlüsseln von Hand, was die eigentliche Alternative ist.

Wird mein JSON irgendwo hochgeladen?

Nein, und dies ist eine Kategorie von Werkzeugen, bei denen die Frage eine echte Antwort und nicht ein Abzeichen verdient.

Überlegen Sie, was' s im JSON you' d in einen Typgenerator einfügen It' s eine API-Antwort, das heißt, es enthält plausibel ein Träger-Token, eine Sitzungskennung, eine Kunden-E-Mail, eine interne Benutzer-ID, eine Preisstufe, ein Webhook-Geheimnis. That's nicht hypothetisch - it's der modale Fall, denn der ganze Punkt ist, dass Sie sich einen geschnappt haben echt Antwort auf Typ gegen.

Jeder serverseitige Konverter empfängt diese Nutzlast zwangsläufig. Es kann sein, dass er sie nicht protokolliert, und das tut er wahrscheinlich auch. #39; t, aber you' re Erweiterung des Vertrauens, das Sie nicht tun. #39; müssen sich erweitern, und abhängig von den Daten erstellen Sie möglicherweise ein Compliance-Problem für eine Aufgabe, die überhaupt nichts damit zu tun hat, ein Netzwerk zu berühren.

Typinferenz ist reine Berechnung über einen analysierten Wert Es braucht kein Netzwerk, kein Konto, keinen Speicher Der Konverter auf Toolz.dev ist ein paar hundert Zeilen abhängigkeitsfreies TypeScript, das in Ihrem Tab ausgeführt wird; die Nutzlast ist ein JavaScript-String in Ihrem Browser' s-Speicher und es bleibt dort Sie können dies überprüfen, wie Sie & #39;d jeden solchen Anspruch überprüfen - öffnen Sie die Netzwerk-Registerkarte und drücken Sie Generieren, oder schalten Sie Ihr WLAN aus und beobachten Sie, wie es weiter funktioniert Dies ist das gleiche Prinzip hinter jedem Tool auf der Website, und I & #39; habe darüber geschrieben, warum es in breiterem Sinne wichtig ist Warum browserbasierte Tools bei sensiblen Daten serverseitige Tools schlagendrohen

Ein gearbeitetes Beispiel

Hier und #39; ist das Beispiel, mit dem das Werkzeug geliefert wird und das bewusst so konstruiert ist, dass es alle oben genannten Regeln ausübt:

{
  "id": 4821,
  "name": "Toolz",
  "isPublic": true,
  "retiredAt": null,
  "owner": {
    "id": 12,
    "email": "[email protected]",
    "twoFactor": false
  },
  "tags": ["developer", "privacy", "browser"],
  "releases": [
    { "version": "1.0.0", "downloads": 1420, "notes": "First cut" },
    { "version": "1.1.0", "downloads": 3310 }
  ]
}

Mit der Wurzel benannt ProjectDas erzeugt:

export interface Project {
  id: number
  name: string
  isPublic: boolean
  retiredAt?: null
  owner: Owner
  tags: string[]
  releases: Release[]
}

export interface Owner {
  id: number
  email: string
  twoFactor: boolean
}

export interface Release {
  version: string
  downloads: number
  notes?: string
}

Lesen Sie, was passiert ist. owner In eine eigene Schnittstelle extrahiert und namentlich referenziert wurde. tags Zusammengebrochen string[] Denn jedes Element war eine Zeichenfolge. releases Seine beiden Mitglieder zu einem zusammengeschlossen Release- singularisiert - und notes Optional wurde, da die zweite Version & #39;t hatte eine. retiredAt Optional wurde, da sein einziger beobachteter Wert null war.

Und jetzt lesen Sie, was Sie'd beheben. retiredAt?: null Ist der Generator's ehrlicher Bericht, dass es noch nie einen Nicht-Null-Wert gesehen hat, und es's als Typ nutzlos - Sie'd ändern es in retiredAt?: string Weil Sie es wissen's einen Zeitstempel, wenn vorhanden Diese einzelne Bearbeitung ist die ganze Lektion: Der Generator hat die Sieben-Tasten-Struktur, die Verschachtelung, die Array-Zusammenführung und die Optionalität direkt in einer Paste erhalten und Ihnen die einzige Entscheidung hinterlassen, die das Wissen über das Feld erforderte.

FAQ

Wie konvertiere ich JSON in eine TypeScript-Schnittstelle?

Fügen Sie Ihren JSON in den Konverter ein, setzen Sie den Namen des Root-Typs auf den Namen der Ressource und drücken Sie Generate. Es leitet den Typ jeder Taste ab, zieht verschachtelte Objekte in ihre eigenen benannten Schnittstellen, führt Arrays von Objekten in einen einzelnen Elementtyp zusammen und gibt Code aus, den Sie direkt in einen kopieren können .ts Datei. There' s kein Anmelden und kein Upload - die Inferenz läuft in Ihrem Browser.

Was passiert mit Arrays von Objekten?

They' werden in eine Schnittstelle zusammengeführt, die ein einzelnes Element beschreibt, und die Eigenschaft wird als Array davon eingegeben Jeder Schlüssel, der in einigen Array-Mitgliedern erscheint, aber nicht in anderen, wird optional Dies entspricht dem Verhalten realer paginierter Daten, wobei Datensätze aus einer Tabelle stammen und einige Spalten nullbar sind Der einzige Fall, den es schlecht verarbeitet, ist ein wirklich heterogenes Array verschiedener Ereignistypen, das Sie von Hand in eine diskriminierte Union umwandeln sollten.

Soll null ein optionaler Schlüssel oder eine Vereinigung mit null werden?

Es kommt darauf an, ob Ihre API fehlende Felder weglässt oder als null sendet, wenn sie diese weglässt, wird key?: T Genau ist Wenn der Schlüssel immer vorhanden und manchmal null ist, key: T | null ist genau und verwendet ? Würde fälschlicherweise zulassen, dass der Schlüssel fehlt Der Konverter ist standardmäßig optional und ermöglicht den Wechsel, da die beiden unterschiedlich serialisiert werden - JSON.stringify Lässt undefinierte Eigenschaften fallen, gibt aber null aus.

Kann aus einer einzelnen JSON-Stichprobe genaue Typen abgeleitet werden?

Es lässt genaue Typen zu Für diese ProbeDas ist & #39; t dasselbe Ein Feld, das & #39; s eine Zahl in Ihrem einen Datensatz ist, könnte in anderen null sein; ein Feld, das in allen drei Datensätzen vorhanden ist, die Sie eingefügt haben, könnte im gesamten Datensatz optional sein Verwenden Sie eine repräsentative Nutzlast mit mehreren Datensätzen anstelle eines handverlesenen Objekts und behandeln Sie die Ausgabe als überprüften Entwurf und nicht als fertigen Vertrag.

Was' Ist der Unterschied zwischen JSON zu TypeScript und JSON Schema zu TypeScript?

Dieses Tool leitet Typen aus einem Beispielwert ab; JSON Schema zu TypeScript übersetzt ein formales Schema, das bereits Typen, erforderliche Felder und Enums deklariert Das Schema ist maßgeblich und die Schlussfolgerung ist eine Vermutung. Wenn Sie also ein JSON-Schema, eine OpenAPI-Spezifikation oder ein GraphQL-Schema haben, verwenden Sie es Die Schlussfolgerung gilt für den sehr häufigen Fall, in dem kein Schema existiert und Sie lediglich ein Antwortgremium haben.

Wie geht es mit Schlüsseln um, die & #39;t gültige Identifikatoren?

In der Ausgabe werden Tasten mit Strichen, Punkten, Leerzeichen oder führenden Ziffern angegeben "content-type" wird "content-type": string. That' s gültiges TypeScript, abgerufen mit Klammerschreibweise Reservierte Wörter wie class Don' t muss als Eigenschaftsnamen zitiert werden Von solchen Schlüsseln abgeleitete Schnittstellennamen sind PascalCased und werden vorangestellt, wenn sie' d mit einer Ziffer beginnen und kollidierende Namen ein numerisches Suffix erhalten, sodass die Ausgabe immer kompiliert wird.

Soll ich Schnittstellen generieren oder Aliase eingeben?

Passen Sie an, was Ihre Codebasis bereits tut - dies ist größtenteils eine Konsistenzfrage. Schnittstellen unterstützen die Zusammenführung von Deklarationen und extendsUnd geben Sie geringfügig klarere Fehlermeldungen an Geben Sie Aliase can't zusammen, was normalerweise wünschenswert ist, und sind für alles erforderlich, was 't eine Objektform ist. Eine Wurzel, für die 's ein Array oder ein Primitiv wird in beide Richtungen als Alias ausgegeben, da dort & #39;s kein Objekt ist, für das eine Schnittstelle deklariert werden kann.

Wird mein JSON auf einen Server hochgeladen?

Nein. Die gesamte Inferenz-Engine läuft als JavaScript in Ihrem Browser, ohne Netzwerkaufrufe, ohne Protokollierung und ohne Speicher Das ist hier wichtiger als bei den meisten Tools, denn das Einfügen von JSON you' d in einen Typgenerator ist normalerweise eine echte API-Antwort, die Token, Kundendatensätze oder interne IDs enthält Öffnen Sie Ihren Netzwerk-Tab während der Generierung oder trennen Sie die Verbindung zum Internet - es funktioniert weiter.

---

Verwandte Werkzeuge: JSON-Formater Zur Überprüfung der Nutzlast zuerst json zu Yaml und JSON zu XML für Formatkonvertierung und json diff für das Erkennen, was sich zwischen zwei Antworten geändert hat. Weiterlesen: Der ultimative Leitfaden für JSON-Tools und Das Programmier-Tools des Entwicklersdrohen