Gson — ce este, biblioteca JSON pentru Java și Kotlin

Ce este Gson

Gson — este o bibliotecă Java dezvoltată de Google pentru conversia obiectelor în reprezentare JSON și invers. Utilizează reflexia pentru analiza structurii claselor, permițând lucrul fără configurație prealabilă. Gson acceptă obiecte Java arbitrare, colecții, array-uri, generice și clase imbricate. Biblioteca nu necesită adnotări pentru utilizarea de bază, dar le oferă pentru reglaj fin. Principalul dezavantaj al reflexiei este scăderea performanței la inițializare și imposibilitatea optimizării în faza de compilare, ceea ce este deosebit de vizibil la pornirea la rece a aplicației Android la deserializarea a sute de modele. În ciuda acestui fapt, Gson rămâne o alegere fiabilă pentru majoritatea proiectelor datorită stabilității și documentației extinse.

Istoric și loc în ecosistem

Gson a fost lansat de Google în 2008 și a devenit rapid standardul de facto pentru JSON în aplicațiile Android. Înainte de apariția Moshi și kotlinx.serialization, Gson rămânea singura alegere populară pentru proiectele Kotlin. Simplitatea conectării — adăugarea unei singure dependențe în build.gradle — și absența adnotărilor obligatorii au făcut Gson popular printre dezvoltatorii de orice nivel.

// Adăugarea Gson în build.gradle
dependencies {
    implementation 'com.google.code.gson:gson:2.10.1'
}

// Utilizare de bază
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"}

Pe lângă serializarea de bază, Gson oferă GsonBuilder pentru configurarea comportamentului: formatarea datelor, dezactivarea escapării HTML, registrul cheilor și instanțe personalizate. GsonBuilder permite, de asemenea, înregistrarea de JsonSerializer și JsonDeserializer personalizate pentru tipuri pe care biblioteca nu le poate procesa automat. Flexibilitatea configurației face GsonBuilder un instrument indispensabil și util la adaptarea bibliotecii la cerințele specifice ale proiectului în dezvoltarea modernă Android.

Operațiile de bază toJson și fromJson

toJson convertește un obiect Java într-un șir JSON, analizându-i câmpurile prin reflexie. În mod implicit, Gson include toate câmpurile, cu excepția transient și static. Metoda acceptă orice tipuri: primitive, obiecte, colecții și array-uri. fromJson efectuează conversia inversă, primind un șir JSON și clasa obiectului țintă, și returnează o instanță cu câmpurile populate.

Conversia obiectului în JSON

La serializare, Gson parcurge recursiv toate câmpurile obiectului, inclusiv pe cele imbricate. Referințele ciclice duc la StackOverflowError, de aceea trebuie excluse prin adnotarea @Expose sau un adaptor personalizat. Pentru colecții, Gson păstrează tipul elementelor, dar la deserializarea listelor cu generice este necesar TypeToken pentru păstrarea informației despre tip.

// data class cu obiect imbricat
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"))

// Serializare în JSON
val json = gson.toJson(employee)

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

Adnotări și configurare

Gson oferă un set de adnotări pentru gestionarea procesului de serializare. @SerializedName specifică numele cheii JSON diferit de numele câmpului. @Expose gestionează includerea câmpului în serializare: Gson creat prin GsonBuilder.excludeFieldsWithoutExposeAnnotation() va procesa doar câmpurile cu @Expose. @Since și @Until controlează versionarea câmpurilor.

@SerializedName și @Expose

Adnotarea @SerializedName rezolvă problema nepotrivirii numelor: serverul poate folosi snake_case, iar în cod este adoptat camelCase. Adnotarea acceptă o valoare și alternative opționale pentru compatibilitate inversă. @Expose permite ascunderea câmpurilor sensibile (parole, token-uri) de la serializare, marcându-le ca @Expose(serialize = false). Pe lângă includerea și excluderea, @Expose poate fi combinat cu GsonBuilder.excludeFieldsWithoutExposeAnnotation pentru a crea o listă albă de câmpuri, ceea ce ajută la controlul suprafeței de atac la serializarea obiectelor cu un număr mare de câmpuri.

// Model cu adnotări 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 cu filtrare @Expose
val gson = GsonBuilder()
    .excludeFieldsWithoutExposeAnnotation()
    .setPrettyPrinting()
    .create()

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

Lucrul cu generice

Problema genericelor în Java și Kotlin constă în ștergerea tipurilor în timpul compilării. Când Gson deserializă List<User>, nu cunoaște tipul elementului și returnează List<Map<String, Any>>. Pentru a păstra informația despre tip, Gson oferă TypeToken — o clasă abstractă care capturează parametrul de tip printr-o clasă anonimă. Fără TypeToken, dezvoltatorul ar trebui să convertească manual fiecare element din Map în tipul țintă, ceea ce duce la cod voluminos și pierdere de performanță.

TypeToken pentru liste

TypeToken rezolvă problema ștergerii tipurilor. Dezvoltatorul creează un moștenitor anonim al TypeToken cu parametrul de tip necesar, iar Gson utilizează informația din semnătura clasei pentru deserializarea corectă. TypeToken funcționează și cu Map, Set și orice alte tipuri parametrizate, inclusiv generice imbricate. În special, pentru Map<String, List<User>> este necesar TypeToken cu semnătura completă a tipului imbricat, altfel Gson deserializă valorile ca List<Map<String, Any>> în loc de List<User>.

// TypeToken pentru deserializarea listei
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)

// Deserializator personalizat
class LocalDateAdapter :
    JsonDeserializer<LocalDate> {

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

Pentru logica personalizată de serializare, Gson acceptă interfețele JsonSerializer și JsonDeserializer. Acestea se înregistrează prin GsonBuilder.registerTypeAdapter() și permit procesarea tipurilor pe care biblioteca nu le poate serializa automat: date Java 8, Enum cu valori nestandard sau clase terțe fără acces la codul sursă. La implementarea adaptorului, este important să se monitorizeze performanța: apelul reflexiei în interiorul adaptorului personalizat anulează avantajele gestionării manuale, de aceea se preferă apelurile directe ale metodelor și câmpurilor. În ecosistemul Gson există și modulul gson-extras care oferă adaptoare pentru tipuri comune precum UUID, Optional și tipurile de date Joda-Time.

Configurare prin GsonBuilder

GsonBuilder oferă zeci de metode pentru configurarea fină a serializării. setPrettyPrinting adaugă indentări și linii noi în JSON-ul de ieșire pentru lizibilitate. disableHtmlEscaping dezactivează escaparea caracterelor HTML în șiruri. setDateFormat stabilește formatul datelor, ceea ce este critic la lucrul cu servere care folosesc reprezentări nestandard ale timpului. setLenient activează modul de parsare permisiv care ignoră unele erori de formatare JSON. addDeserializationExclusionStrategy permite excluderea programatică a câmpurilor din deserializare pe baza strategiilor personalizate. Pentru depanare, metoda setPrettyPrinting este utilă în combinație cu logarea — face răspunsurile JSON lizibile în loguri și simplifică găsirea neconcordanțelor.

O capacitate importantă a GsonBuilder este gestionarea versionării câmpurilor prin adnotările @Since și @Until. Dezvoltatorul specifică versiunea obiectului prin setVersion, iar Gson include sau exclude automat câmpurile în funcție de adnotarea lor de versiune. Acest lucru este util la evoluția API, când același model este utilizat pentru diferite versiuni ale protocolului serverului. GsonBuilder acceptă, de asemenea, înregistrarea TypeAdapterFactory pentru procesarea globală a familiilor de tipuri și complexMapKeySerialization pentru lucrul corect cu chei Map complexe.