Gson — cos'è, libreria JSON per Java e Kotlin

Cos'è Gson

Gson è una libreria Java sviluppata da Google per convertire oggetti in rappresentazione JSON e viceversa. Utilizza la riflessione per analizzare la struttura delle classi, consentendo di lavorare senza configurazione preliminare. Gson supporta oggetti Java arbitrari, collezioni, array, generics e classi annidate. La libreria non richiede annotazioni per l'uso di base, ma le fornisce per la regolazione fine. Il principale svantaggio della riflessione è la riduzione delle prestazioni durante l'inizializzazione e l'impossibilità di ottimizzare in fase di compilazione, particolarmente evidente all'avvio a freddo di un'applicazione Android durante la deserializzazione di centinaia di modelli. Nonostante ciò, Gson rimane una scelta affidabile per la maggior parte dei progetti grazie alla sua stabilità e alla documentazione estesa.

Storia e posizione nell'ecosistema

Gson è stato rilasciato da Google nel 2008 ed è diventato rapidamente lo standard de facto per JSON nelle applicazioni Android. Prima dell'arrivo di Moshi e kotlinx.serialization, Gson era l'unica scelta popolare per i progetti Kotlin. Facilità di integrazione — aggiungere una singola dipendenza a build.gradle — e l'assenza di annotazioni obbligatorie hanno reso Gson popolare tra sviluppatori di tutti i livelli.

// Aggiungere Gson in build.gradle
dependencies {
    implementation 'com.google.code.gson:gson:2.10.1'
}

// Utilizzo di base
data class User(
    val id: Int,
    val name: String,
    val email: String
)

val gson = Gson()
val user = User(1, "John", "john@test.com")
val json = gson.toJson(user)
println(json) // {"id":1,"name":"John","email":"john@test.com"}

Oltre alla serializzazione di base, Gson fornisce GsonBuilder per configurare il comportamento: formattazione delle date, disattivazione dell'escape HTML, formato delle chiavi e istanze personalizzate. GsonBuilder consente anche di registrare JsonSerializer e JsonDeserializer personalizzati per tipi che la libreria non può gestire automaticamente. La flessibilità di configurazione rende GsonBuilder uno strumento indispensabile e utile quando si adatta la libreria ai requisiti specifici del progetto nello sviluppo Android moderno.

Operazioni principali toJson e fromJson

toJson converte un oggetto Java in una stringa JSON analizzando i suoi campi tramite riflessione. Per impostazione predefinita, Gson include tutti i campi tranne transient e static. Il metodo supporta qualsiasi tipo: primitivi, oggetti, collezioni e array. fromJson esegue l'operazione inversa, accettando una stringa JSON e la classe dell'oggetto di destinazione, e restituisce un'istanza con i campi popolati.

Convertire un oggetto in JSON

Durante la serializzazione, Gson attraversa ricorsivamente tutti i campi dell'oggetto, inclusi quelli annidati. I riferimenti ciclici portano a StackOverflowError, quindi devono essere esclusi tramite l'annotazione @Expose o un adattatore personalizzato. Per le collezioni, Gson preserva i tipi degli elementi, ma quando si deserializza una lista con generics, è necessario TypeToken per preservare le informazioni sul tipo.

// data class con oggetto annidato
data class Address(
    val city: String,
    val street: String
)

data class Employee(
    val id: Int,
    val name: String,
    val address: Address
)

val gson = Gson()
val employee = Employee(1, "Alice",
    Address("New York", "5th Ave"))

// Serializzazione in JSON
val json = gson.toJson(employee)

// Deserializzazione da JSON
val jsonString = """
{"id":2,"name":"Bob","address":{"city":"London","street":"Baker St"}}
"""
val parsed = gson.fromJson(jsonString, Employee::class.java)

Annotazioni e configurazione

Gson fornisce un insieme di annotazioni per gestire il processo di serializzazione. @SerializedName specifica il nome della chiave JSON che differisce dal nome del campo. @Expose controlla se un campo è incluso nella serializzazione: Gson creato tramite GsonBuilder.excludeFieldsWithoutExposeAnnotation() elaborerà solo i campi con @Expose. @Since e @Until controllano il versionamento dei campi.

@SerializedName e @Expose

L'annotazione @SerializedName risolve il problema di disallineamento dei nomi: il server può utilizzare snake_case mentre nel codice viene utilizzato camelCase. L'annotazione accetta un valore e alternative opzionali per la retrocompatibilità. @Expose consente di nascondere campi sensibili (password, token) dalla serializzazione contrassegnandoli come @Expose(serialize = false). Oltre all'inclusione e all'esclusione, @Expose può essere combinato con GsonBuilder.excludeFieldsWithoutExposeAnnotation per creare una whitelist di campi, il che aiuta a controllare la superficie di attacco durante la serializzazione di oggetti con molti campi.

// Modello con annotazioni Gson
data class UserResponse(
    @SerializedName("user_id")
    val userId: Int,

    @SerializedName("full_name",
        alternate = [Alternative("name")])
    val fullName: String,

    @Expose(serialize = false)
    val password: String
)

// Gson con filtro @Expose
val gson = GsonBuilder()
    .excludeFieldsWithoutExposeAnnotation()
    .setPrettyPrinting()
    .create()

val user = UserResponse(1, "John", "secret123")
println(gson.toJson(user))
// {"user_id":1,"full_name":"John"} — password esclusa

Lavorare con i generics

Il problema dei generics in Java e Kotlin è la cancellazione del tipo in fase di compilazione. Quando Gson deserializza List<User>, non conosce il tipo dell'elemento e restituisce List<Map<String, Any>>. Per preservare le informazioni sul tipo, Gson fornisce TypeToken — una classe astratta che cattura il parametro di tipo tramite una classe anonima. Senza TypeToken, lo sviluppatore dovrebbe convertire manualmente ogni elemento da Map al tipo di destinazione, risultando in codice complesso e perdita di prestazioni.

TypeToken per le liste

TypeToken risolve il problema della cancellazione del tipo. Lo sviluppatore crea una sottoclasse anonima di TypeToken con il parametro di tipo richiesto, e Gson utilizza le informazioni dalla firma della classe per una deserializzazione corretta. TypeToken funziona anche con Map, Set e qualsiasi altro tipo parametrizzato, inclusi i generics annidati. In particolare, per Map<String, List<User>>, è necessario un TypeToken con la firma completa del tipo annidato, altrimenti Gson deserializza i valori come List<Map<String, Any>> invece di List<User>.

// TypeToken per deserializzazione di liste
data class Product(
    val id: Int,
    val title: String,
    val price: Double
)

val jsonArray = """
[
    {"id":1,"title":"Phone","price":599.0},
    {"id":2,"title":"Laptop","price":1299.0}
]
"""

val gson = Gson()
val listType = object : TypeToken<List<Product>>() {}
val products: List<Product> =
    gson.fromJson(jsonArray, listType.type)

// Deserializzatore personalizzato
class LocalDateAdapter :
    JsonDeserializer<LocalDate> {

    override fun deserialize(
        json: JsonElement,
        typeOfT: java.lang.reflect.Type,
        context: JsonDeserializationContext
    ): LocalDate {
        return LocalDate.parse(json.asString)
    }
}

Per la logica di serializzazione personalizzata, Gson supporta le interfacce JsonSerializer e JsonDeserializer. Vengono registrate tramite GsonBuilder.registerTypeAdapter() e consentono di gestire tipi che la libreria non può serializzare automaticamente: date Java 8, Enum con valori non standard o classi di terze parti senza accesso al codice sorgente. Quando si implementa un adattatore, è importante monitorare le prestazioni: chiamare la riflessione all'interno di un adattatore personalizzato annulla i vantaggi del controllo manuale, quindi sono preferibili chiamate dirette a metodi e campi. Nell'ecosistema Gson, esiste anche il modulo gson-extras che fornisce adattatori per tipi comuni come UUID, Optional e ruote di data Joda-Time.

Configurazione tramite GsonBuilder

GsonBuilder fornisce decine di metodi per la regolazione fine della serializzazione. setPrettyPrinting aggiunge indentazione e interruzioni di riga al JSON di output per la leggibilità. disableHtmlEscaping disattiva l'escape dei caratteri HTML nelle stringhe. setDateFormat specifica il formato della data, che è fondamentale quando si lavora con server che utilizzano rappresentazioni temporali non standard. setLenient attiva la modalità di parsing permissiva, che ignora alcuni errori di formattazione JSON. addDeserializationExclusionStrategy consente di escludere programmaticamente campi dalla deserializzazione basandosi su strategie personalizzate. Per il debug, setPrettyPrinting combinato con la registrazione è utile — rende le risposte JSON leggibili nei log e semplifica la ricerca di incongruenze.

Una caratteristica importante di GsonBuilder è la gestione del versionamento dei campi tramite le annotazioni @Since e @Until. Lo sviluppatore specifica la versione dell'oggetto tramite setVersion e Gson include o esclude automaticamente i campi in base alla loro annotazione di versione. Ciò è utile durante l'evoluzione dell'API, quando lo stesso modello viene utilizzato per diverse versioni del protocollo server. GsonBuilder supporta anche la registrazione di TypeAdapterFactory per la gestione globale dei tipi di famiglia e complexMapKeySerialization per il corretto funzionamento con chiavi Map complesse.