Come Mappare JSON per Andare Strutture Con Tag di Campo

La maggior parte del mio lavoro quotidiano è TypeScript e PHP, ma una buona parte degli strumenti dietro Toolz.dev e i piccoli servizi che scrivo intorno ad esso sono Go, e ogni volta che cablo un nuovo client API colpisco lo stesso muro Hai una risposta JSON di fronte a te, e hai bisogno della struttura Go che json.Unmarshal lo decodificherà in Scrivere quella struttura a mano è noioso in un modo molto specifico: non è difficile, è solo giocherellone, e i bit violini sono esattamente dove si commettono errori Così ho costruito un convertitore nel sito, e questa è la guida ad esso.

tl; dr: Il Toolz Convertitore di struttura da JSON a Go analizza un documento JSON ed emette le dichiarazioni di tipo Go che lo descrivono Gli oggetti diventano strutture in linea, gli array di oggetti vengono uniti in un'unica struttura e ogni campo ottiene un json:"key" tag così encoding/json mappa correttamente i dati I nomi dei campi seguono le convenzioni Go, quindi id diventa ID e user_url diventa UserURL. Passa i numeri interi a int64, aggiungere omitempty, e rinominare il tipo di root Funziona interamente lato client: nessun upload, nessuna iscrizione, funziona offline.

Che cosa è un convertitore struttura JSON to Go?

Un convertitore di struttura da JSON a Go trasforma un documento JSON nelle dichiarazioni di tipo Go che lo descrivono, in modo da poter decodificare gli stessi dati con la libreria standard's encoding/json pacchetto invece di digitare la struttura a mano Ogni oggetto JSON diventa una struttura Go, ogni campo porta un json:"key" tag che lo mappa nuovamente al nome originale, e i tipi scalari sono dedotti dai valori Una stringa JSON diventa string, un numero intero diventa int, un numero con punto decimale diventa float64, true e false diventare bool, e null diventa interface{}.

Il motivo per cui questo è utile è che un oggetto JSON e una struttura Go descrivono la stessa forma, un insieme di campi con nome con valori tipizzati, ma Go è tipizzato staticamente e JSON no, quindi la struttura deve precisare ogni tipo in anticipo Derivare quei tipi da una risposta di esempio è meccanica pura e le meccaniche eseguite a mano su un carico utile annidato sono dove vivono i bug Il convertitore esegue la derivazione in modo deterministico e ti restituisce un blocco di tipo che compila.

Vale la pena essere chiari sulle due metà del problema, perché sono ciò che un convertitore ingenuo sbaglia Il primo è il naming: Go codifica solo i campi esportati, quelli con la prima lettera maiuscola, e le regole di lanugine della comunità vogliono inizialismi comuni completamente maiuscole Il secondo è il tag: il json:"..." tag deve tenere l'esatta chiave originale o json.Unmarshal salta silenziosamente il campo in fase di esecuzione senza errori Sbaglia entrambi e la tua decodifica restituisce una struttura piena di valori zero mentre tutto sembra a posto Lo strumento gestisce entrambi per te.

Perché non scrivere la struttura a mano?

Questa è la domanda onesta, perché per un oggetto piatto a tre campi, scrivere a mano la struttura è più veloce che aprire uno strumento Il convertitore guadagna il suo posto sulle risposte che non sono piatte: un carico utile con oggetti nidificati, matrici di oggetti e venti campi in cui metà dei tasti sono snake_case e alcuni sono inizialismi come id, url, e api_key.

In una risposta del genere, la versione scritta a mano ha tre modalità di errore che ho colpito ripetutamente Ti dimentichi di esportare un campo, quindi rimane minuscolo e encoding/json si rifiuta di popolarlo Capitalizzi il campo ma dimentichi il tag, quindi UserName cerca una chiave JSON chiamata UserName e non trova mai user_name. Oppure sbagli il nesting, dichiarando un campo come struttura semplice quando il JSON lo avvolge effettivamente in un array Nessuno di questi è un errore di compilazione Sono sorprese di runtime che si presentano come dati mancanti e perdi più tempo nel debug di uno di essi di quanto avresti speso generando l'intera struttura.

Il convertitore li rimuove tutti e tre Esporta ogni campo, scrive il tag dalla chiave reale e legge la forma JSON effettiva per decidere tra una struttura e una fetta di strutture Ciò che incolli è ciò per cui ottieni i tipi.

Ecco la decisione in una tabella.

situazione	maneggiare	perché
Un oggetto piatto con due o tre campi	Scrivilo a mano	Più veloce di aprire qualsiasi cosa
Una risposta API annidata con molti campi	Convertitore di struttura da JSON a Go	Naming e tag sono i luoghi in cui si rompono le strutture scritte a mano
Hai bisogno della stessa forma di TypeScript	Convertitore da JSON a TypeScript	Stessa inferenza, lingua di destinazione diversa
Vuoi uno schema di convalida, non tipi	Generatore di schemi JSON	Regole Draft-07 anziché tipi Go

Perché i nomi dei campi Go sono diversi dai miei tasti JSON?

Questo fa inciampare le persone la prima volta, quindi vale la pena spiegare piuttosto che nascondersi Go' s encoding/json pacchettizza solo marescialli e non marescialli esportato struct campi, che significa campi il cui nome inizia con una lettera maiuscola Una chiave JSON come user_name impossibile mappare su un non esportato user_name campo, quindi il campo deve essere rinominato in qualcosa esportato. Lo strumento capitalizza ogni parola, girando user_name dentro UserName.

Oltre a ciò, la comunità Go's lint tooling, le regole che hanno iniziato con golint e continuare a vivere con strumenti come staticcheck, vuole inizialismi comuni scritti in maiuscolo Così id diventa ID, no Id; user_url diventa UserURL, no UserUrl; E html_body diventa HTMLBody. Il convertitore conosce l'insieme standard di inizialismi, ID, URL, API, HTTP, JSON, UUID, e il resto, e li applica, quindi l'output passa i linter che probabilmente viene eseguito dal tuo CI.

Il pezzo che rende sicura la ridenominazione è il tag Ogni campo ottiene un json:"user_name" tag che tiene esattamente la chiave originale, quindi in fase di esecuzione json.Unmarshal legge il tasto JSON user_name e lo scrive nel UserName campo indipendentemente dalla ridenominazione L'articolo di Go blog' s su JSON e Go documenta questo meccanismo di tag, ed è il motivo per cui un campo rinominato decodifica ancora correttamente Senza il tag, la struttura rinominata non riuscirebbe silenziosamente a popolarsi.

Come vengono gestiti numeri e array di oggetti?

Due parti dell'inferenza meritano uno sguardo più attento perché sono dove i convertitori differiscono in qualità.

Prima i numeri JSON ha un singolo tipo di numero, ma Go no, quindi lo strumento deve scegliere Un valore senza parte frazionaria diventa int, o int64 se attivi quell'opzione e diventa un valore con punto decimale float64. Il caso interessante è un array che li mescola, come [9.5, 8, 7.2]. Se lo strumento lo ha digitato come []int non riuscirebbe a decodificare il 9.5, quindi allarga l'intera fetta a []float64. Qualsiasi array in cui un elemento forza un tipo più ampio ottiene il tipo più ampio per tutti gli elementi, che è l'unica scelta che decodifica ogni valore.

Gli array di oggetti sono l'altro posto in cui i payload reali diventano interessanti Un'API non ti dà quasi mai un array in cui ogni oggetto ha un insieme identico di chiavi; un elemento ha un campo che gli altri omettono, o un campo nullable è presente qui e lì assente Se lo strumento generasse una struttura solo dal primo elemento, lascerebbe cadere le chiavi che appaiono più tardi Invece unisce ogni oggetto nell'array in una struttura che include ogni chiave che ha qualsiasi elemento E se due elementi danno la stessa chiave tipi incompatibili, diciamo un numero in uno e una stringa in un altro, quel campo ricade su interface{} piuttosto che lo strumento indovinare sbagliato o fallire a titolo definitivo Il risultato è un singolo tipo di struttura che può decodificare l'intero array.

Come si usa il convertitore?

Il flusso è di quattro passi Incolla un oggetto o un array JSON nella casella di input; se vuoi vedere prima la forma dell'output, carica il campione Dai un nome al tipo root, qualcosa come User oppure ApiResponse, e lo strumento lo pulisce in un identificatore Go esportato valido in modo che venga compilato come scritto Scegli int oppure int64 per numeri interi, e accendi omitempty se si desidera che i campi a valore zero vengano esclusi quando la struttura viene successivamente codificata nuovamente in JSON. Quindi fare clic su Converti e copiare la struttura nel proprio .go file.

Se il JSON non è valido, lo strumento segnala il parser's proprio messaggio di errore piuttosto che fallire silenziosamente, quindi una virgola vagante finale o una chiave non quotata è veloce da trovare E perché tutto viene eseguito nel browser, è possibile incollare una risposta API reale, tra cui uno con campi privati, senza che lasci la macchina Quel modello lato client è lo stesso dietro il resto del sito, descritto nel strumenti online per la privacy dei dati guida.

Come si adatta questo con gli altri strumenti JSON?

Il convertitore struct da JSON a Go è un membro di una famiglia di trasformatori JSON sul sito e condividono lo stesso nucleo di analisi. Quando si desidera riordinare prima il JSON, il Formattatore JSON rientrandolo e convalidandolo, cosa che vale la pena fare prima di convertire in modo da poter leggere la forma che stai per digitare Quando la lingua di destinazione è TypeScript anziché Go, il Convertitore da JSON a TypeScript esegue la stessa inferenza ed emette interfacce Quando è necessario un contratto di convalida anziché tipi di lingua, il Generatore di schemi JSON produce uno schema Draft-07 e quando la destinazione è una base di codice PHP, il Convertitore di array da JSON a PHP scrive un array letterale.

Il thread che li collega tutti è che trattano JSON come una fonte di struttura e traducono quella struttura in qualunque cosa parli il tuo codice Se lavori in diverse lingue, il Toolkit per sviluppatori web la carrellata mostra come questi pezzi si incastrano insieme e il Guida agli strumenti di codifica copre l'insieme più ampio di formattatori e convertitori.

Un esempio pratico dalla costruzione di un servizio Go

Lasciate che lo renda concreto Tempo fa stavo scrivendo un piccolo servizio Go che estraeva dati da un'API di terze parti e ne riesponeva una versione ridotta La risposta vendor's era un oggetto annidato: un record di primo livello con un owner sottooggetto, a tags array di stringhe, e un scores array che, fastidiosamente, mescolava interi e decimali a seconda del campo Digitare a mano la struttura significava ottenere il owner nidificando bene, taggando ogni snake_case chiave e decidere cosa fare riguardo a quell'array misto.

Ho incollato la risposta del campione nel convertitore, ho chiamato il tipo di root in onore della risorsa e ho recuperato una struttura con Owner come struttura annidata in linea, Tags tanto []string, e Scores correttamente allargato a []float64. la id field è uscito come ID con un json:"id" tag, quindi ha passato la linter e decodificato la chiave reale L'ho copiata direttamente nel pacchetto client e sono passata alla logica, che è dove volevo effettivamente trascorrere il mio tempo La struttura non era la parte interessante del lavoro, e generarla significava che smetteva di essere qualsiasi parte del lavoro.

Il motivo per cui raggiungo il convertitore piuttosto che una struttura scritta a mano in questi spot non è la pigrizia, è che le parti meccaniche, l'esportazione, il tagging e il nesting, sono proprio le parti che sbaglio quando penso invece alla logica. Scaricarle su uno strumento deterministico significa che la struttura è corretta nella prima compilazione e una decodifica corretta nella prima esecuzione, che su un payload annidato salva una sessione di debug autentica. Quando ho bisogno che anche la struttura sopravviva alla ricodifica, accendo omitempty quindi i valori zero rimangono fuori dall'output e i tag arrivano come json:"key,omitempty" pronti per quel viaggio di andata e ritorno.

Quali sono i limiti che vale la pena conoscere?

Qualche spigolo onesto Il primo è null. UN JSON null non trasporta informazioni sul tipo da solo, quindi un campo che lo è null nel tuo campione è digitato come interface{}. Non c'è nulla che lo strumento possa dedurre lì; se conosci il tipo reale, cambialo nel tuo editor dopo aver incollato, o dai al convertitore un campione in cui quel campo ha un valore reale in modo che il tipo possa essere derivato Questa è una proprietà dei dati, non una mancanza dello strumento.

Il secondo è la precisione numerica, ed è una proprietà del parsing JSON in generale piuttosto che di questo convertitore in particolare Lo strumento analizza il tuo JSON con il browser's JSON parser, che rappresenta i numeri come float a doppia precisione, quindi gli interi oltre circa 2 alla 53a potenza perdono esattezza in fase di analisi, prima che lo strumento li veda mai Il generato int64 campo è abbastanza ampio da tenere un ID grande, ma se l'ID arriva come un numero JSON nudo così grande, l'analisi lo ha già arrotondato Per ID interi veramente grandi, la mossa robusta è portarli come stringhe nel JSON, il che li mantiene esatti e ti consente di digitare il campo come string.

Il terzo è che l'inferenza è un punto di partenza, non un vangelo. Lo strumento ti fornisce i tipi supportati dal campione, ma solo tu sai che un campo che sembra essere un numero intero in questa risposta è in realtà un conteggio annullabile, o che a float64 dovrebbe essere un json.Number per evitare perdite di precisione Tratta l'output come una prima bozza corretta che raffini, non un contratto scolpito nella pietra Questo è vero per ogni generatore JSON-to-types, in qualsiasi lingua.

Infine, il convertitore produce strutture annidate in linea, che mantengono l'intera forma in un'unica dichiarazione che puoi incollare come blocco. Questo è lo stile più comune e più leggibile per una struttura generata, ed è ciò che gli strumenti nell'ecosistema Go hanno reso popolare. Se preferisci avere tipi con nome separati per sottooggetti riutilizzati in profondità, è un refactor che fai a mano una volta che la versione in linea è nel tuo editor, e di solito è un estratto di cinque secondi con il tuo IDE.

Domande frequenti

Che cosa è un convertitore struttura JSON to Go? Un convertitore di struttura da JSON a Go trasforma un documento JSON nelle dichiarazioni di tipo Go che lo descrivono Ogni oggetto diventa una struttura, ogni campo ottiene un tag json: & quot; key& quot; e i tipi di valore sono dedotti, in modo da poter deselezionare gli stessi dati con encoding/json senza scrivere la struttura a mano.

Come faccio a convertire JSON in una struttura Go? Incolla il tuo JSON nella casella di input, inserisci un nome per il tipo di root, scegli le opzioni del tuo numero intero e del tag, quindi fai clic su Converti Lo strumento stampa le definizioni Go struct con i tag json che puoi copiare direttamente in un file .go.

Perché i nomi dei campi Go sono diversi dai miei tasti JSON? Go codifica solo i campi esportati, quindi ogni nome di campo è in maiuscolo e le inizializzazioni comuni vengono rese maiuscole per corrispondere a golint. Il json:"..." il tag su ogni campo mantiene la chiave originale, quindi json.Unmarshal mappa ancora correttamente i dati nonostante il campo rinominato.

Come vengono mappati i numeri JSON sui tipi Go? Un numero intero diventa int, o int64 se si abilita tale opzione, e un numero con punto decimale diventa float64 Quando un array mescola numeri interi e decimali per la stessa posizione, il tipo viene ampliato a float64 in modo che ogni valore si adatti.

Come vengono gestiti gli array di oggetti? Un array di oggetti viene unito in un'unica struttura che include ogni chiave di qualsiasi elemento. Se due elementi forniscono gli stessi tipi incompatibili con la chiave, quel campo diventa interfaccia{} quindi la struttura copre ancora l'intero array.

Cosa succede ai valori nulli? Un null JSON non fornisce informazioni sul tipo da solo, quindi il campo viene digitato come interfaccia{}. Se conosci il tipo reale, cambialo nel tuo editor dopo l'incollaggio o fornisci un valore di esempio non nullo nel JSON in modo che il tipo possa essere dedotto.

Il mio JSON è stato caricato da qualche parte? No. La conversione avviene interamente nel browser utilizzando JavaScript sul dispositivo Il tuo JSON non viene mai caricato, registrato o archiviato e lo strumento continua a funzionare con la rete disconnessa una volta caricata la pagina.

Il convertitore struct da JSON a Go è gratuito? Sì. è completamente gratuito senza iscrizione, filigrana e senza limite di utilizzo Converti in Go structs tutti i documenti JSON necessari per progetti personali o commerciali.