JSON vers Go Struct : le générateur donne le squelette, ces quatre points demandent votre main
L’essentiel : Collez un échantillon de réponse API dans le convertisseur et obtenez en dix secondes des structs Go balisés — mais les nombres deviennent float64, les champs optionnels ne deviennent jamais des pointeurs automatiquement, omitempty n'efface pas les structs vides et la plupart des dates restent des chaînes. Table de mapping complète, arbitrage pointeur/omitzero et liste de contrôle en quatre étapes.

En résumé : les structs produits par un convertisseur en dix secondes compilent, mais ne sont pas prêts pour la production. Le générateur ne décrit que l'unique échantillon collé — les nombres deviennent float64, les champs optionnels ne deviennent pas des pointeurs tout seuls, omitempty ne supprime pas les structs vides, et la plupart des chaînes de date restent des chaînes. Ces quatre écarts restent votre travail après le collage.
Transformer une réponse API en structs Go est un travail purement mécanique, et le coût du mécanique se cache dans le silence : un nom de champ mal orthographié ne produit aucune erreur de compilation, juste un champ qui reste à zéro pour toujours ; un mauvais réglage sur la gestion des null et
"note": nullapparaît en production là où personne ne l'attendait. La génération de structs résout l'alignement des noms et des types, mais deux choses ne s'alignent jamais toutes seules : les variantes hors de votre échantillon, et le fossé entre le système de types de Go et celui de JSON.
Ce que le générateur lit vraiment : une table de mapping
Tout convertisseur JSON → Go repose sur la même table. Passez une réponse de commande typique par la page /convert/go de ce site — collez l'échantillon, activez les balises json — et vous obtenez cette forme :
| Valeur JSON | Type Go généré | Remarques |
|---|---|---|
| chaîne | string |
Les chaînes de date restent généralement des chaînes, voir time.Time plus bas |
| entier | float64 |
encoding/json analyse les nombres comme des doubles en interne |
| décimal | float64 |
Remplacez les montants par une bibliothèque decimal ou des int64 en unités mineures |
| true / false | bool |
Aucun piège |
| null | any |
Un seul échantillon null ne prouve rien, repli conservateur |
| objet | struct nommé | Les objets imbriqués deviennent leur propre struct |
objet vide {} |
map[string]any |
Aucun champ observable, le générateur ne devine pas |
| tableau | []TypeÉlément |
Type d'élément déduit du premier échantillon |
| types mixtes | any |
Go n'a pas d'union, les champs multi-types retombent sur any |
// Échantillon d'entrée
// {"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"`
}
Trois observations. L'objet imbriqué items est devenu son propre struct Item référencé par une slice. coupon n'est apparu que comme null : le générateur ne peut pas prouver ce qu'il deviendra et retombe sur any. Le nombre qty atterrit en int ou float64 selon l'outil — les stratégies diffèrent, mais toutes reposent sur la même hypothèse : l'échantillon est toute la vérité.
Les balises json : noms d'origine, options et trois oublis faciles
Les balises portent la plus forte densité d'information de la sortie du générateur et sont aussi la partie la plus facile à modifier de travers. Les règles viennent directement de la documentation d'encoding/json :
Field int `json:"myName"` // apparaît sous la clé myName
Field int `json:"myName,omitempty"` // champ entier omis si vide
Field int `json:",omitempty"` // nom de champ par défaut, option seulement
Field int `json:"-"` // toujours ignoré, ni encodage ni décodage
Field int64 `json:"id,string"` // nombre encodé dans une chaîne
Trois oublis à retenir. D'abord la virgule de tête dans json:",omitempty" — quand on veut seulement sauter les valeurs vides sans renommer la clé, la virgule est obligatoire ; sans elle, le champ est traité comme une clé littéralement nommée ,omitempty. Ensuite, gardez la clé JSON d'origine dans la balise (user_id, html_url) tandis que le champ Go suit la casse idiomatique (UserID, HTMLURL) : sans balise, la correspondance se fait sur le nom du champ verbatim, donc une clé userId ne se mappe jamais silencieusement. Enfin, json:"-" ignore le champ, mais json:"-," signifie que la clé s'appelle réellement -.
Les pointeurs : nil est la seule façon de distinguer « absent » de « zéro »
Le système de valeurs nulles de Go empêche int et string d'exprimer « champ absent » — 0 et "" peuvent être de vraies données ou un champ non analysé. La même clé JSON a trois états : présent avec une valeur, présent comme null, absent. Les types valeur ne couvrent que le premier.
type Config struct {
Note string `json:"note,omitempty"` // omis seulement si exactement ""
Alias *string `json:"alias,omitempty"` // omis si nil
Details *Meta `json:"details,omitempty"`
}
La valeur nulle d'un champ pointeur est nil. json.Unmarshal le laisse nil quand la clé manque ou est null, et omitempty ne le saute qu'alors. C'est pourquoi la plupart des convertisseurs offrent un interrupteur « pointeurs pour les objets imbriqués » : activé, les structs imbriqués deviennent *Item, et dans une requête PATCH « champ non envoyé » et « null envoyé pour supprimer » se séparent enfin. Le prix, ce sont des vérifications de nil partout — p.Address.Street panique si Address est nil, l'un des crashs à l'exécution les plus courants du code JSON en Go.
Le struct vide qu'omitempty ne peut pas supprimer, et le trou que comble omitzero
La définition officielle d'omitempty s'appuie sur les valeurs : false, 0, pointeurs nil, interfaces nil, et tableaux, slices, maps ou chaînes de longueur zéro. Notez ce qui n'y figure pas : les structs vides.
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 n'a rien fait
Un champ de type struct n'est jamais omis par omitempty — il vit en mémoire comme un conteneur de taille fixe, et un conteneur existant n'est pas « vide ». La correction est de transformer le champ en *Meta ; seul un pointeur nil est abandonné. Depuis Go 1.24, un second interrupteur existe, omitzero : jugé selon la valeur nulle de Go, appelant IsZero() bool quand le type en définit une — c'est la seule façon d'omettre un time.Time nul. Avec encoding/json/v2 (expérimental en Go 1.25) la sémantique glisse encore : l'omitempty de v2 juge le résultat JSON encodé (seuls null, "", {}, [] comptent comme vides), donc count: 0 reste dans la sortie ; en migrant du vieux code, l'omitempty des champs bool et numériques doit devenir omitzero pour garder le sens d'origine.
Tous les nombres deviennent float64 : le piège des grands entiers
Sans type explicite, le décodeur d'encoding/json traite les nombres comme float64, et float64 n'a que 53 bits de mantisse. Le cas classique de JavaScript — 9007199254740993 devenant 9007199254740992 — existe aussi en Go, tant que le champ cible est float64 ou any.
var v map[string]any
_ = json.Unmarshal([]byte(`{"id":9007199254740993}`), &v)
// v["id"] vaut float64(9007199254740992), la précision est déjà perdue
Trois sorties. Déclarez le champ comme int64 et le décodeur analyse exactement dedans. Quand vous devez passer par any, appelez decoder.UseNumber() pour que les nombres atterrissent en json.Number à convertir délibérément. N'utilisez jamais de virgule flottante pour l'argent — stockez les unités mineures en int64 ou employez une bibliothèque decimal. Chaque fois qu'une API renvoie des snowflake IDs ou des numéros de commande 64 bits, cette section est une vérification obligatoire.
time.Time n'accepte que RFC 3339
Face à "2024-01-15T10:30:00Z" un générateur mappe time.Time ; face à "2024-01-15 10:30:00" il laisse une chaîne. Ce n'est pas de la paresse — c'est une contrainte dure d'encoding/json : time.Time implémente UnmarshalJSON et analyse strictement dans le format RFC 3339 2006-01-02T15:04:05Z07:00. Un T manquant, un fuseau manquant, ou un Z suivi d'un décalage échouent tous :
parsing time "\"2022-07-27T14:16:00Z04:00\"" as
"\"2006-01-02T15:04:05Z07:00\"": cannot parse "04:00\"" as "\""
Quand le format amont ne peut pas changer, la correction standard est un type personnalisé enveloppant time.Time dont UnmarshalJSON essaie plusieurs formats :
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 liste de contrôle en quatre étapes après la génération
Quatre étapes séparent la sortie du générateur du code de production, et les parcourir une fois coûte moins cher que déboguer plus tard :
- Éliminez chaque repli any : cherchez
any, revoyez trois à cinq échantillons réels par champ en repli, puis atterrissez sur un type concret ou un pointeur ; - Revérifiez les largeurs numériques : passez identifiants, montants et compteurs de float64 à int64 / int32 / decimal ; en cas de doute sur la largeur, écrivez int64 ;
- Marquez l'optionnalité : pointeurs ou omitempty/omitzero pour les champs d'objets de tableau, les corps PATCH et les champs nullables d'API tierces — décidez la sémantique de nil une fois, ici ;
- Compilez et testez l'aller-retour : passez
go vet, puis ajoutez un test aller-retour Marshal→Unmarshal pour verrouiller le format filaire — cela attrape la dérive de comportement des futures mises à jour d'encoding/json.
De l'échantillon au contrat : la frontière du convertisseur
Un convertisseur répond à « à quoi ressemble cet échantillon », pas à « à quoi ressemblera toujours cette interface ». Les outils concurrents le disent franchement dans leurs propres documents : un échantillon ne peut pas prouver les variantes de production — l'optionnalité, les formats de date et les valeurs d'énumération exigent tous une relecture humaine. Prenez donc l'habitude : avant de coller, rassemblez les réponses les plus susceptibles d'exposer les différences (liste vide, tous champs, une avec des null) ; après la génération, traitez la sortie comme un brouillon, pas un livrable. Si l'interface possède un document de contrat, rendez les contraintes explicites avec JSON Schema et alignez le code généré dessus — cela vaut un ordre de grandeur de mieux que l'inférence depuis des échantillons. Pour la vue transversale du même problème, le côté Java est couvert par notre test de terrain du générateur Java, le contrat frontal par les interfaces TypeScript ; le fossé de précision numérique réapparaît dans chaque langue sous un autre costume, détaillé dans le piège des grands nombres JSON.
Quels champs demandent encore une relecture manuelle après génération ?
Au moins quatre : les replis any, les largeurs numériques (float64 → int64), la mise en pointeur des champs optionnels, et si les champs de date doivent être string ou time.Time. Les quatre sont des variantes de production invisibles dans l'échantillon ; le générateur ne devine pas, l'humain doit compléter.
Pourquoi mon champ reste-t-il dans le JSON après avoir ajouté omitempty ?
omitempty ne saute que les valeurs nulles : false, 0, "", nil, slices vides. Un struct vide {} n'est pas une valeur nulle, donc il survit — passez le champ en type pointeur. Un time.Time nul exige omitzero, pas omitempty.
Pourquoi mon grand entier d'identifiant a-t-il changé après désérialisation ?
Sans type explicite, encoding/json analyse les nombres comme float64, qui porte 53 bits de mantisse ; les entiers au-delà de 2^53 perdent en précision. Tapez le champ int64, ou appelez UseNumber() pour garder les nombres en json.Number.
Quand un champ objet imbriqué doit-il être un pointeur ?
Deux cas : le champ peut être absent ou null (nil sépare « non envoyé » de « valeur nulle »), et une requête PATCH doit distinguer « non soumis » de « null soumis pour supprimer ». Pour des structs de réponse ordinaires avec champs non nullables, les types valeur sont plus sûrs — payez le coût des vérifications nil seulement quand vous en avez vraiment besoin.