Introdução ao JSON em Java

JSON (JavaScript Object Notation) é o formato mais comum para troca de dados na web. APIs o retornam, arquivos de configuração o utilizam e serviços o passam entre si. O Java não possui suporte nativo a JSON no JDK principal, então trabalhar com JSON significa escolher uma biblioteca — mas os conceitos de parsing, mapeamento e serialização permanecem os mesmos independentemente da que você escolher.

Esta página é o mapa para a seção de JSON: explica o que é JSON, como seus tipos se alinham com os tipos Java, quais bibliotecas existem e os dois modelos de parsing. Os capítulos seguintes aprofundam as duas bibliotecas mais populares — JSON com Jackson e JSON com Gson.

O Que É JSON

JSON é um formato leve, baseado em texto, para dados estruturados. É construído a partir de alguns tipos simples: strings, números, booleanos, null, arrays (listas ordenadas) e objetos (mapas de chave/valor). Por ser texto simples, qualquer linguagem pode lê-lo e escrevê-lo, o que é por isso que se tornou a língua franca das APIs web.

{
  "name": "Ann",
  "age": 30,
  "admin": true,
  "roles": ["editor", "author"],
  "address": null
}

O formato se mapeia diretamente para tipos de linguagens de programação. Em Java, um objeto JSON se torna um Map ou uma classe personalizada, um array se torna uma List ou um array, e os tipos escalares se tornam String, Number, Boolean e null.

Por Que JSON É Importante

JSON é o payload padrão para APIs REST, e programas Java constantemente o enviam e recebem: um serviço web lê o corpo de uma requisição JSON, consulta um banco de dados e escreve uma resposta JSON. Ele também é legível por humanos, por isso serve também como formato de configuração e log.

Comparado ao XML — o formato de intercâmbio mais antigo que o JSON amplamente substituiu — o JSON é mais conciso, tem menos cerimônia e se mapeia mais diretamente para estruturas de dados de linguagens. O XML ainda é preferido quando você precisa de esquemas, namespaces ou conteúdo misto, mas para troca simples de dados o JSON é geralmente a escolha mais leve.

As Principais Bibliotecas Java

O JDK não inclui um parser JSON, então você adiciona um. Três bibliotecas dominam:

Jackson é o mais amplamente utilizado. Sua classe central é ObjectMapper, que converte entre texto JSON e objetos Java em uma única chamada:

import com.fasterxml.jackson.databind.ObjectMapper;

ObjectMapper mapper = new ObjectMapper();

// Java object -> JSON text (serialize)
String json = mapper.writeValueAsString(user);

// JSON text -> Java object (deserialize)
User parsed = mapper.readValue(json, User.class);

Gson segue a mesma forma com nomes diferentes:

import com.google.gson.Gson;

Gson gson = new Gson();
String json = gson.toJson(user);          // serialize
User parsed = gson.fromJson(json, User.class); // deserialize

Adicione a biblioteca como dependência antes de usá-la — para Jackson é com.fasterxml.jackson.core:jackson-databind; para Gson, com.google.code.gson:gson.

Qual você deve escolher? Se você está no Spring Boot, o Jackson já está lá e configurado, então use-o. Para uma ferramenta standalone pequena ou um app Android onde o tamanho do binário importa, a API minimalista e sem configuração do Gson é conveniente. Recorra ao JSON-B apenas quando você estiver comprometido com o stack Jakarta EE e quiser o padrão neutro de fornecedor. Na prática, a escolha raramente importa para a corretude — todas as três leem e escrevem o mesmo JSON — então prefira a que já está no seu classpath.

Duas Formas de Fazer Parsing: Árvore vs Binding

Qualquer que seja a biblioteca escolhida, há dois modelos principais para leitura de JSON:

• Data binding mapeia o JSON diretamente para classes Java. Você define uma classe (ou record) cujos campos correspondem às chaves, e a biblioteca os preenche. Esta é a abordagem mais limpa quando a estrutura é conhecida e estável.
• Modelo de árvore / mapa faz o parsing do JSON em uma árvore genérica de nós (JsonNode no Jackson) ou um Map<String, Object>. Você navega por chave. Use isso quando a forma é dinâmica ou você precisa apenas de alguns campos.

// Binding: structure known ahead of time
record User(String name, int age, boolean admin) {}
User u = mapper.readValue(json, User.class);
System.out.println(u.name());

// Tree: navigate without a class
JsonNode root = mapper.readTree(json);
System.out.println(root.get("name").asText());

O binding oferece segurança de tipos e código legível; o modelo de árvore oferece flexibilidade. A maioria das aplicações usa binding para seus próprios objetos de domínio e recorre ao modelo de árvore apenas para dados com estrutura menos rígida.

Um Exemplo Executável

O sandbox não tem Jackson ou Gson no classpath, então o programa abaixo usa apenas coleções do JDK para demonstrar a mesma ideia: um objeto JSON parseado é apenas chaves mapeadas para valores tipados, um array é uma List, e serializar transforma essa estrutura de volta em texto JSON. Os exemplos estáticos acima mostram a API real da biblioteca que você usará em um projeto.

O que aprender com a execução:

• Um objeto JSON parseado se comporta como um Map: você obtém cada campo pela sua chave, exatamente como mapper.readTree(...).get("name") faria no Jackson.
• Os valores JSON mantêm seu tipo — age volta como Number e admin como Boolean, não como texto bruto, razão pela qual age instanceof Number imprime true.
• Um array JSON mapeia para uma List, então roles é iterável e reporta um tamanho de 2.
• A serialização é o inverso do parsing: percorrer a mesma estrutura reconstrói o texto JSON compacto {"name":"Ann",...}.
• Usar LinkedHashMap preserva a ordem de inserção, então as chaves serializadas aparecem na ordem em que foram adicionadas — útil para saída estável e amigável a diffs.

Prática