JSON zu Go Struct: Der Generator liefert das Skelett, diese vier Punkte brauchen Handarbeit
Fazit: Eine API-Antwort als Muster in den Konverter einfügen und in zehn Sekunden landen getaggte Go-Structs auf dem Schirm — doch Zahlen fallen als float64 durch, optionale Felder werden nie automatisch zu Pointern, omitempty bekommt leere Structs nicht weg, und die meisten Datumsstrings bleiben Strings. Komplette Mapping-Tabelle, der Kompromiss zwischen Pointer und omitzero sowie eine Vier-Schritte-Checkliste zum Nachziehen.

Das Fazit vorweg: Die Structs, die ein Konverter in zehn Sekunden ausspuckt, kompilieren — produktionsreif sind sie nicht. Der Generator beschreibt nur das eine Muster, das du eingefügt hast: Zahlen landen als float64, optionale Felder werden nie von selbst zu Pointern, omitempty bekommt leere Structs nicht weg, und die meisten Datumsstrings bleiben Strings. Diese vier Lücken bleiben nach dem Einfügen deine Arbeit.
Eine API-Antwort in Go-Structs zu übersetzen ist reine Fleißarbeit, und der Preis von Fleißarbeit versteckt sich im Stillen: Ein falsch geschriebener Feldname erzeugt keinen Compilerfehler, nur ein Feld, das für immer auf null bleibt; ein falsch gestellter Schalter bei der Null-Behandlung, und in der Produktion taucht ein
"note": nullauf, den niemand erwartet hat. Die Struct-Generierung löst das Alignment von Namen und Typen — aber zwei Dinge richten sich nie von selbst aus: die Varianten außerhalb deines Musters und der Graben zwischen Go-Typsystem und JSON-Typsystem.
Was der Generator wirklich liest: eine Mapping-Tabelle
Jeder JSON → Go-Konverter fährt auf derselben Tabelle. Leite eine typische Bestell-Antwort durch die Seite /convert/go dieser Website — Muster einfügen, json-Tags aktivieren — und heraus kommt diese Form:
| JSON-Wert | Generierter Go-Typ | Hinweise |
|---|---|---|
| Zeichenkette | string |
Datumsstrings bleiben meist Strings, siehe time.Time unten |
| Ganzzahl | float64 |
encoding/json parst Zahlen intern als double |
| Dezimalzahl | float64 |
Beträge auf eine Decimal-Bibliothek oder int64-Kleinheiten umstellen |
| true / false | bool |
keine Stolperfalle |
| null | any |
Ein einzelnes null-Muster beweist nichts, konservativer Fallback |
| Objekt | benannter Struct | Verschachtelte Objekte werden zum eigenen Struct |
leeres Objekt {} |
map[string]any |
Keine Felder beobachtbar, der Generator rät nicht |
| Array | []ElementTyp |
Elementtyp aus dem ersten Muster abgeleitet |
| gemischte Typen | any |
Go hat keine Union-Typen, Mehrfachtyp-Felder fallen auf any zurück |
// Eingabemuster
// {"id":"A-1029","items":[{"sku":"J-01","qty":2}],"coupon":null}
type Root struct {
ID string `json:"id"`
Items []Item `json:"items"`
Coupon any `json:"coupon"`
}
type Item struct {
Sku string `json:"sku"`
Qty int `json:"qty"`
}
Drei Beobachtungen. Das verschachtelte Objekt items wurde zum eigenen Struct Item, referenziert über einen Slice. coupon erschien nur als null — der Generator kann nicht beweisen, was es später sein wird, und fällt auf any zurück. Die Zahl qty landet je nach Werkzeug als int oder float64 — die Strategien unterscheiden sich, aber alle ruhen auf derselben Annahme: Das Muster ist die ganze Wahrheit.
json-Tags: Originalnamen, Optionen und drei leicht übersehene Schreibweisen
Tags tragen die größte Informationsdichte in der Generator-Ausgabe und sind zugleich der Teil, der beim Nachbauen am leichtesten schiefgeht. Die Regeln stammen direkt aus der encoding/json-Dokumentation:
Field int `json:"myName"` // erscheint unter Schlüssel myName
Field int `json:"myName,omitempty"` // gesamtes Feld weggelassen, wenn leer
Field int `json:",omitempty"` // Standard-Feldname bleibt, nur die Option
Field int `json:"-"` // immer ignoriert, weder Kodierung noch Dekodierung
Field int64 `json:"id,string"` // Zahl in einen String verpackt
Drei Übersehn-Würdigkeiten. Erstens das führende Komma in json:",omitempty" — wenn du nur leere Werte überspringen willst, ohne den Schlüssel umzubenennen, ist das Komma Pflicht; ohne es gilt das Feld als Schlüssel, der wörtlich ,omitempty heißt. Zweitens, den ursprünglichen JSON-Schlüssel im Tag behalten (user_id, html_url), während das Go-Feld idiomatische Schreibweise trägt (UserID, HTMLURL): Ohne Tag wird wörtlich über den Feldnamen gematcht, ein Antwort-Schlüssel userId mappet also still nie. Drittens gibt es neben json:"-" auch json:"-," — letzteres bedeutet, der Schlüssel heißt wirklich -.
Pointer: Nur nil kann „abwesend" von „null" unterscheiden
Go's Zero-Value-System macht es int und string unmöglich, „Feld nicht vorhanden" auszudrücken — 0 und "" können echte Daten sein oder einfach nicht geparst. Derselbe JSON-Schlüssel hat drei Zustände: vorhanden mit Wert, vorhanden als null, nicht vorhanden. Werttypen decken nur den ersten ab.
type Config struct {
Note string `json:"note,omitempty"` // weggelassen nur bei exakt ""
Alias *string `json:"alias,omitempty"` // weggelassen bei nil
Details *Meta `json:"details,omitempty"`
}
Der Nullwert eines Pointer-Felds ist nil. json.Unmarshal lässt es nil, wenn der Schlüssel fehlt oder null ist, und omitempty überspringt es nur dann. Deshalb bieten die meisten Konverter einen Schalter „Pointer für verschachtelte Objekte": aktiviert werden verschachtelte Structs zu *Item, und in einem PATCH-Request trennen sich „Feld nicht gesendet" und „null gesendet zum Löschen" endlich. Der Preis sind nil-Prüfungen überall — p.Address.Street panikt, wenn Address nil ist, einer der häufigsten Laufzeit-Crashes in Go-JSON-Code.
Der leere Struct, den omitempty nicht loswird, und das Loch, das omitzero stopft
Die offizielle omitempty-Definition urteilt über Werte: false, 0, nil-Pointer, nil-Interfaces sowie Arrays, Slices, Maps oder Strings der Länge null. Beachte, was nicht auf der Liste steht: leere Structs.
type Order struct {
Meta Meta `json:"meta,omitempty"`
}
type Meta struct {
Version string
Build int
}
// Meta{Version: "1.0"} → "meta":{"version":"1.0","build":0}
// Meta{} → "meta":{} ← omitempty tat nichts
Ein Struct-Feld wird von omitempty nie weggelassen — es lebt im Speicher als Container fester Größe, und ein existierender Container ist nicht „leer". Die Korrektur: das Feld zu *Meta machen; nur ein nil-Pointer wird fallen gelassen. Seit Go 1.24 gibt es einen zweiten Schalter, omitzero: bewertet nach dem Go-Nullwert, ruft IsZero() bool auf, wenn der Typ ihn definiert — der einzige Weg, ein null time.Time wegzulassen. Mit encoding/json/v2 (experimentell ab Go 1.25) verschiebt sich die Semantik erneut: omitempty von v2 urteilt über das kodierte JSON-Ergebnis (nur null, "", {}, [] gelten als leer), also bleibt count: 0 in der Ausgabe; beim Migrieren alten Codes muss omitempty auf bool- und Zahlenfeldern zu omitzero werden, um die alte Bedeutung zu halten.
Jede Zahl wird float64: die Falle der großen Ganzzahlen
Ohne expliziten Typ behandelt der encoding/json-Decoder Zahlen als float64, und float64 hat nur 53 signifikante Mantissenbits. Der klassische JavaScript-Fall — 9007199254740993 wird zu 9007199254740992 — existiert auch in Go, solange das Zielfeld float64 oder any ist.
var v map[string]any
_ = json.Unmarshal([]byte(`{"id":9007199254740993}`), &v)
// v["id"] ist float64(9007199254740992), Präzision schon verloren
Drei Auswege. Deklariere das Struct-Feld als int64, dann parst der Decoder exakt hinein. Wenn es durch any gehen muss, rufe decoder.UseNumber() auf, damit Zahlen als json.Number-Strings landen, die du bewusst konvertierst. Nimm nie Fließkommazahlen für Geld — speichere Kleinheiten in int64 oder benutze eine Decimal-Bibliothek. Immer wenn eine API Snowflake-IDs oder 64-Bit-Bestellnummern zurückgibt, ist dieser Abschnitt eine Pflichtprüfung.
time.Time akzeptiert nur RFC 3339
Vor "2024-01-15T10:30:00Z" mappt ein Generator time.Time; vor "2024-01-15 10:30:00" lässt er einen String. Das ist keine Bequemlichkeit — es ist eine harte Einschränkung von encoding/json: time.Time implementiert UnmarshalJSON und parst strikt im RFC-3339-Layout 2006-01-02T15:04:05Z07:00. Fehlendes T, fehlende Zeitzone oder ein Z gefolgt von einem Offset schlagen alle fehl:
parsing time "\"2022-07-27T14:16:00Z04:00\"" as
"\"2006-01-02T15:04:05Z07:00\"": cannot parse "04:00\"" as "\""
Wenn sich das vorgelagerte Format nicht ändern lässt, ist die Standardkorrektur ein eigener Typ, der time.Time umhüllt und dessen UnmarshalJSON mehrere Layouts versucht:
type CustomDate struct{ time.Time }
func (c *CustomDate) UnmarshalJSON(b []byte) error {
s := strings.Trim(string(b), `"`)
t, err := time.Parse("2006-01-02 15:04:05", s)
if err != nil {
t, err = time.Parse(time.RFC3339, s)
if err != nil {
return fmt.Errorf("invalid date format: %w", err)
}
}
c.Time = t
return nil
}
Die Vier-Schritte-Checkliste nach der Generierung
Vier Schritte trennen die Generator-Ausgabe vom Produktionscode, und sie einmal zu durchlaufen ist billiger als späteres Debuggen:
- Jeden any-Fallback ersetzen: nach
anysuchen, pro Fallback-Feld drei bis fünf echte Muster prüfen, dann auf einen konkreten Typ oder Pointer festlegen; - Zahlenbreiten nachprüfen: IDs, Beträge und Zähler von float64 auf int64 / int32 / decimal umstellen; bei unsicherer Breite int64 schreiben;
- Optionalität markieren: Pointer oder omitempty/omitzero für Array-Objektfelder, PATCH-Bodies und nullable Felder von Drittanbieter-APIs — die nil-Semantik einmal, hier festzurren;
- Kompilieren und Rundtrip testen:
go vetdurchlaufen lassen, dann einen Marshal→Unmarshal-Rundtriptest hinzufügen, der das Wire-Format festnagelt — das fängt das Verhaltensdriften künftiger encoding/json-Upgrades ab.
Vom Muster zum Vertrag: die Grenze des Konverters
Ein Konverter beantwortet „wie sieht dieses Muster aus", nicht „wie wird diese Schnittstelle immer aussehen". Konkurrierende Werkzeuge sagen es in ihren eigenen Dokumenten offen: Ein Muster kann Produktionsvarianten nicht beweisen — Optionalität, Zeitformate und Enum-Werte brauchen alle menschliche Nachprüfung. Gewöhne dir also an: vor dem Einfügen die Antworten sammeln, die Unterschiede am ehesten aufdecken (leere Liste, alle Felder, eine mit nulls); nach der Generierung die Ausgabe als Entwurf behandeln, nicht als Lieferung. Hat die Schnittstelle ein Vertragsdokument, mache die Einschränkungen mit JSON Schema explizit und richte den generierten Code daran aus — das schlägt Rückschlüsse aus Mustern um Größenordnungen. Für den sprachübergreifenden Blick auf dasselbe Problem ist die Java-Seite in unserem Java-Generator-Praxistest abgedeckt, der Frontend-Vertrag in den TypeScript-Interfaces; die Zahlenpräzisions-Lücke erscheint in jeder Sprache in anderem Kostüm, ausführlich in der JSON-Großzahl-Falle.
Welche Felder brauchen nach der Generierung noch manuelle Prüfung?
Mindestens vier: any-Fallbacks, Zahlenbreiten (float64 → int64), die Pointer-Machung optionaler Felder und ob Datumsfelder string oder time.Time sein sollen. Alle vier sind Produktionsvarianten, die im Muster unsichtbar sind; der Generator rät nicht, der Mensch muss ergänzen.
Warum bleibt mein Feld im JSON, obwohl omitempty gesetzt ist?
omitempty überspringt nur Nullwerte: false, 0, "", nil, leere Slices. Ein leerer Struct {} ist kein Nullwert und überlebt deshalb — mach das Feld zum Pointertyp. Ein null time.Time braucht omitzero, nicht omitempty.
Warum hat sich meine große Ganzzahl-ID nach der Deserialisierung verändert?
Ohne expliziten Typ parst encoding/json Zahlen als float64 mit nur 53 Mantissenbits; Ganzzahlen jenseits von 2^53 verlieren Präzision. Typisiere das Feld int64 oder rufe UseNumber() auf, um Zahlen als json.Number zu halten.
Wann sollte ein verschachteltes Objektfeld ein Pointer sein?
Zwei Fälle: Das Feld kann fehlen oder null sein (nil trennt „nicht gesendet" von „Nullwert"), und ein PATCH-Request muss „nicht übermittelt" von „null übermittelt zum Löschen" unterscheiden. Bei gewöhnlichen Antwort-Structs mit nicht-nullable Feldern sind Werttypen sicherer — die nil-Prüfkosten nur zahlen, wenn du die Unterscheidung wirklich brauchst.