JSON Toolkit

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.

Intermedio~6 min di letturaPubblicato il 2026-11-22Aggiornato il 2026-11-22
Conversione di un esempio JSON in codice struct Go con uno strumento online

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": null compare 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:

  1. Sostituisci ogni fallback any: cerca any, rivedi tre-cinque campioni reali per campo in fallback e poi atterra in un tipo concreto o puntatore;
  2. Riverifica le larghezze numeriche: sposta ID, importi e contatori da float64 a int64 / int32 / decimal; nel dubbio sulla larghezza, scrivi int64;
  3. 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;
  4. 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.