Introduzione a JSON in Java

JSON (JavaScript Object Notation) è il formato più comune per lo scambio di dati sul web. Le API lo restituiscono, i file di configurazione lo usano e i servizi lo passano tra loro. Java non include il supporto JSON nel JDK di base, quindi lavorare con JSON significa scegliere una libreria — ma i concetti di parsing, mapping e serializzazione rimangono gli stessi indipendentemente da quella che si sceglie.

Questa pagina è la mappa per la sezione JSON: spiega cos'è JSON, come i suoi tipi si allineano con i tipi Java, quali librerie esistono e i due modelli di parsing. I capitoli successivi approfondiscono le due librerie più popolari — JSON con Jackson e JSON con Gson.

Cos'è JSON

JSON è un formato leggero, basato su testo, per dati strutturati. È costruito su pochi tipi semplici: stringhe, numeri, booleani, null, array (liste ordinate) e oggetti (mappe chiave/valore). Poiché è testo normale, qualsiasi linguaggio può leggerlo e scriverlo, il che lo ha reso la lingua franca delle API web.

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

Il formato si mappa in modo pulito sui tipi dei linguaggi di programmazione. In Java, un oggetto JSON diventa una Map o una classe personalizzata, un array diventa una List o un array, e i tipi scalari diventano String, Number, Boolean e null.

Perché JSON è importante

JSON è il payload predefinito per le API REST, e i programmi Java lo inviano e ricevono continuamente: un servizio web legge il corpo di una richiesta JSON, interroga un database e scrive una risposta JSON. È anche leggibile dall'uomo, quindi funge anche da formato di configurazione e di logging.

Rispetto a XML — il formato di interscambio più vecchio che JSON ha in gran parte sostituito — JSON è più conciso, ha meno cerimonia e si mappa più direttamente sulle strutture dati dei linguaggi. XML rimane superiore quando si hanno bisogno di schemi, namespace o contenuto misto, ma per il semplice scambio di dati JSON è di solito la scelta più leggera.

Le principali librerie Java

Il JDK non include un parser JSON, quindi bisogna aggiungerne uno. Tre librerie dominano il panorama:

Jackson è il più utilizzato. La sua classe centrale è ObjectMapper, che converte tra testo JSON e oggetti Java in una singola chiamata:

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 la stessa struttura con nomi diversi:

import com.google.gson.Gson;

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

Aggiungere la libreria come dipendenza prima di usarla — per Jackson si tratta di com.fasterxml.jackson.core:jackson-databind; per Gson, com.google.code.gson:gson.

Quale scegliere? Se si usa Spring Boot, Jackson è già presente e configurato, quindi conviene usarlo. Per un piccolo strumento standalone o un'app Android dove le dimensioni del binario contano, la piccola API senza configurazione di Gson è conveniente. Si ricorre a JSON-B solo quando si è vincolati allo stack Jakarta EE e si vuole lo standard vendor-neutral. In pratica la scelta raramente influisce sulla correttezza — tutte e tre leggono e scrivono lo stesso JSON — quindi si preferisce quella già nel classpath.

Due modi per fare il parsing: Tree vs Binding

Qualunque libreria si scelga, esistono due modelli principali per leggere JSON:

• Il data binding mappa JSON direttamente sulle classi Java. Si definisce una classe (o un record) i cui campi corrispondono alle chiavi, e la libreria la riempie. Questo è l'approccio più pulito quando la struttura è nota e stabile.
• Il modello tree / map analizza JSON in un albero generico di nodi (JsonNode in Jackson) o una Map<String, Object>. Si naviga per chiave. Va usato quando la struttura è dinamica o si hanno bisogno solo di alcuni campi.

// 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());

Il binding offre sicurezza dei tipi e codice leggibile; il modello tree offre flessibilità. La maggior parte delle applicazioni usa il binding per i propri oggetti di dominio e ricorre al modello tree solo per dati con struttura variabile.

Un esempio eseguibile

La sandbox non ha Jackson o Gson nel classpath, quindi il programma seguente usa solo le collezioni JDK per dimostrare la stessa idea: un oggetto JSON analizzato è semplicemente chiavi mappate a valori tipizzati, un array è una List, e la serializzazione trasforma quella struttura in testo JSON. Gli esempi statici sopra mostrano la vera API della libreria che si userà in un progetto.

Cosa ricavare dall'esecuzione:

• Un oggetto JSON analizzato si comporta come una Map: si recupera ogni campo tramite la sua chiave, esattamente come farebbe mapper.readTree(...).get("name") in Jackson.
• I valori JSON mantengono il loro tipo — age viene restituito come Number e admin come Boolean, non come testo grezzo, ecco perché age instanceof Number stampa true.
• Un array JSON si mappa su una List, quindi roles è iterabile e riporta una dimensione di 2.
• La serializzazione è l'inverso del parsing: percorrere la stessa struttura ricostruisce il testo JSON compatto {"name":"Ann",...}.
• Usare LinkedHashMap preserva l'ordine di inserimento, quindi le chiavi serializzate appaiono nell'ordine in cui sono state aggiunte — utile per un output stabile e facile da confrontare con diff.

Esercitazione