A maior parte do meu trabalho diário é TypeScript e PHP, mas uma boa parte das ferramentas por trás Toolz.dev e os pequenos serviços que escrevo em torno dele é Go, e toda vez que EU ligar um novo cliente API EU acertei a mesma parede Você tem uma resposta JSON na sua frente, e você precisa da estrutura Go que json.Unmarshal irá decodificá-lo em. escrever essa estrutura à mão é tedioso de uma forma muito específica: não é difícil, é apenas mexer, e os bits mexidos são exatamente onde você comete erros Então EU construí um conversor no site, e este é o guia para ele.
tl;dr: O Toolz Conversor de estrutura JSON para Go analisa um documento JSON e emite as declarações de tipo Go que o descrevem Os objetos tornam-se estruturas inline, matrizes de objetos são mescladas em uma estrutura e cada campo recebe uma
json:"key"tag assimencoding/jsonmapeia os dados de volta corretamente Os nomes dos campos seguem as convenções Go, entãoidtorna-seIDeuser_urltorna-seUserURL. Alternar inteiros paraint64, adicionaromitempty, e renomear o tipo de raiz Ele é executado inteiramente cliente-lado: sem upload, sem inscrição, funciona offline.
O que é um conversor de estrutura JSON para Go?
Um conversor de estrutura JSON para Go transforma um documento JSON nas declarações de tipo Go que o descrevem, para que você possa decodificar os mesmos dados com a biblioteca padrão & #39; s encoding/json pacote em vez de digitar a estrutura manualmente. Cada objeto JSON se torna uma estrutura Go, cada campo carrega um json:"key" tag que mapeia de volta para o nome original, e os tipos escalares são inferidos a partir dos valores Uma string JSON torna-se string, um número inteiro se torna int, um número com vírgula torna-se float64, true e false tornar-se bool, e null torna-se interface{}.
A razão pela qual isso é útil é que um objeto JSON e uma estrutura Go descrevem a mesma forma, um conjunto de campos nomeados com valores digitados, mas Go é digitado estaticamente e JSON não é, então a estrutura tem que soletrar todos os tipos na frente Derivar esses tipos de uma resposta de amostra é mecânica pura, e mecânica feita à mão através de uma carga aninhada é onde os bugs vivem O conversor faz a derivação deterministicamente e devolve um bloco de tipos que compila.
Vale a pena ser claro sobre as duas metades do problema, porque eles são o que um conversor ingênuo erra O primeiro é nomear: Go só codifica campos exportados, aqueles com uma primeira letra maiúscula, e as regras de fiapos comunitários querem inicialismos comuns totalmente capitalizados O segundo é a tag: o json:"..." tag tem que segurar a chave original exata ou json.Unmarshal silenciosamente pula o campo em tempo de execução sem erro Erre e sua decodificação retorna uma estrutura cheia de valores zero enquanto tudo parece bem A ferramenta lida com ambos para você.
Por que não escrever a estrutura à mão?
Esta é a pergunta honesta, porque para um objeto plano de três campos, escrever à mão a estrutura é mais rápido do que abrir uma ferramenta O conversor ganha seu lugar nas respostas que não são planas: uma carga útil com objetos aninhados, matrizes de objetos e vinte campos onde estão metade das chaves snake_case e alguns são inicialismos como id, url, e api_key.
Em uma resposta como essa, a versão escrita à mão tem três modos de falha que EU bati repetidamente Você esquece de exportar um campo, então ele permanece minúsculo e encoding/json recusa-se a preenchê-lo. Você capitaliza o campo, mas esquece a etiqueta, então UserName procura uma chave JSON chamada UserName e nunca encontra user_name. Ou você erra o aninhamento, declarando um campo como uma estrutura simples quando o JSON realmente o envolve em uma matriz Nenhum desses são erros de compilação Eles são surpresas de tempo de execução que aparecem como dados ausentes, e você perde mais tempo depurando um deles do que você teria gasto gerando toda a estrutura.
O conversor remove todos os três Ele exporta todos os campos, ele escreve a tag da chave real, e ele lê a forma JSON real para decidir entre uma estrutura e uma fatia de structs O que você cola é para que você obtém tipos.
Aqui está a decisão em uma tabela.
| situação | usar | por que |
|---|---|---|
| Um objeto plano com dois ou três campos | Escreva-o à mão | Mais rápido do que abrir qualquer coisa |
| Uma resposta de API aninhada com muitos campos | Conversor de estrutura JSON para Go | Nomeação e tags são onde as estruturas escritas à mão quebram |
| Você precisa da mesma forma que TypeScript | Conversor JSON para TypeScript | Mesma inferência, idioma de destino diferente |
| Você quer um esquema de validação, não tipos | Gerador de esquema JSON | Regras do Draft-07 em vez dos tipos Go |
Por que os nomes dos campos Go são diferentes das minhas chaves JSON?
Isso faz as pessoas subirem pela primeira vez, por isso vale a pena explicar em vez de se esconder. Ir e #39;s encoding/json empacote apenas marechais e submarechais exportado struct fields, que significa campos cujo nome começa com uma letra maiúscula Uma chave JSON como user_name não é possível mapear para um não exportado user_name campo, então o campo tem que ser renomeado para algo exportado A ferramenta capitaliza cada palavra, girando user_name em UserName.
Além disso, a comunidade Go e #39; são ferramentas de fiapos, as regras que começaram golint e viva em ferramentas como staticchecké quer inicialismos comuns escritos em letras maiúsculas id torna-se ID, não Id; user_url torna-se UserURL, não UserUrl; e html_body torna-se HTMLBody. O conversor conhece o conjunto padrão de inicialismos, ID, URL, API, HTTP, JSON, UUID, e o resto, e aplica-los, de modo que a saída passa os linters seu CI provavelmente é executado.
A peça que torna a renomeação segura é a tag. Cada campo recebe um json:"user_name" tag segurando a chave original exatamente, então em tempo de execução json.Unmarshal lê a chave JSON user_name e escreve no UserName campo independentemente da renomeação O artigo do Go blog' s sobre JSON e Go documenta esse mecanismo de tag, e é a razão pela qual um campo renomeado ainda decodifica corretamente Sem a tag, a estrutura renomeada falharia silenciosamente em preencher.
Como são tratados os números e os arrays dos objetos?
Duas partes da inferência merecem um olhar mais atento porque são onde os conversores diferem em qualidade.
Números primeiro JSON tem um único tipo de número, mas Go não, então a ferramenta tem que escolher Um valor sem parte fracionária torna-se int, ou int64 se você ativar essa opção, um valor com vírgula será float64. O caso interessante é uma matriz que os mistura, como [9.5, 8, 7.2]. Se a ferramenta digitou isso como []int ele não conseguiria decodificar o 9.5, então amplia toda a fatia para []float64. Qualquer matriz onde um elemento força um tipo mais amplo obtém o tipo mais amplo para todos os elementos, que é a única escolha que decodifica cada valor.
Matrizes de objetos são o outro lugar cargas reais ficam interessantes Uma API quase nunca dá-lhe uma matriz onde cada objeto tem um conjunto idêntico de chaves; um elemento tem um campo os outros omitem, ou um campo anulável está presente aqui e ausente lá Se a ferramenta gerou uma estrutura de apenas o primeiro elemento, ele iria soltar as chaves que aparecem mais tarde Em vez disso ele funde cada objeto na matriz em uma estrutura que inclui cada chave qualquer elemento tem E se dois elementos dão a mesma chave tipos incompatíveis, digamos um número em um e uma cadeia em outro, esse campo cai de volta para interface{} em vez de a ferramenta adivinhar errado ou falhar completamente O resultado é um único tipo de estrutura que pode decodificar toda a matriz.
Como uso o conversor?
O fluxo é de quatro passos Cole um objeto ou matriz JSON na caixa de entrada; se você quiser ver a forma da saída primeiro, carregue a amostra Dê um nome ao tipo raiz, algo como User ou ApiResponse0, e a ferramenta limpa - o num identificador de Go exportado válido para que compile como está escrito Escolher int ou int64 para números inteiros, e ligue omitempty se você quiser campos de valor zero deixados de fora quando a estrutura for posteriormente codificada de volta para JSON Em seguida, clique em Converter e copie a estrutura em seu .go arquivo.
Se o JSON for inválido, a ferramenta reporta a mensagem de erro do próprio analisador & #39; s em vez de falhar silenciosamente, então uma vírgula de fuga perdida ou uma chave não citada é rápida de encontrar E como tudo é executado em seu navegador, você pode colar uma resposta API real, incluindo uma com campos privados, sem que ele saia da sua máquina Esse modelo do lado do cliente é o mesmo atrás do resto do site, descrito no ferramentas online de privacidade de dados guia.
Como isso se encaixa com as outras ferramentas JSON?
O conversor de estrutura JSON para Go é um membro de uma família de transformadores JSON no site, e eles compartilham o mesmo núcleo de análise Quando você deseja arrumar o JSON primeiro, o formatador json irá recuá-lo e validá-lo, o que vale a pena fazer antes de converter para que você possa ler a forma que está prestes a digitar Quando seu idioma de destino é TypeScript em vez de Go, o Conversor JSON para TypeScript executa a mesma inferência e emite interfaces Quando você precisa de um contrato de validação em vez de tipos de linguagem, o Gerador de esquema JSON produz um esquema Draft-07 e, quando o destino é uma base de código PHP, o Conversor de matriz JSON para PHP escreve um array literal.
O tópico que conecta todos eles é que eles tratam JSON como uma fonte de estrutura e traduzem essa estrutura em tudo o que sua base de código fala Se você trabalhar em vários idiomas, o Kit de ferramentas para desenvolvedores web roundup mostra como essas peças se encaixam e o Guia de ferramentas de codificação abrange o conjunto mais amplo de formatadores e conversores.
Um exemplo prático de construção de um serviço Go
Deixe-me tornar isso concreto Um tempo atrás EU estava escrevendo um pequeno serviço Go que puxou dados de uma API de terceiros e reexpôs uma versão simplificada dele A resposta do fornecedor' s foi um objeto aninhado: um registro de nível superior com um owner subobjeto, a tags matriz de cordas e a scores array que, irritantemente, misturava inteiros e decimais dependendo do campo, digitar manualmente a estrutura significava obter o owner aninhando-se direito, marcando cada snake_case chave e decidir o que fazer em relação a esse array misto.
Colei a resposta da amostra no conversor, batizei o tipo raiz em homenagem ao recurso e recuperei uma estrutura com Owner como uma estrutura aninhada em linha, Tags quanto []string, e Scores corretamente ampliado para []float64. o id campo saiu como ID com um json:"id" tag, então ele passou o linter e decodificou a chave real Eu copiei direto para o pacote cliente e passei para a lógica, que é onde EU realmente queria gastar meu tempo A estrutura não era a parte interessante do trabalho, e gerá-la significava que ela deixava de fazer parte do trabalho.
A razão pela qual EU alcancei o conversor em vez de uma estrutura escrita à mão nesses pontos não é a preguiça, é que as partes mecânicas, exportando, marcando e aninhando, são precisamente as partes que EU erro quando estou pensando na lógica em vez disso, descarregá-las para uma ferramenta determinística significa que a estrutura está correta na primeira compilação, e uma decodificação correta na primeira execução, que em uma carga aninhada salva uma sessão de depuração genuína Quando EU preciso da estrutura para também sobreviver sendo recodificada, EU ligo omitempty portanto, os valores zero ficam fora da saída e as tags passam como json:"key,omitempty" pronto para aquela ida e volta.
Quais são os limites que vale a pena conhecer?
Algumas arestas honestas A primeira é null. UM JSON null não carrega nenhuma informação de tipo por si só, portanto, um campo que é null em sua amostra é digitado como interface{}. Não há nada que a ferramenta possa inferir lá; se você sabe o tipo real, altere-o em seu editor após colar, ou alimente o conversor uma amostra onde esse campo tem um valor real para que o tipo possa ser derivado Esta é uma propriedade dos dados, não uma deficiência da ferramenta.
A segunda é a precisão numérica, e é uma propriedade da análise JSON em geral, em vez deste conversor especificamente A ferramenta analisa seu JSON com o analisador JSON browser' s, que representa números como flutuadores de precisão dupla, de modo que inteiros além de aproximadamente 2 elevado à 53a exatidão de perda de energia no momento da análise, antes que a ferramenta os veja. O gerado int64 o campo é largo o suficiente para segurar um grande ID, mas se o ID chegar como um número JSON nu tão grande, a análise já o arredondou Para IDs inteiros realmente grandes, o movimento robusto é carregá-los como strings no JSON, o que os mantém exatos e permite digitar o campo como string.
A terceira é que a inferência é um ponto de partida, não evangelho A ferramenta dá-lhe os tipos que a amostra suporta, mas só você sabe que um campo que passa a ser um inteiro nesta resposta é realmente uma contagem anulável, ou que um float64 deveria ser um json.Number para evitar perda de precisão Trate a saída como um primeiro rascunho correto que você refina, não um contrato esculpido em pedra Isso é verdade para todo gerador JSON-to-types, em qualquer idioma.
Finalmente, o conversor produz estruturas aninhadas em linha, que mantém toda a forma em uma declaração que você pode colar como um bloco Esse é o estilo mais comum e legível para uma estrutura gerada, e é o que as ferramentas no ecossistema Go popularizaram Se você preferir ter tipos nomeados separados para sub-objetos profundamente reutilizados, que é um refator que você faz à mão uma vez que a versão em linha está em seu editor, e geralmente é um extrato de cinco segundos com seu IDE.
Perguntas frequentes
O que é um conversor de estrutura JSON para Go? Um conversor de estrutura JSON para Go transforma um documento JSON nas declarações de tipo Go que o descrevem Cada objeto se torna uma estrutura, cada campo recebe um json: & quot; key& quot; tag, e os tipos de valor são inferidos, para que você possa desmarcar os mesmos dados com codificação/json sem escrever a estrutura manualmente.
Como converto JSON em uma estrutura Go? Cole seu JSON na caixa de entrada, insira um nome para o tipo raiz, escolha suas opções de número inteiro e tag e clique em Converter. A ferramenta imprime definições de estrutura Go com tags json que você pode copiar diretamente em um arquivo.go.
Por que os nomes dos campos Go são diferentes das minhas chaves JSON? Go codifica apenas campos exportados, então cada nome de campo é maiúsculo e as inicializações comuns são maiúsculas para corresponder a golint. O json:"..." tag em cada campo mantém a chave original, então json.Unmarshal ainda mapeia os dados corretamente, apesar do campo renomeado.
Como os números JSON são mapeados para os tipos Go? Um número inteiro torna-se int, ou int64 se você ativar essa opção, e um número com ponto decimal torna-se float64. quando uma matriz mistura inteiros e decimais para a mesma posição, o tipo é ampliado para float64 para que cada valor se ajuste.
Como são tratadas as matrizes de objetos? Uma matriz de objetos é mesclada em uma única estrutura que inclui cada chave que qualquer elemento possui. Se dois elementos fornecerem os mesmos tipos incompatíveis de chave, esse campo se tornará interface {}, então a estrutura ainda cobre toda a matriz.
O que acontece com os valores nulos? Um nulo JSON não fornece informações de tipo por conta própria, portanto o campo é digitado como interface {}. Se você conhece o tipo real, altere-o em seu editor após colar ou forneça um valor de exemplo não nulo no JSON para que o tipo possa ser inferido.
Meu JSON foi carregado em algum lugar? Não. A conversão acontece inteiramente no seu navegador usando JavaScript no seu dispositivo. Seu JSON nunca é carregado, registrado ou armazenado, e a ferramenta continua trabalhando com a rede desconectada assim que a página for carregada.
O conversor de estrutura JSON to Go é gratuito? Sim. é totalmente gratuito sem inscrição, sem marca d'água e sem limite de uso. Converta quantos documentos JSON em estruturas Go você precisar para projetos pessoais ou comerciais.
