Tutorial: Trabalhando com JSON
JSON (JavaScript Object Notation) é um formato simples de troca de dados. Sintaticamente, ele se parece com os objetos e listas do JavaScript. É muito usado para comunicação com serviços de API em rede, mas também aparece em muitos outros lugares. A página oficial, json.org, traz uma definição excelente, clara e concisa do padrão.
Com o pacote encoding/json/v2, é muito simples ler e escrever dados JSON nos seus programas em Go. Esse pacote oferece uma API mais limpa e padrões melhores do que o pacote mais antigo encoding/json.
Codificação
Para codificar dados JSON, usamos a função Marshal.
func Marshal(in any, opts ...Options) (out []byte, err error)
Dada a estrutura de dados do Go, Message,
type Message struct {
Name string
Body string
Time time.Time
}
e uma instância de Message
m := Message{"Alice", "Hello", time.Date(2011, 1, 25, 0, 0, 0, 0, time.UTC)}
podemos fazer o marshal de uma versão JSON de m usando json.Marshal:
b, err := json.Marshal(m)
Se tudo correr bem, err será nil e b será um []byte contendo estes dados JSON:
b == []byte(`{"Name":"Alice","Body":"Hello","Time":"2011-01-25T00:00:00Z"}`)
Só são codificadas estruturas de dados que podem ser representadas como JSON válido:
-
Ponteiros são codificados como os valores para os quais apontam (ou como
nullse o ponteiro fornil). -
Objetos JSON só aceitam strings como chaves. Assim, para codificar um map do Go, ele precisa ter uma chave que seja codificada como string JSON, como
map[string]T(em queTé qualquer tipo do Go suportado pelo pacote json). -
Tipos de canal, complexos e funções não podem ser codificados.
-
Estruturas de dados cíclicas não são suportadas.
-
Marshaldocumenta o conjunto completo da semântica de codificação.
O pacote json só acessa os campos exportados de tipos struct (aqueles que começam com letra maiúscula). Por isso, apenas os campos exportados de uma struct aparecem na saída JSON.
Decodificação
Para decodificar dados JSON, usamos a função Unmarshal.
func Unmarshal(in []byte, out any, opts ...Options) (err error)
Primeiro, precisamos criar um lugar onde os dados decodificados serão armazenados
var m Message
e chamar json.Unmarshal, passando a ela um []byte com os dados JSON e um ponteiro para m
err := json.Unmarshal(b, &m)
Se b contiver JSON válido que caiba em m,
depois da chamada err será nil e os dados de b terão sido
armazenados na struct m,
como se fosse feita uma atribuição como:
m = Message{
Name: "Alice",
Body: "Hello",
Time: time.Date(2011, 1, 25, 0, 0, 0, 0, time.UTC),
}
Como o Unmarshal identifica os campos onde deve guardar os dados decodificados?
Para uma chave JSON "Foo",
o Unmarshal procura nos campos da struct de destino (em
ordem de preferência):
-
Um campo exportado com a tag
json:"Foo"(veja a especificação da linguagem Go para mais sobre tags de struct), ou -
Um campo exportado chamado
Foo.
E o que acontece quando a estrutura dos dados JSON não bate exatamente com o tipo do Go?
b := []byte(`{"Name":"Bob","Food":"Pickle"}`)
var m Message
err := json.Unmarshal(b, &m)
O Unmarshal decodifica apenas os campos que consegue encontrar no tipo de destino.
Nesse caso, só o campo Name de m será preenchido,
e o campo Food será ignorado.
Esse comportamento é especialmente útil quando você quer extrair apenas alguns
campos específicos de um JSON grande.
Isso também significa que quaisquer campos não exportados da struct de destino
não são afetados pelo Unmarshal.
Mas e se você não souber a estrutura dos seus dados JSON de antemão?
JSON genérico com any
O tipo any descreve qualquer tipo do Go.
any é definido como interface{} (interface vazia), que descreve uma interface sem métodos.
Todo tipo do Go implementa pelo menos zero métodos e, portanto, satisfaz a interface vazia.
any funciona como um tipo contêiner genérico:
var a any
a = "a string"
a = 2011
a = 2.777
Uma asserção de tipo acessa o tipo concreto subjacente:
r := a.(float64)
fmt.Println("the circle's area", math.Pi*r*r)
Ou, se o tipo subjacente for desconhecido, um switch de tipo determina o tipo:
switch v := a.(type) {
case int:
fmt.Println("twice a is", v*2)
case float64:
fmt.Println("the reciprocal of a is", 1/v)
case string:
h := len(v) / 2
fmt.Println("a swapped by halves is", v[h:]+v[:h])
default:
// a isn't one of the types above
}
O pacote json usa valores map[string]any e
[]any para armazenar objetos e arrays JSON arbitrários;
ele aceita de bom grado fazer o unmarshal de qualquer JSON válido
em um valor any simples. Os tipos concretos padrão do Go são:
-
boolpara booleanos JSON, -
float64para números JSON, -
stringpara strings JSON, e -
nilpara null JSON.
Decodificando dados arbitrários
Considere estes dados JSON, armazenados na variável b:
b := []byte(`{"Name":"Wednesday","Age":6,"Parents":["Gomez","Morticia"]}`)
Sem saber a estrutura desses dados, podemos decodificá-los em um valor any com Unmarshal:
var f any
err := json.Unmarshal(b, &f)
Neste ponto, o valor do Go em f seria um map cujas chaves são strings
e cujos valores são, por sua vez, armazenados como valores any:
f = map[string]any{
"Name": "Wednesday",
"Age": 6,
"Parents": []any{
"Gomez",
"Morticia",
},
}
Para acessar esses dados, podemos usar uma asserção de tipo para obter o map[string]any subjacente de f:
m := f.(map[string]any)
Depois, podemos percorrer o map com uma instrução range e usar um switch de tipo para acessar seus valores como os tipos concretos:
for k, v := range m {
switch vv := v.(type) {
case string:
fmt.Println(k, "is string", vv)
case float64:
fmt.Println(k, "is float64", vv)
case []any:
fmt.Println(k, "is an array:")
for i, u := range vv {
fmt.Println(i, u)
}
default:
fmt.Println(k, "is of a type I don't know how to handle")
}
}
Dessa forma, você pode trabalhar com dados JSON desconhecidos e ainda aproveitar os benefícios da segurança de tipos.
Tipos de referência
Vamos definir um tipo do Go para conter os dados do exemplo anterior:
type FamilyMember struct {
Name string
Age int
Parents []string
}
var m FamilyMember
err := json.Unmarshal(b, &m)
Fazer o unmarshal desses dados em um valor FamilyMember funciona como esperado,
mas, se olharmos com atenção, podemos notar algo notável que aconteceu.
Com a instrução var, alocamos uma struct FamilyMember e
passamos um ponteiro para esse valor ao Unmarshal,
mas, naquele momento, o campo Parents era um valor de slice nil.
Para preencher o campo Parents, o Unmarshal alocou uma nova slice por trás dos panos.
Isso é típico da forma como o Unmarshal trabalha com os tipos de referência suportados
(ponteiros, slices e maps).
Considere fazer o unmarshal nesta estrutura de dados:
type Foo struct {
Bar *Bar
}
Se houvesse um campo Bar no objeto JSON,
o Unmarshal alocaria um novo Bar e o preencheria.
Se não houvesse, Bar ficaria como um ponteiro nil.
Disso surge um padrão útil: se você tiver uma aplicação que recebe alguns tipos distintos de mensagem, você pode definir uma estrutura “receptora” como
type IncomingMessage struct {
Cmd *Command
Msg *Message
}
e a parte que envia pode preencher o campo Cmd e/ou o campo Msg
do objeto JSON de nível superior,
dependendo do tipo de mensagem que quer comunicar.
O Unmarshal, ao decodificar o JSON em uma struct IncomingMessage,
só alocará as estruturas de dados presentes nos dados JSON.
Para saber quais mensagens processar, o programador só precisa testar se
Cmd ou Msg não é nil.
Marshal e Unmarshal em streaming
As interfaces io.Reader e io.Writer são onipresentes em Go, oferecendo acesso em streaming a recursos como conexões HTTP, WebSockets ou arquivos.
As funções MarshalWrite e UnmarshalRead permitem fazer marshal e unmarshal diretamente de e para esses streams, sem precisar de um []byte intermediário que armazene a mensagem inteira.
func MarshalWrite(out io.Writer, in any, opts ...Options) (err error)
func UnmarshalRead(in io.Reader, out any, opts ...Options) (err error)
Por exemplo, podemos escrever a saída do marshal diretamente na saída padrão:
err := json.MarshalWrite(os.Stdout, m)
Marshal e Unmarshal personalizados
Às vezes, o comportamento padrão de marshal não faz sentido para o seu tipo.
Por exemplo, suponha que temos um tipo que descreve a versão de um software.
type Version struct {
Major, Minor, Patch int64
}
v := Version{1, 2, 3}
b, err := json.Marshal(s)
Isso faz o marshal como {"Major":1,"Minor":2,"Patch":3}, como esperado com base na definição da struct, mas uma string de versão como “1.2.3” provavelmente seria uma representação melhor para quem consome o JSON.
Implementando a interface MarshalerTo, podemos fornecer uma representação JSON personalizada.
UnmarshalerFrom faz o unmarshal da representação JSON personalizada.
type MarshalerTo interface {
MarshalJSONTo(*jsontext.Encoder) error
}
type UnmarshalerFrom interface {
UnmarshalJSONFrom(*jsontext.Decoder) error
}
Podemos implementar esses métodos para converter de e para representações em string.
func (v Version) MarshalJSONTo(enc *jsontext.Encoder) error {
return json.MarshalEncode(enc, fmt.Sprintf("%d.%d.%d", v.Major, v.Minor, v.Patch))
}
Com o marshal personalizado, o valor Version{1, 2, 3} agora faz marshal como "1.2.3".
func (v *Version) UnmarshalJSONFrom(dec *jsontext.Decoder) error {
if k := dec.PeekKind(); k != jsontext.KindString {
// Value must be a string.
return &json.SemanticError{JSONKind: k}
}
var s string
if err := json.UnmarshalDecode(dec, &s); err != nil {
return err
}
_, err := fmt.Sscanf(s, "%d.%d.%d", &v.Major, &v.Minor, &v.Patch)
return err
}
Com o unmarshal personalizado, "1.2.3" agora faz unmarshal como Version{1, 2, 3}.
Este exemplo simples exige exatamente o formato de versão "major.minor.patch", mas um UnmarshalJSONFrom mais complexo poderia escolher adicionar flexibilidade, por exemplo tornando opcionais as versões minor e patch.
Referências
Para mais informações, veja a documentação dos pacotes encoding/json/v2 e encoding/json/jsontext.