Comment mapper JSON pour aller des structures avec des balises de terrain

La plupart de mon travail quotidien est composé de TypeScript et de PHP, mais une bonne partie de l'outillage derrière Toolz.dev et les petits services que j'écris autour de lui, c'est Go, et chaque fois que je câble un nouveau client API je frappe le même mur Vous avez une réponse JSON devant vous, et vous avez besoin de la structure Go qui json.Unmarshal le décodera en Écrivant que struct by hand est fastidieux d'une manière très spécifique : ce n'est pas dur, c'est juste bidouille, et les bits bidouilles sont exactement là où vous faites des erreurs J'ai donc construit un convertisseur dans le site, et c'est le guide pour cela.

tl;dr : Les Toolz Convertisseur de structure JSON en Go analyse un document JSON et émet les déclarations de type Go qui le décrivent Les objets deviennent des structures en ligne, les tableaux d'objets sont fusionnés en une seule structure et chaque champ obtient un json:"key" étiquetez-le encoding/json recale correctement les données Les noms de champs suivent les conventions Go, donc id se transforme ID et user_url se transforme UserURL. Basculer les entiers vers int64, ajouter omitempty« et renommer le type root » Il s'exécute entièrement côté client : pas de téléchargement, pas d'inscription, fonctionne hors ligne.

Qu'est-ce qu'un convertisseur de structure JSON to Go ?

Un convertisseur de structure JSON to Go transforme un document JSON en déclarations de type Go qui le décrivent, afin que vous puissiez décoder les mêmes données avec la bibliothèque standard&#39 ; s encoding/json paquet au lieu de taper la structure à la main Chaque objet JSON devient une structure Go, chaque champ porte un json:"key" balise qui le mappe au nom d'origine, et les types scalaires sont déduits des valeurs Une chaîne JSON devient string: un nombre entier devient int1, un nombre avec une virgule décimale devient float64, true et false devenir bool, et null se transforme interface{}.

La raison pour laquelle cela est utile est qu'un objet JSON et une structure Go décrivent la même forme, un ensemble de champs nommés avec des valeurs typées, mais Go est typé statiquement et JSON ne l'est pas, donc la structure doit épeler chaque type dès le départ. La dérivation de ces types à partir d'une réponse d'échantillon est une pure mécanique, et la mécanique effectuée à la main sur une charge utile imbriquée est l'endroit où vivent les bugs. Le convertisseur effectue la dérivation de manière déterministe et vous remet un bloc de types qui compile.

Il vaut la peine d'être clair sur les deux moitiés du problème, car c'est ce qu'un convertisseur naïf se trompe. Le premier est de nommer : Go code uniquement les champs exportés, ceux avec une première lettre majuscule et les règles de peluche communautaire veulent des initialismes communs entièrement capitalisés. Le second est le tag : le json:"..." la balise doit contenir la clé d'origine exacte ou json.Unmarshal saute silencieusement le champ au moment de l'exécution sans erreur Se tromper et votre décodage renvoie une structure pleine de valeurs nulles alors que tout semble bien L'outil gère les deux pour vous.

Pourquoi ne pas écrire la structure à la main ?

C'est la question honnête, car pour un objet plat à trois champs, l'écriture manuelle de la structure est plus rapide que l'ouverture d'un outil Le convertisseur gagne sa place sur les réponses qui ne sont pas plates : une charge utile avec des objets imbriqués, des tableaux d'objets, et vingt champs où se trouvent la moitié des clés snake_case et quelques-uns sont des initialismes comme id, url, et api_key.

Sur une réponse comme celle-là, la version manuscrite a trois modes d'échec que j'ai frappés à plusieurs reprises Vous oubliez d'exporter un champ, donc il reste minuscule et encoding/json refuse de le peupler. Vous capitalisez le champ mais oubliez le tag, alors UserName recherche une clé JSON appelée UserName et ne trouve jamais user_name. Ou vous vous trompez d'imbrication, déclarant un champ comme une structure simple lorsque le JSON l'enveloppe réellement dans un tableau Aucune de ces erreurs de compilation Ce sont des surprises d'exécution qui apparaissent comme des données manquantes, et vous perdez plus de temps à déboguer l'une d'elles que vous n'auriez passé à générer l'ensemble de la structure.

Le convertisseur supprime les trois Il exporte chaque champ, il écrit la balise de la vraie clé, et il lit la forme réelle de JSON pour décider entre une structure et une tranche de structures Ce que vous collez dans est ce que vous obtenez des types pour.

Voici la décision dans un tableau.

situation	manier	pourquoi
Un objet plat avec deux ou trois champs	Écrivez-le à la main	Plus vite que d'ouvrir quoi que ce soit
Une réponse API imbriquée avec de nombreux champs	Convertisseur de structure JSON en Go	Le nom et les balises sont l'endroit où les structures manuscrites se brisent
Vous avez besoin de la même forme que TypeScript	Convertisseur JSON vers TypeScript	Même inférence, langage cible différent
Vous voulez un schéma de validation, pas des types	Générateur de schéma JSON	Règles Draft-07 plutôt que les types Go

Pourquoi les noms de champs Go sont-ils différents de mes clés JSON ?

Cela fait trébucher les gens la première fois, il vaut donc la peine d'expliquer plutôt que de se cacher. Aller et n°39 ; s encoding/json paquet uniquement des maréchaux et des démaréchaux exporté struct champs, qui signifie champs dont le nom commence par une lettre majuscule Une clé JSON comme user_name impossible de mapper à un non exporté user_name field, le champ doit donc être renommé en quelque chose d'exporté. L'outil capitalise chaque mot en tournant user_name dans UserName.

En plus de cela, la communauté Go&#39 ; s lint tooling, les règles qui ont commencé avec golint et vivre avec des outils comme staticcheck, veut des initialismes communs écrits en majuscules Donc id se transforme ID, pas Id; user_url se transforme UserURL, pas UserUrl; et html_body se transforme HTMLBody. Le convertisseur connaît l'ensemble standard d'initialismes, ID, URL, API, HTTP, JSON, UUID« Et le reste, et les applique, donc la sortie passe les linters que votre CI exécute probablement ».

La pièce qui rend le renommage sûr est la balise Chaque champ obtient un json:"user_name" balise contenant exactement la clé d'origine, donc au moment de l'exécution json.Unmarshal lit la touche JSON user_name et l'écrit dans le UserName field indépendamment du renom Le blog Go&#39 ; son article sur JSON and Go documente ce mécanisme de balise, et c'est la raison pour laquelle un champ renommé décode toujours correctement Sans la balise, la structure renommée ne parviendrait pas à se remplir.

Comment les nombres et les tableaux d'objets sont-ils traités ?

Deux parties de l'inférence méritent un examen plus approfondi car ce sont là que les convertisseurs diffèrent en qualité.

Les nombres d'abord. JSON a un seul type de nombre, mais pas Go, donc l'outil doit choisir Une valeur sans partie fractionnaire devient int, ou int64 si vous activez cette option et qu'une valeur avec une virgule décimale devient float64. Le cas intéressant est un tableau qui les mélange, comme [9.5, 8, 7.2]. Si l'outil a tapé cela comme []int il ne parviendrait pas à décoder le 9.5« , donc cela élargit toute la tranche » []float64. Tout tableau dans lequel un élément force un type plus large obtient le type plus large pour tous les éléments, qui est le seul choix qui décode chaque valeur.

Les tableaux d'objets sont l'autre endroit où les charges utiles réelles deviennent intéressantes Une API ne vous donne presque jamais un tableau où chaque objet a un ensemble identique de clés ; un élément a un champ que les autres omettent, ou un champ nullable est présent ici et absent là Si l'outil générait une structure à partir du seul premier élément, il laisserait tomber les clés qui apparaissent plus tard Au lieu de cela, il fusionne chaque objet du tableau en une structure qui inclut chaque clé que possède un élément. Et si deux éléments donnent la même clé types incompatibles, disons un nombre dans un et une chaîne dans un autre, ce champ revient à interface{} plutôt que l'outil devinant mal ou échouant carrément Le résultat est un type de structure unique qui peut décoder l'ensemble du tableau.

Comment utiliser le convertisseur ?

Le flux est de quatre étapes Collez un objet ou un tableau JSON dans la zone d'entrée ; si vous voulez voir la forme de la sortie en premier, chargez l'échantillon Donnez un nom au type racine, quelque chose comme User ou ApiResponse(en), et l'outil le nettoie en un identifiant Go exporté valide afin qu'il se compile comme écrit Choisissez int ou int64 pour les nombres entiers, et allumez omitempty si vous souhaitez que les champs de valeur zéro soient laissés de côté lorsque la structure est ensuite codée en JSON. Cliquez ensuite sur Convertir et copiez la structure dans votre .go fichier.

Si le JSON n'est pas valide, l'outil signale le message d'erreur parser&#39 ; s propre plutôt que de tomber en panne silencieusement, donc une virgule traînante errante ou une clé non citée est rapide à trouver Et comme tout s'exécute dans votre navigateur, vous pouvez coller une réponse API réelle, y compris une avec des champs privés, sans qu'il quitte votre machine Ce modèle côté client est le même que celui derrière le reste du site, décrit dans le outils en ligne de confidentialité des données guide.

Comment cela s'accorde-t-il avec les autres outils JSON ?

Le convertisseur struct JSON to Go est un membre d'une famille de transformateurs JSON sur le site, et ils partagent le même noyau d'analyse Lorsque vous voulez ranger le JSON en premier, le Formateur JSON va l'indenter et le valider, ce qui vaut la peine d'être fait avant de convertir afin que vous puissiez lire la forme que vous êtes sur le point de taper Lorsque votre langue cible est TypeScript plutôt que Go, le Convertisseur JSON vers TypeScript exécute la même inférence et émet des interfaces Lorsque vous avez besoin d'un contrat de validation au lieu de types de langues, le Générateur de schéma JSON produit un schéma Draft-07, et lorsque la destination est une base de code PHP, le Convertisseur de tableaux JSON en PHP écrit un tableau littéral.

Le fil de discussion les reliant tous est qu'ils traitent JSON comme une source de structure et traduisent cette structure dans tout ce que parle votre base de code Si vous travaillez sur plusieurs langues, le Boîte à outils pour les développeurs Web le résumé montre comment ces pièces s'emboîtent et le Guide des outils de codage couvre l'ensemble plus large de formateurs et de convertisseurs.

Un exemple concret de la création d’un service Go

Permettez-moi de rendre cela concret Il y a quelque temps, j'écrivais un petit service Go qui extrayait des données d'une API tierce et en réexposait une version allégée Le fournisseur&#39 ; s réponse était un objet imbriqué : un enregistrement de haut niveau avec un owner sous-objet, a tags tableau de chaînes, et un scores tableau qui, de manière ennuyeuse, mélangeait des entiers et des décimales selon le champ. Dactylographier manuellement la structure signifiait obtenir le owner nidification à droite, marquage de chaque snake_case clé et décider quoi faire à propos de ce tableau mixte.

J'ai collé l'exemple de réponse dans le convertisseur, nommé le type de racine d'après la ressource, et j'ai récupéré une structure avec Owner en tant que structure imbriquée en ligne, Tags comme []string, et Scores correctement élargi à []float64. le id field est sorti comme ID avec un json:"id" tag, donc il a à la fois passé le linter et décodé la vraie clé Je l'ai copié directement dans le package client et je suis passé à la logique, qui est là où je voulais réellement passer mon temps La structure n'était pas la partie intéressante du travail, et la générer signifiait qu'il a cessé d'être n'importe quelle partie du travail.

La raison pour laquelle j'atteins le convertisseur plutôt qu'une structure manuscrite à ces endroits n'est pas la paresse, c'est que les pièces mécaniques, exportant, étiquetant et imbriquant, sont précisément les pièces sur lesquelles je me trompe lorsque je pense à la logique. Les décharger sur un outil déterministe signifie que la structure est correcte lors de la première compilation, et un décodage correct lors de la première exécution, ce qui sur une charge utile imbriquée enregistre une véritable session de débogage. Lorsque j'ai besoin que la structure survive également à être réencodée, je m'active omitempty ainsi, les valeurs zéro restent en dehors de la sortie et les balises apparaissent comme suit json:"key,omitempty" prêt pour cet aller-retour.

Quelles sont les limites à connaître ?

Quelques bords honnêtes Le premier est null. UN JSON null ne transporte aucune information de type en soi, donc un champ qui l'est null dans votre échantillon est tapé comme interface{}. Il n'y a rien que l'outil peut déduire là ; si vous connaissez le type réel, changez-le dans votre éditeur après avoir collé, ou donnez au convertisseur un échantillon où ce champ a une valeur réelle afin que le type puisse être dérivé. Il s'agit d'une propriété des données et non d'une lacune de l'outil.

La seconde est la précision numérique, et c'est une propriété de JSON analysant en général plutôt que ce convertisseur en particulier L'outil analyse votre JSON avec le navigateur&#39 ; s JSON analyseur, qui représente les nombres comme des flotteurs de double précision, donc les entiers au-delà d'environ 2 à la puissance 53 perdent l'exactitude au moment de l'analyse, avant que l'outil ne les voit jamais Le généré int64 le champ est suffisamment large pour tenir un grand ID, mais si l'ID arrive comme un nombre JSON nu aussi grand, l'analyse l'a déjà arrondi Pour les ID entiers vraiment grands, le mouvement robuste est de les porter comme chaînes dans le JSON, ce qui les garde exactes et vous permet de taper le champ comme string.

La troisième est que l'inférence est un point de départ, pas un évangile L'outil vous donne les types que l'échantillon supporte, mais vous seul savez qu'un champ qui se trouve être un entier dans cette réponse est vraiment un compte nullable, ou qu'un float64 devrait être un json.Number pour éviter la perte de précision Traitez la sortie comme une première ébauche correcte que vous affinez, pas un contrat gravé dans la pierre Cela est vrai de chaque générateur JSON-to-types, dans n'importe quelle langue.

Enfin, le convertisseur produit des structures imbriquées en ligne, qui conservent toute la forme dans une seule déclaration que vous pouvez coller sous forme de bloc. C'est le style le plus courant et le plus lisible pour une structure générée, et c'est ce que les outils de l'écosystème Go ont popularisé. Si vous préférez avoir des types nommés séparés pour les sous-objets profondément réutilisés, c'est un refactor que vous effectuez à la main une fois que la version en ligne est dans votre éditeur, et c'est généralement un extrait de cinq secondes avec votre IDE.

Questions fréquentes

Qu'est-ce qu'un convertisseur de structure JSON to Go ? Un convertisseur de structure JSON to Go transforme un document JSON en déclarations de type Go qui le décrivent Chaque objet devient une structure, chaque champ obtient un json : & quot ; key&quot ; tag, et les types de valeurs sont déduits, vous pouvez donc désamorcer les mêmes données avec encodage/json sans écrire la structure à la main.

Comment convertir JSON en structure Go ? Collez votre JSON dans la zone de saisie, saisissez un nom pour le type de racine, choisissez vos options d'entier et de balise, puis cliquez sur Convertir L'outil imprime les définitions Go struct avec les balises json que vous pouvez copier directement dans un fichier.go.

Pourquoi les noms de champs Go sont-ils différents de mes clés JSON ? Go code uniquement les champs exportés, donc chaque nom de champ est en majuscule et les initialismes communs sont faits en majuscules pour correspondre à la golint. Le json :&quot ;...&quot ; la balise sur chaque champ conserve la clé d'origine, donc json.Unmarshal mappe toujours correctement les données malgré le champ renommé.

Comment les nombres JSON sont-ils mappés sur les types Go ? Un nombre entier devient int, ou int64 si vous activez cette option, et un nombre avec une virgule décimale devient float64. lorsqu'un tableau mélange des entiers et des décimales pour la même position, le type est élargi à float64 donc chaque valeur correspond.

Comment les tableaux d'objets sont-ils gérés ? Un tableau d'objets est fusionné en une seule structure qui inclut chaque clé de tout élément. Si deux éléments donnent les mêmes types clés incompatibles, ce champ devient interface{} donc la structure couvre toujours l'ensemble du tableau.

Qu'arrive-t-il aux valeurs nulles ? Un JSON null ne donne aucune information de type en soi, donc le champ est tapé comme interface{}. Si vous connaissez le type réel, changez-le dans votre éditeur après le collage ou fournissez une valeur d'exemple non nulle dans le JSON afin que le type puisse être déduit.

Mon JSON est-il téléchargé quelque part ? Non. La conversion se produit entièrement dans votre navigateur à l'aide de JavaScript sur votre appareil. Votre JSON n'est jamais téléchargé, enregistré ou stocké, et l'outil continue de fonctionner avec le réseau déconnecté une fois la page chargée.

Le convertisseur struct JSON to Go est-il gratuit ? Oui. Il est entièrement gratuit sans inscription, sans filigrane et sans plafond d'utilisation. Convertissez autant de documents JSON en structures Go que nécessaire pour des projets personnels ou commerciaux.