JSON to Go Struct: il generatore consegna lo scheletro, quattro cose richiedono le tue mani
In sintesi: Incolla una risposta API di esempio nel convertitore e in dieci secondi hai le struct Go con i tag — ma i numeri diventano float64, i campi opzionali non diventano mai puntatori da soli, omitempty non elimina le struct vuote e la maggior parte delle date resta stringa. Tabella completa di mappatura, l'equilibrio tra puntatore e omitzero e una checklist in quattro passi per rifinire il codice generato.

Conclusione prima: le struct che un convertitore produce in dieci secondi compilano, ma non sono pronte per la produzione. Il generatore descrive solo il singolo campione che hai incollato — i numeri diventano float64, i campi opzionali non diventano mai puntatori da soli, omitempty non elimina le struct vuote, e la maggior parte delle stringhe di data resta stringa. Queste quattro lacune restano compito tuo dopo l'incollaggio.
Trasformare una risposta API in struct Go è lavoro puramente meccanico, e il costo del lavoro meccanico si nasconde nel silenzio: un nome di campo scritto male non genera errore di compilazione, solo un campo che resta a zero per sempre; un'interruttore sbagliato nella gestione del null e un
"note": nullcompare in produzione dove nessuno se l'aspettava. La generazione delle struct risolve l'allineamento di nomi e tipi, ma due cose non si allineano mai da sole: le varianti fuori dal tuo campione e il fossato tra il sistema di tipi di Go e quello di JSON.
Cosa legge davvero il generatore: una tabella di mappatura
Ogni convertitore JSON → Go gira sulla stessa tabella. Passa una risposta tipica di ordine dalla pagina /convert/go di questo sito — incolla il campione, attiva i tag json — e ottieni questa forma:
| Valore JSON | Tipo Go generato | Note |
|---|---|---|
| string | string |
Le stringhe di data di solito restano stringhe, vedi time.Time sotto |
| intero | float64 |
encoding/json analizza i numeri internamente come double |
| decimale | float64 |
Sostituisci i campi monetari con una libreria decimal o int64 in unità minori |
| true / false | bool |
Nessuna trappola |
| null | any |
Un solo campione null non prova nulla, fallback conservativo |
| oggetto | struct nominata | Gli oggetti annidati diventano una struct propria |
oggetto vuoto {} |
map[string]any |
Nessun campo osservabile, il generatore non indovina |
| array | []TipoElemento |
Tipo dell'elemento dedotto dal primo campione |
| tipi misti | any |
Go non ha le unioni, i campi con più tipi ripiegano su any |
// Campione di input
// {"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"`
}
Tre osservazioni. L'oggetto annidato items è diventato la sua struct Item referenziata da uno slice. coupon è apparso solo come null: il generatore non può provare cosa sarà dopo e ripiega su any. Il numero qty atterra come int o float64 a seconda dello strumento — le strategie differiscono, ma tutte poggiano sulla stessa supposizione: il campione è tutta la verità.
Tag json: nomi originali, opzioni e tre errori facili
I tag portano la più alta densità di informazione nell'output del generatore e sono anche la parte più facile da sbagliare quando ritocchi. Le regole vengono dritte dalla documentazione di encoding/json:
Field int `json:"myName"` // appare sotto la chiave myName
Field int `json:"myName,omitempty"` // campo intero omesso quando vuoto
Field int `json:",omitempty"` // nome di campo predefinito, solo l'opzione
Field int `json:"-"` // sempre ignorato, né codificato né decodificato
Field int64 `json:"id,string"` // numero codificato dentro una stringa
Tre disattenzioni vale la pena memorizzare. Primo, la virgola iniziale in json:",omitempty" — quando vuoi solo saltare i valori vuoti senza rinominare la chiave, la virgola è obbligatoria; senza di essa il campo viene trattato come una chiave letteralmente chiamata ,omitempty. Secondo, mantieni la chiave JSON originale nel tag (user_id, html_url) mentre il campo Go usa la convenzione idiomatica (UserID, HTMLURL): senza tag, la corrispondenza usa il nome del campo letteralmente, quindi una chiave userId nella risposta non mappa mai, in silenzio. Terzo, oltre a json:"-" esiste json:"-," — quest'ultima significa che la chiave si chiama davvero -.
Puntatori: nil è l'unico modo per distinguere "assente" da "zero"
Il sistema dei valori zero di Go impedisce a int e string di esprimere "campo non presente" — 0 e "" possono essere dati reali o semplicemente non analizzati. La stessa chiave JSON ha tre stati: presente con valore, presente come null e assente. I tipi per valore coprono solo il primo.
type Config struct {
Note string `json:"note,omitempty"` // omesso solo quando esattamente ""
Alias *string `json:"alias,omitempty"` // omesso quando nil
Details *Meta `json:"details,omitempty"`
}
Il valore zero di un campo puntatore è nil. json.Unmarshal lo lascia nil quando la chiave manca o è null, e omitempty lo salta solo in quel caso. È il motivo per cui la maggior parte dei convertitori offre un'interruttore "usa puntatori per gli oggetti annidati": attivato, le struct annidate diventano *Item, e in una richiesta PATCH "campo non inviato" e "null inviato per cancellare" finalmente si separano. Il prezzo sono controlli nil ovunque — p.Address.Street va in panico quando Address è nil, uno dei crash di runtime più comuni nel codice JSON in Go.
La struct vuota che omitempty non riesce a eliminare, e il vuoto che omitzero riempie
La definizione ufficiale di omitempty giudica i valori: false, 0, puntatori nil, interfacce nil e array, slice, map o stringhe di lunghezza zero. Nota cosa non è nella lista: le struct vuote.
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 non ha fatto nulla
Un campo struct non viene mai omesso da omitempty — vive in memoria come un contenitore di dimensione fissa, e un contenitore esistente non è "vuoto". La correzione è trasformare il campo in *Meta; solo un puntatore nil viene scartato. Da Go 1.24 esiste un secondo interruttore, omitzero: giudicato dal valore zero di Go, chiamando IsZero() bool quando il tipo lo definisce — l'unico modo per omettere un time.Time zero. Con encoding/json/v2 (sperimentale in Go 1.25) la semantica si sposta di nuovo: l'omitempty di v2 giudica il risultato JSON codificato (solo null, "", {}, [] contano come vuoto), quindi count: 0 resta nell'output; migrando codice vecchio, l'omitempty sui campi bool e numerici deve diventare omitzero per conservare il significato originale.
Ogni numero diventa float64: la trappola dei grandi interi
Senza tipo esplicito, il decoder di encoding/json tratta i numeri come float64, e float64 ha solo 53 bit di mantissa. Il classico caso di JavaScript — 9007199254740993 che diventa 9007199254740992 — esiste anche in Go, purché il campo di destinazione sia float64 o any.
var v map[string]any
_ = json.Unmarshal([]byte(`{"id":9007199254740993}`), &v)
// v["id"] è float64(9007199254740992), precisione già perduta
Tre vie d'uscita. Dichiara il campo della struct come int64 e il decoder analizza esattamente lì. Quando devi passare per any, chiama decoder.UseNumber() perché i numeri atterrino come stringhe json.Number che converti deliberatamente. Non usare mai il virgola mobile per il denaro — conserva le unità minori in int64 o usa una libreria decimal. Ogni volta che un'API restituisce ID snowflake o numeri d'ordine a 64 bit, questa sezione è verifica obbligatoria.
time.Time accetta solo RFC 3339
Davanti a "2024-01-15T10:30:00Z" un generatore mappa time.Time; davanti a "2024-01-15 10:30:00" lascia una stringa. Non è pigrizia — è un vincolo duro di encoding/json: time.Time implementa UnmarshalJSON e analizza rigorosamente nel layout RFC 3339 2006-01-02T15:04:05Z07:00. T mancante, fuso mancante o uno Z seguito da un offset falliscono tutti:
parsing time "\"2022-07-27T14:16:00Z04:00\"" as
"\"2006-01-02T15:04:05Z07:00\"": cannot parse "04:00\"" as "\""
Quando il formato upstream non può cambiare, la correzione standard è un tipo personalizzato che avvolge time.Time e il cui UnmarshalJSON prova più layout:
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
}
La checklist in quattro passi dopo la generazione
Quattro passi separano l'output del generatore dal codice di produzione, e farli una volta costa meno che fare debug dopo:
- Sostituisci ogni fallback any: cerca
any, rivedi tre-cinque campioni reali per campo in fallback e poi atterra in un tipo concreto o puntatore; - Riverifica le larghezze numeriche: sposta ID, importi e contatori da float64 a int64 / int32 / decimal; nel dubbio sulla larghezza, scrivi int64;
- Marca l'opzionalità: puntatori o omitempty/omitzero per i campi di oggetti negli array, corpi PATCH e campi nullable di API di terze parti — decidi la semantica di nil una volta, qui;
- Compila e testa l'andata e ritorno: esegui
go vet, poi aggiungi un test di andata e ritorno Marshal→Unmarshal per bloccare il formato sul filo — coglie la deriva comportamentale dei futuri aggiornamenti di encoding/json.
Dal campione al contratto: il confine del convertitore
Un convertitore risponde a "come appare questo campione", non a "come apparirà sempre questa interfaccia". Gli strumenti concorrenti lo dicono francamente nelle loro stesse documentazioni: un campione non può provare le varianti di produzione — opzionalità, formati di data e valori di enumerazione richiedono revisione umana. Costruisci quindi l'abitudine: prima di incollare, raccogli le risposte più propense a esporre differenze (lista vuota, tutti i campi, una con null); dopo la generazione, tratta l'output come bozza, non come consegna. Se l'interfaccia ha un documento di contratto, rendi esplicite le restrizioni con JSON Schema e allinea il codice generato a esso — batte l'inferenza dai campioni di un ordine di grandezza. Per la vista trasversale dello stesso problema, il lato Java è coperto nel nostro test sul terreno del generatore Java, il contratto frontend nelle interfacce TypeScript; il fossato di precisione numerica riappare in ogni lingua con un'altra maschera, dettagliato nella trappola dei grandi numeri del JSON.
Quali campioni richiedono ancora revisione manuale dopo la generazione?
Almeno quattro: i fallback any, le larghezze numeriche (float64 → int64), trasformare in puntatori i campi opzionali e se i campi di data debbano essere string o time.Time. Tutti e quattro sono varianti di produzione invisibili nel campione; il generatore non indovina, l'umano deve completare.
Perché il mio campo appare ancora nel JSON dopo aver aggiunto omitempty?
omitempty salta solo i valori zero: false, 0, "", nil, slice vuote. Una struct vuota {} non è un valore zero, quindi sopravvive — trasforma il campo in puntatore. Un time.Time zero richiede omitzero, non omitempty.
Perché il mio grande ID intero è cambiato dopo la deserializzazione?
Senza tipo esplicito, encoding/json analizza i numeri come float64, che porta 53 bit di mantissa; gli interi oltre 2^53 perdono precisione. Tipizza il campo come int64, o chiama UseNumber() per conservare i numeri come json.Number.
Quando un campo di oggetto annidato deve essere un puntatore?
Due casi: il campo può essere assente o null (nil separa "non inviato" da "valore zero"), e una richiesta PATCH deve distinguere "non inviato" da "null inviato per cancellare". Nelle struct di risposta comuni con campi non nullable, i tipi per valore sono più sicuri — paga il costo dei controlli nil solo quando davvero ti serve la distinzione.