La mayor parte de mi trabajo diario es TypeScript y PHP, pero hay una buena parte de las herramientas detrás Toolz.dev y los pequeños servicios que escribo son Go, y cada vez que conecto un nuevo cliente API golpeo la misma pared. Tienes una respuesta JSON frente a ti y necesitas la estructura Go json.Unmarshal lo decodificará en. Escribir esa estructura a mano es tedioso de una manera muy específica: no es difícil, es simplemente complicado, y las partes complicadas son exactamente donde cometes errores. Así que incorporé un conversor al sitio y esta es la guía para ello.
TL;Dr: La herramientaz Convertidor de estructuras JSON to Go analiza un documento JSON y emite las declaraciones de tipo Go que lo describen. Los objetos se convierten en estructuras en línea, las matrices de objetos se fusionan en una sola estructura y cada campo obtiene una
json:"key"etiqueta asíencoding/jsonmapea los datos correctamente. Los nombres de los campos siguen las convenciones Go, así queidse convierte enIDyuser_urlse convierte enUserURL. Cambia números enteros aint64, añadeomitemptyy cambie el nombre del tipo raíz. Se ejecuta completamente del lado del cliente: sin carga, sin registro, funciona sin conexión.
¿qué es un convertidor de estructuras JSON to Go?
Un convertidor de estructura JSON to Go convierte un documento JSON en declaraciones de tipo Go que lo describen, por lo que puede decodificar los mismos datos con la biblioteca estándar 's encoding/json paquete en lugar de escribir la estructura a mano. Cada objeto JSON se convierte en una estructura Go, cada campo lleva un json:"key" etiqueta que lo asigna al nombre original y los tipos escalares se infieren a partir de los valores. Se convierte en una cadena JSON string, un número entero se convierte int, un número con un punto decimal se convierte en float64, true y false convertirse en booly null se convierte en interface{}.
La razón por la que esto es útil es que un objeto JSON y una estructura Go describen la misma forma, un conjunto de campos con nombre con valores tipificados, pero Go está escrito estáticamente y JSON no, por lo que la estructura tiene que deletrear cada tipo en el frente. Derivar esos tipos a partir de una respuesta de muestra es pura mecánica, y la mecánica realizada a mano a través de una carga útil anidada es donde viven los errores. El convertidor hace la derivación de manera determinista y le devuelve un bloque de tipos que compila.
Vale la pena tener claro las dos mitades del problema, porque son lo que un conversor ingenuo se equivoca. El primero es nombrar: Go solo codifica campos exportados, los que tienen una primera letra mayúscula y las reglas de la pelusa comunitaria quieren iniciales comunes completamente en mayúscula. El segundo es la etiqueta: el json:"..." la etiqueta debe contener la clave original exacta o json.Unmarshal se salta silenciosamente el campo en tiempo de ejecución sin errores. Si te equivocas, tu decodificación devuelve una estructura llena de valores cero mientras todo se ve bien. La herramienta maneja ambos por ti.
¿Por qué no escribir la estructura a mano?
Esta es la pregunta honesta, porque para un objeto plano de tres campos, escribir a mano la estructura es más rápido que abrir una herramienta. El convertidor gana su lugar en las respuestas que no son planas: una carga útil con objetos anidados, matrices de objetos y veinte campos donde están la mitad de las claves snake_case y algunos son inicialismos como id, urly api_key.
En una respuesta como esa, la versión escrita a mano tiene tres modos de falla que presiono repetidamente. Olvidas exportar un campo, por lo que permanece en minúsculas y encoding/json se niega a completarlo. Capitalizas el campo pero olvidas la etiqueta, así que UserName busca una clave JSON llamada UserName y nunca lo encuentra user_name. O te equivocas al anidar, declarando un campo como una estructura simple cuando el JSON realmente lo envuelve en una matriz. Ninguno de estos son errores de compilación. Son sorpresas en tiempo de ejecución que aparecen como datos faltantes y pierdes más tiempo depurando uno de ellos del que habrías dedicado a generar toda la estructura.
El convertidor elimina los tres. Exporta todos los campos, escribe la etiqueta a partir de la clave real y lee la forma JSON real para decidir entre una estructura y una porción de estructuras. Lo que pegas es para qué obtienes tipos.
Aquí está la decisión en una tabla.
| colocación | aprovechamiento | porque |
|---|---|---|
| Un objeto plano con dos o tres campos | Escríbelo a mano | Más rápido que abrir cualquier cosa |
| Una respuesta API anidada con muchos campos | Convertidor de estructuras JSON to Go | Los nombres y las etiquetas son donde se rompen las estructuras escritas a mano |
| Necesitas la misma forma que TypeScript | Convertidor JSON a TypeScript | Misma inferencia, diferente idioma de destino |
| Quiere un esquema de validación, no tipos | Generador de esquemas JSON | Borrador de reglas 07 en lugar de tipos Go |
¿por qué los nombres de los campos Go son diferentes de mis claves JSON?
Esto hace tropezar a la gente la primera vez, por lo que vale la pena explicarlo en lugar de esconderlo. Ir 's encoding/json paquete solo mariscales y unmarshals exportado campos de estructura, que significa campos cuyo nombre comienza con una letra mayúscula. Una clave JSON como user_name no se puede asignar a un no exportado user_name campo, por lo que se debe cambiar el nombre del campo a algo exportado. La herramienta escribe en mayúscula cada palabra, girando user_name hacia el interior de UserName.
Además de eso, la comunidad Go 's pelusa, las reglas que comenzaron con golint y sigue vivo en herramientas como staticcheck, quiere iniciales comunes escritas en mayúsculas. Entonces id se convierte en ID, no Id; user_url se convierte en UserURL, no UserUrl; y html_body se convierte en HTMLBody. El convertidor conoce el conjunto estándar de iniciales ID, URL, API, HTTP, JSON, UUID, y el resto, y los aplica, por lo que la salida pasa los linters que probablemente ejecuta su CI.
La pieza que hace que el cambio de nombre sea seguro es la etiqueta. Cada campo obtiene un json:"user_name" etiqueta que contiene exactamente la clave original, así que en tiempo de ejecución json.Unmarshal lee la clave JSON user_name y lo escribe en el UserName campo independientemente del cambio de nombre. El blog Go & #39;s en JSON y Go documenta este mecanismo de etiqueta, y es la razón por la que un campo renombrado aún decodifica correctamente. Sin la etiqueta, la estructura renombrada silenciosamente no se completaría.
¿cómo se manejan los números y matrices de objetos?
Dos partes de la inferencia merecen una mirada más cercana porque es donde los convertidores difieren en calidad.
Números primero. JSON tiene un solo tipo de número, pero Go no, por lo que la herramienta tiene que elegir. Se convierte en un valor sin parte fraccionaria int, o int64 si activa esa opción, se convierte en un valor con un punto decimal float64. El caso interesante es una matriz que los mezcla, como [9.5, 8, 7.2]. Si la herramienta escribiera eso como []int no lograría decodificar el 9.5, entonces ensancha toda la rebanada []float64. Cualquier matriz donde un elemento fuerza a un tipo más ancho obtiene el tipo más ancho para todos los elementos, que es la única opción que decodifica cada valor.
Las matrices de objetos son el otro lugar donde las cargas útiles reales se vuelven interesantes. Una API casi nunca le proporciona una matriz donde cada objeto tiene un conjunto idéntico de claves; un elemento tiene un campo que los demás omiten, o un campo anulable está presente aquí y ausente allí. Si la herramienta generara una estructura solo a partir del primer elemento, eliminaría las claves que aparecen más tarde. En lugar de eso, fusiona cada objeto de la matriz en una estructura que incluye cada clave que tenga cualquier elemento. Y si dos elementos dan los mismos tipos incompatibles de claves, digamos un número en uno y una cadena en otro, ese campo vuelve a caer interface{} en lugar de que la herramienta adivine mal o falle por completo. El resultado es un tipo de estructura única que puede decodificar toda la matriz.
¿Cómo uso el convertidor?
El flujo consta de cuatro pasos. Pegue un objeto o matriz JSON en el cuadro de entrada; Si desea ver primero la forma de la salida, cargue la muestra. Dale un nombre al tipo de raíz, algo así como User investigaciones operacionales ApiResponse, y la herramienta lo limpia hasta convertirlo en un identificador Go exportado válido para que se compile tal como está escrito. Elegir int investigaciones operacionales int64 para números enteros, y enciende omitempty si desea que los campos de valor cero queden fuera cuando la estructura se codifique posteriormente a JSON. Luego haga clic en Convertir y copie la estructura en su .go archivo
Si el JSON no es válido, la herramienta informa el propio mensaje de error del analizador ' en lugar de fallar silenciosamente, por lo que se puede encontrar rápidamente una coma final perdida o una clave sin comillas. Y debido a que todo se ejecuta en su navegador, puede pegar una respuesta API real, incluida una con campos privados, sin que salga de su máquina. Ese modelo del lado del cliente es el mismo que se encuentra detrás del resto del sitio, descrito en el herramientas en línea de privacidad de datos guía.
¿cómo encaja esto con las otras herramientas JSON?
El convertidor de estructura JSON to Go es un miembro de una familia de transformadores JSON en el sitio y comparten el mismo núcleo de análisis. Cuando primero desea ordenar el JSON, el Formateador JSON lo sangrará y validará, lo cual vale la pena hacer antes de convertir para que pueda leer la forma que está a punto de escribir. Cuando su idioma de destino es TypeScript en lugar de Go, el Convertidor JSON a TypeScript ejecuta la misma inferencia y emite interfaces. Cuando necesita un contrato de validación en lugar de tipos de lenguaje, el Generador de esquemas JSON produce un esquema Draft-07 y, cuando el destino es un código base PHP, el Convertidor de matriz JSON a PHP escribe una matriz literal.
El hilo que los conecta a todos es que tratan a JSON como una fuente de estructura y traducen esa estructura a lo que diga su código base. Si trabaja en varios idiomas, el Kit de herramientas para desarrolladores web el resumen muestra cómo estas piezas se encajan y el Guía de herramientas de codificación cubre el conjunto más amplio de formateadores y convertidores.
Un ejemplo práctico de la creación de un servicio Go
Déjame concretar esto. Hace un tiempo estaba escribiendo un pequeño servicio Go que extraía datos de una API de terceros y volvía a exponer una versión reducida del mismo. La respuesta del proveedor ' fue un objeto anidado: un registro de nivel superior con un owner subobjeto, a tags conjunto de cadenas y a scores matriz que, molestamente, mezclaba números enteros y decimales según el campo. Escribir manualmente la estructura significaba obtener el owner anidando bien, etiquetando cada snake_case clave y decidir qué hacer con esa matriz mixta.
Pegué la respuesta de muestra en el convertidor, nombré el tipo de raíz con el nombre del recurso y recuperé una estructura con Owner como estructura anidada en línea, Tags de []stringy Scores correctamente ampliado a []float64. los id el campo salió como ID con un json:"id" etiqueta, por lo que pasó la linter y decodificó la clave real. Lo copié directamente en el paquete del cliente y pasé a la lógica, que es donde realmente quería pasar mi tiempo. La estructura no era la parte interesante del trabajo y generarla significaba que dejaba de ser parte del trabajo.
La razón por la que busco el convertidor en lugar de una estructura escrita a mano en estos lugares no es la pereza, es que las partes mecánicas, la exportación, el etiquetado y el anidamiento son precisamente las partes en las que me equivoco cuando pienso en la lógica. Descargarlos en una herramienta determinista significa que la estructura es correcta en la primera compilación y una decodificación correcta en la primera ejecución, lo que en una carga útil anidada guarda una sesión de depuración genuina. Cuando necesito que la estructura también sobreviva a la recodificación, la enciendo omitempty entonces los valores cero permanecen fuera de la salida y las etiquetas aparecen como json:"key,omitempty" listo para ese viaje de ida y vuelta.
¿Cuáles son los límites que vale la pena conocer?
Algunas ventajas honestas. El primero es null. UN JSON null no lleva información de tipo por sí solo, por lo que es un campo null en su muestra se escribe como interface{}. No hay nada que la herramienta pueda inferir allí; si conoce el tipo real, cámbielo en su editor después de pegarlo o alimente al convertidor una muestra donde ese campo tenga un valor real para que se pueda derivar el tipo. Esta es una propiedad de los datos, no una deficiencia de la herramienta.
El segundo es la precisión numérica y es una propiedad del análisis JSON en general y no de este convertidor específicamente. La herramienta analiza su JSON con el navegador 's JSON parser, que representa números como flotadores de doble precisión, por lo que los números enteros más allá de aproximadamente 2 elevado a la 53.a potencia pierden exactitud en el momento del análisis, antes de que la herramienta los vea. El generado int64 el campo es lo suficientemente amplio como para mantener un ID grande, pero si el ID llega como un número JSON simple de ese tamaño, el análisis ya lo ha redondeado. Para ID de números enteros verdaderamente grandes, el movimiento sólido es transportarlos como cadenas en el JSON, lo que los mantiene exactos y le permite escribir el campo como string.
La tercera es que la inferencia es un punto de partida, no un evangelio. La herramienta te brinda los tipos que admite la muestra, pero solo tú sabes que un campo que resulta ser un número entero en esta respuesta es en realidad un recuento anulable, o que a float64 debería ser un json.Number para evitar pérdidas de precisión. Trate la salida como un primer borrador correcto que refina, no como un contrato tallado en piedra. Esto es cierto para todos los generadores de JSON a tipos, en cualquier idioma.
Finalmente, el convertidor produce estructuras anidadas en línea, que mantiene toda la forma en una declaración que puedes pegar como un bloque. Ese es el estilo más común y legible para una estructura generada, y es lo que popularizaron las herramientas en el ecosistema Go. Si prefiere tener tipos con nombre separados para subobjetos profundamente reutilizados, ese es un refactor que hace a mano una vez que la versión en línea está en su editor, y generalmente es un extracto de cinco segundos con su IDE.
Preguntas frecuentes
¿qué es un convertidor de estructuras JSON to Go? Un convertidor de estructura JSON to Go transforma un documento JSON en declaraciones de tipo Go que lo describen. Cada objeto se convierte en una estructura, cada campo obtiene un json:"key" etiqueta y se infieren los tipos de valores, por lo que puede descomprimir los mismos datos con codificación/json sin escribir la estructura a mano.
¿cómo convierto JSON a una estructura Go? Pegue su JSON en el cuadro de entrada, ingrese un nombre para el tipo raíz, elija sus opciones de entero y etiqueta, luego haga clic en Convertir. La herramienta imprime definiciones de estructura Go con etiquetas json que puede copiar directamente en un archivo .go.
¿por qué los nombres de los campos Go son diferentes de mis claves JSON? Go solo codifica campos exportados, por lo que el nombre de cada campo está en mayúscula y las iniciales comunes se hacen en mayúsculas para que coincidan con golint. El json:"..." La etiqueta en cada campo mantiene la clave original, por lo que json.Unmarshal aún asigna los datos correctamente a pesar del campo renombrado.
¿cómo se asignan los números JSON a los tipos Go? Un número entero se vuelve int, o int64 si habilita esa opción, y un número con un punto decimal se convierte en float64. Cuando una matriz mezcla números enteros y decimales para la misma posición, el tipo se amplía a float64 para que cada valor encaje.
¿cómo se manejan las matrices de objetos? Una matriz de objetos se fusiona en una única estructura que incluye todas las claves que tiene cualquier elemento. Si dos elementos dan los mismos tipos incompatibles de claves, ese campo se convierte en interfaz{}, por lo que la estructura aún cubre toda la matriz.
¿Qué pasa con los valores nulos? Un JSON nulo no proporciona información de tipo por sí solo, por lo que el campo se escribe como interfaz{}. Si conoce el tipo real, cámbielo en su editor después de pegarlo o proporcione un valor de ejemplo no nulo en el JSON para que se pueda inferir el tipo.
¿Se subió mi json a alguna parte? No. La conversión se realiza completamente en su navegador mediante JavaScript en su dispositivo. Su JSON nunca se carga, registra ni almacena, y la herramienta sigue funcionando con la red desconectada una vez que se ha cargado la página.
¿el convertidor de estructuras JSON to Go es gratuito? Sí. Es completamente gratuito, sin registro, sin marca de agua ni límite de uso. Convierta tantas estructuras JSON a Go como necesite para proyectos personales o comerciales.
