JSON zu Go

Structs, die das JSON dekodieren, aus dem sie stammen

Fügen Sie eine JSON-Probe ein, und diese Seite schreibt Go-Deklarationen dafür: ein benanntes Struct für jedes Objekt in der Probe und an jedem Feld ein json-Tag, das den Schlüssel nennt, den das Feld liest. Ein Versprechen entscheidet alles, was folgt. In einem Programm, das mit Go 1.27 gebaut wird, dekodieren die Deklarationen das JSON, das Sie eingefügt haben, über "encoding/json" ohne Fehler, und jeder Schlüssel wird in ein Feld gelesen, außer einem Schlüssel, den kein Struct-Tag tragen kann: Dieser wird weggelassen. Wo Go dieses Versprechen nicht gelten lässt oder die Seite zwingt, etwas zu wählen, das Ihre Daten nicht entschieden haben, sagt ein Hinweis unter der Ausgabe, wo — mit einer seltenen Ausnahme, die im Abschnitt über die Tags beschrieben wird.

Die Form selbst wird ermittelt, bevor irgendetwas in Go geschrieben ist, und zwar vom selben Einlesen Ihres JSON, das auch die Seite JSON zu TypeScript speist. Die Elemente eines Arrays zusammenführen, Schlüssel bemerken, die nur manche von ihnen haben, null von einem Schlüssel trennen, der nie gesendet wurde, und jedes Objekt benennen, das in einem anderen steckt: All das behandelt der Leitfaden jener Seite, daher wird unten nichts davon wiederholt. Was folgt, ist der Teil von Go — ein Typ für jede Zahl, Zeiger, ein Typ für einen Schlüssel mit Werten verschiedener Art, Feldnamen, Tags und die Fragen, die die Hinweise aufwerfen.

Drei Zahlentypen, gewählt danach, wie jede Zahl geschrieben ist

Ein Browser, der JSON liest, macht aus 10 und 10.0 dieselbe Zahl. Go nicht: Ein "int64"-Feld lehnt eine Zahl ab, die mit Dezimalpunkt oder Exponent geschrieben ist — 10.0, 1e3, selbst -0.0 —, nimmt aber 11 und -0 an. Deshalb wählt die Seite einen Zahlentyp nicht allein nach den Werten. Sie fragt den eigenen Parser des Browsers, wie jede Zahl geschrieben war, und entscheidet danach:

• Wo jede Zahl an einer Position als ganze Zahl geschrieben ist, ohne Dezimalpunkt und ohne Exponent, ist das Feld "int64", und der Hinweis zu ganzen Zahlen nennt es.
• Jede andere Zahl ist "float64", ein als 10.0 geschriebener Preis ist also "float64", auch wenn jeder Preis in der Probe rund ist. Das Modul "json" von Python schreibt einen float mit ganzzahligem Wert genau so, und so ist eine von Python ausgelieferte API der übliche Ort, an dem man darauf stößt.
• "json.Number" bleibt den Zahlen vorbehalten, die keiner der beiden Typen genau fasst: einer ganzen Zahl jenseits eines der beiden Enden des Wertebereichs von "int64", einer Zahl, die für einen "float64" überhaupt zu groß ist, etwa 1e999, und einer ganzen Zahl, die für einen "float64" zu lang ist und neben einem Bruch steht, wie in [9007199254740993, 1.5]. Er bewahrt jede davon genau, und Ihr Programm wandelt ihn dort um, wo es den Wert verwendet.

Eine lange ganze Zahl unter anderen ganzen Zahlen braucht diese Sorgfalt nicht: [9007199254740993, 1] ist "[]int64". Ein Bruch mit mehr Stellen, als ein "float64" speichert, bleibt "float64" und wird in einem eigenen Hinweis genannt, denn dekodiert und erneut kodiert kommt 0.30000000000000001 als 0.3 zurück.

Um zu lesen, wie eine Zahl geschrieben war, braucht es einen Browser, der das meldet. Einer, der es nicht meldet, liest jede Zahl allein aus ihrem Wert, dort wirkt 10.0 also ganzzahlig, und sein Feld wird "int64", ein Feld, das dieses JSON nicht dekodiert; die Seite zählt die Zahlen, die sie nicht von ganzen unterscheiden konnte, und zeigt, wo die erste steht. Ein solcher Browser sieht auch die Stellen nicht, die ein "float64" fallen lässt, dort erhält eine lange ganze Zahl neben einem Bruch also den Typ "float64", und ein Bruch, der gerundet wird, wird nicht genannt.

Zeiger, wo ein Wert fehlen kann

Ein Schlüssel, den manche Objekte weglassen oder auf null setzen, ist ein Zeiger: "*string", "*int64" oder ein Zeiger auf das Struct, das für ein Objekt geschrieben wurde. Auch die Elemente eines Arrays, das null enthält, sind Zeiger, [1, null] ist also "[]*int64". Ein Schlüssel, der in manchen Objekten fehlt, wird in seinem Tag außerdem mit "omitzero" markiert. Mit beidem kann ein Feld sagen, ob ein Wert angekommen ist, und kodiert man das dekodierte Struct erneut, wird ein Schlüssel, den die Probe immer nur weggelassen hat, wieder weggelassen und einer, den sie immer nur auf null gesetzt hat, wieder als null geschrieben.

Ein Slice, eine Map, "any" und "json.RawMessage" erhalten keinen Zeiger, da jedes davon bereits nil ist, wenn nichts hinein dekodiert wurde. Ein Slice erhält trotzdem "omitzero", wo sein Schlüssel fehlen kann, und ein Array, das vorhanden, aber leer war, wird wieder als [] geschrieben.

Eine Unterscheidung überlebt nicht. Ein Schlüssel, der in manchen Objekten fehlt und in anderen null ist, ist in Go ein einziges nil, Ihr Programm kann die beiden Fälle also nicht unterscheiden, und kodiert man das Struct erneut, wird der Schlüssel weggelassen, auch wo die Probe null hatte; die Seite nennt jedes Feld, dem das passiert. Ein Schlüssel gemischter Arten behält den Unterschied, denn ein "json.RawMessage" bewahrt ein null als die Bytes null.

json.RawMessage für gemischte Arten und any, wo nichts gesehen wurde

Wenn die Werte eines Schlüssels in der Art voneinander abweichen — eine Zahl an einer Stelle, ein String oder ein Objekt an einer anderen —, ist das Feld "json.RawMessage": die eigenen Bytes des Werts, die Ihrem Programm überlassen bleiben, damit es sie dekodiert, sobald es nachgesehen hat, welche Art angekommen ist. Ein null darunter ändert nichts. Ist eine der Arten ein Objekt, wird das dafür ausgelagerte Struct trotzdem neben den anderen ausgegeben. Ein "any" würde ebenfalls jede Art annehmen, und es wird für eine Mischung nicht verwendet, weil eine in ein "any" dekodierte Zahl zu einem "float64" wird und alles verliert, was ein "float64" nicht fassen kann.

Manche Teile einer Probe bieten keinen Wert, aus dem sich etwas lernen ließe: ein Schlüssel, der immer nur null enthielt, ein Array, das jedes Mal leer war, ein Objekt ohne Schlüssel und ein Wert, der tiefer verschachtelt ist, als die Inferenz ihm folgen kann. In Go erhalten der Schlüssel mit null und der tief verschachtelte Wert "any", die Elemente des leeren Arrays "[]any" und das Objekt "map[string]any". Ein "any" nimmt jede Art von Wert an. Die Map nimmt ein Objekt oder null an, und ein String, eine Zahl, ein Array oder ein Wahrheitswert an ihrer Stelle lässt das Dekodieren scheitern.

Jenseits dieser Tiefe bleiben in den Hinweisen zwei Dinge ungesagt. Ein Schlüssel dort, der in manchen Objekten fehlt und in anderen null ist, wird nur als Position genannt, an der es nichts gab, woraus sich ein Typ ableiten ließ, und wo er null war, lässt Go ihn beim Zurückschreiben weg. Und eine ganze Zahl, die länger ist, als ein "float64" fasst, kommt gerundet zurück, aus 9007199254740993 wird 9007199254740992, weil die Position ein "any" ist.

Feldnamen im Stil von Go, Struct-Namen gemeinsam mit der TypeScript-Seite

Der Name eines Felds ist sein Schlüssel in der Schreibweise von Go. Der Schlüssel wird an jedem Zeichen, das weder Buchstabe noch Ziffer ist, in Wörter zerlegt, ebenso überall dort, wo auf einen Kleinbuchstaben ein Großbuchstabe folgt; dann werden die Wörter zusammengefügt, jedes mit einem Großbuchstaben am Anfang, sodass aus "user_name", "last-name" und "firstName" UserName, LastName und FirstName werden. Ein Wort auf der Standardliste der Abkürzungen von staticcheck wird in Großbuchstaben geschrieben — "id" wird zu ID, "api_key" zu APIKey, "video_url" zu VideoURL —, aber nur ein ganzes Wort zählt, also wird "idle" zu Idle und der Plural "ids" zu Ids. Ein Schlüssel, der ganz in Großbuchstaben geschrieben ist, wird als Wörter gelesen: "USER_ID" wird zu UserID.

Die eigenen Buchstaben des Schlüssels bleiben erhalten, aus "имя" wird also Имя. Wo ein Name nicht mit einem Großbuchstaben beginnen würde — bei einem Schlüssel in einem Schriftsystem ohne Großbuchstaben wie "名前", einem Schlüssel, der mit einer Ziffer beginnt, wie "1st", oder einem ersten Buchstaben ohne Großbuchstaben aus einem einzigen Zeichen wie "ß" —, wird ihm ein X vorangestellt, also X名前, X1st und Xß, und das Feld liest seinen Schlüssel trotzdem. Kombinierende Zeichen werden aus dem Namen weggelassen und im Tag behalten. Ein Schlüssel ganz ohne Buchstaben oder Ziffern, etwa "@", heißt Field, und ein Name, der im selben Struct schon vergeben ist, erhält eine Zahl: "user_id", "userId" und "USER_ID" zusammen werden zu UserID, UserID2 und UserID3.

Der Stil von Go reicht bis zu den Feldnamen und endet dort: Jedes Struct behält den Namen, den die Inferenz für sein Objekt gewählt hat, sodass die Deklarationen hier und die Interfaces auf der TypeScript-Seite gleich heißen und ein Feld anders geschrieben sein kann als das Struct, das in ihm enthalten ist. Wie dieser Name gewählt wird, ist Sache des Leitfadens der TypeScript-Seite.

Tags für Go 1.27 und die Schlüssel, die kein Tag tragen kann

Das Tag jedes Felds nennt seinen Schlüssel exakt, wie in json:"user_id", mit ,omitzero nach dem Schlüssel, wo der Schlüssel fehlen kann. Ein Steuerzeichen in einem Schlüssel wird mit der Escape-Sequenz geschrieben, die Go selbst verwendet, und der Schlüssel "-" wird als json:"-," geschrieben, eine Form, die Go als eben diesen Schlüssel liest.

Die Tags sind für Go 1.27 geschrieben. Go 1.26 liest über ein Tag weniger Schlüssel: Ein Schlüssel, der etwas anderes enthält als Buchstaben, Ziffern, das ASCII-Leerzeichen und eine Reihe von ASCII-Satzzeichen — "Price (€)", "temp °C", ein Emoji, ein Steuerzeichen, ein kombinierender Akzent —, wird dort nicht gelesen, und die Seite nennt jedes solche Feld. Diese Hälfte wird gegen ein mit "GOEXPERIMENT=nojsonv2" gebautes Go 1.27 geprüft, das Tags wie Go 1.26 liest, aber mit den neueren Unicode-Tabellen von Go 1.27, daher wird ein Schlüssel mit einem Buchstaben, den die älteren Tabellen von Go 1.26 nicht haben, bei dieser Prüfung gelesen und löst keinen Hinweis aus.

Ein Schlüssel, der ein Komma, einen Rückstrich, ein Anführungszeichen, einen Apostroph oder einen Gravis enthält, oder der leere Schlüssel ist ein Schlüssel, den kein Struct-Tag tragen kann, und bekommt daher überhaupt kein Feld. Ihr JSON wird trotzdem dekodiert: "json.Unmarshal" überspringt diesen Schlüssel ohne Beanstandung, ein auf "DisallowUnknownFields" gesetzter "json.Decoder" hält allerdings bei ihm an. Der Hinweis führt einen solchen Schlüssel über sein Struct und den Schlüssel auf, so in Anführungszeichen gesetzt, wie Go einen String setzt, etwa Order["note,internal"], und für ein Objekt unter einem solchen Schlüssel wird sein Struct trotzdem ausgegeben. Ein Fall bleibt ohne Hinweis: Zwei Schlüssel, die sich nur in einem einzelnen Ersatzzeichen unterscheiden, einer Escape-Sequenz, die für kein Zeichen steht, sind für Go derselbe Schlüssel, und keines ihrer Felder wird gefüllt.

Nur Deklarationen, im Layout von gofmt

Die Ausgabe enthält Typdeklarationen und sonst nichts: keine package-Klausel und kein import, sie kommt also in eine Datei, die Sie schon haben, unter die eigene package-Klausel dieser Datei. Wo sie "json.RawMessage" oder "json.Number" verwendet, importiert die Datei außerdem "encoding/json", und das ist die eine Zeile, die Ihnen oder Ihrem Editor bleibt. Das Layout ist das von gofmt selbst — ein Tabulator vor jedem Feld und die Namen, Typen und Tags jedes Structs in ausgerichteten Spalten —, daher lässt gofmt es genau so, wie es ist. Der Typ der Wurzel wird zuerst ausgegeben, jedes Objekt ist ein benannter Typ statt eines Structs, das direkt in das Feld geschrieben ist, in dem es steht, und JSON, das auf oberster Ebene ein Array oder ein einzelner Wert ist, ist ebenfalls ein benannter Typ, etwa "type Root []RootItem", sodass es immer einen Typ gibt, in den es sich dekodieren lässt.

Was die Hinweise Sie zu prüfen bitten

Jede Art von Entscheidung, die Go erzwungen hat, bekommt einen Eintrag unter den Deklarationen, und der Eintrag sammelt jede Stelle, für die er gilt, sodass eine Probe mit vielen ganzzahligen Feldern einen Eintrag bekommt und nicht einen pro Feld. Stellen werden so geschrieben, wie die Deklarationen sie schreiben — Order.UserID ist ein Feld, Order.Tags[] sind die Elemente eines Arrays, und die Wurzel ist ihr bloßer Name —, außer in zwei Einträgen, die stattdessen mit Zeile und Spalte in Ihr JSON zeigen: ein zweimal geschriebener Schlüssel und Zahlen, die dieser Browser nicht von ganzen unterscheiden konnte. Keiner davon ändert die Deklarationen. Lesen Sie jeden als Frage an Ihre Daten:

• Ganze Zahlen mit dem Typ "int64". Jede Zahl dort war als ganze Zahl geschrieben. Wenn ein später eintreffender Wert einen Dezimalpunkt oder einen Exponenten tragen kann, wie es ein Preis oder ein Messwert kann, lässt er sich nicht dekodieren, machen Sie dieses Feld also zu "float64"; eine ID oder eine Anzahl kann bleiben, wie sie ist.
• "json.Number". Kein anderer Zahlentyp fasst diese Werte genau. Wandeln Sie jeden dort um, wo Ihr Programm ihn verwendet, oder ändern Sie das Feld selbst, wenn Sie wissen, dass die tatsächlichen Werte in einen engeren Typ passen.
• Ein Bruch, den "float64" rundet. Eine Zahl dort hat mehr Stellen, als ein "float64" speichert, Ihr Programm sieht also einen nahen Wert statt des geschriebenen. Wo jede Stelle zählt, machen Sie das Feld zu "json.Number".
• Gemischte Arten, als "json.RawMessage" bewahrt. Sehen Sie sich jeden Wert beim Eintreffen an und dekodieren Sie ihn als die Art, als die er sich herausstellt; ist eine Art ein Objekt, steht sein Struct trotzdem in der Ausgabe, damit sich dieser Wert hinein dekodieren lässt.
• Nichts, woraus sich ein Typ ableiten ließ. Das Feld ist "any" oder eine Map von "any", weil die Probe dort keinen Wert enthielt, aus dem sich lernen ließe. Ersetzen Sie es durch den Typ, von dem Sie wissen, dass das Feld ihn trägt, oder konvertieren Sie erneut aus JSON, in dem es echte Werte enthält.
• In manchen Objekten fehlend, in anderen null. Go speichert beides als ein nil, daher wird der Schlüssel beim Zurückschreiben weggelassen. Das zählt nur, wenn das, was Ihre Ausgabe liest, ein null anders behandelt als einen Schlüssel, der nicht da ist.
• Schlüssel, die Go 1.26 nicht liest. Bauen Sie mit Go 1.27, oder benennen Sie diese Schlüssel dort um, wo sie entstehen; unter Go 1.26 bleiben sie ungelesen.
• Weggelassene Schlüssel. Sie haben kein Feld. Um einen davon zu lesen, dekodieren Sie das Objekt in eine "map[string]json.RawMessage" oder schreiben Sie eine "UnmarshalJSON"-Methode für das Struct, wie es der Hinweis selbst vorschlägt.
• Ein zweimal geschriebener Schlüssel. Die Typen folgen der letzten Kopie des Schlüssels, doch Go dekodiert jede Kopie der Reihe nach, daher lässt eine frühere Kopie, die der Typ nicht fassen kann, etwa ein String, wo die letzte Kopie eine Zahl ist, das Dekodieren einen Fehler zurückgeben, und ein Schlüssel, der nur in einer früheren Kopie eines Objekts steht, wird nicht gelesen. Korrigieren Sie das JSON in der angezeigten Zeile und Spalte.
• Dieser Browser kann 10 nicht von 10.0 unterscheiden. Er meldet nicht, wie eine Zahl geschrieben ist, daher dekodiert ein Feld, das seinen Typ "int64" von einem Wert mit Dezimalpunkt oder Exponent bekam, Ihr JSON nicht. Prüfen Sie die Felder, deren Werte so geschrieben sind, oder konvertieren Sie das JSON in einem Browser, der es meldet.

Zu Datumsangaben, Formaten oder festen Wertemengen gibt es keinen Hinweis, denn die Seite errät so etwas nie aus einem String: "created_at" im Beispiel bleibt ein "string", wie es auch aussieht.