Gson — co to je, JSON knihovna pro Java a Kotlin

Co je Gson

Gson — je Java knihovna vyvinutá Googlem pro převod objektů do JSON reprezentace a zpět. Používá reflexi k analýze struktury tříd, což umožňuje práci bez předchozí konfigurace. Gson podporuje libovolné Java objekty, kolekce, pole, generiky a vnořené třídy. Knihovna nevyžaduje anotace pro základní použití, ale poskytuje je pro jemné doladění. Hlavní nevýhodou reflexe je snížení výkonu při inicializaci a nemožnost optimalizace ve fázi kompilace, což je zvláště patrné při studeném startu Android aplikace při deserializaci stovek modelů. Navzdory tomu Gson zůstává spolehlivou volbou pro většinu projektů díky stabilitě a rozsáhlé dokumentaci.

Historie a místo v ekosystému

Gson byl vydán Googlem v roce 2008 a rychle se stal de facto standardem pro JSON v Android aplikacích. Před příchodem Moshi a kotlinx.serialization zůstával Gson jedinou populární volbou pro Kotlin projekty. Jednoduchost připojení — přidání jedné závislosti v build.gradle — a absence povinných anotací učinily Gson populárním mezi vývojáři všech úrovní.

// Přidání Gson do build.gradle
dependencies {
    implementation 'com.google.code.gson:gson:2.10.1'
}

// Základní použití
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"}

Kromě základní serializace poskytuje Gson GsonBuilder pro konfiguraci chování: formátování dat, vypnutí HTML escapování, registr klíčů a vlastní instance. GsonBuilder také umožňuje registrovat vlastní JsonSerializer a JsonDeserializer pro typy, které knihovna nemůže zpracovat automaticky. Flexibilita konfigurace činí GsonBuilder nepostradatelným a užitečným nástrojem při přizpůsobování knihovny specifickým požadavkům projektu v moderním vývoji pro Android.

Základní operace toJson a fromJson

toJson převádí Java objekt na JSON řetězec, analyzuje jeho pole pomocí reflexe. Ve výchozím nastavení Gson zahrnuje všechna pole kromě transient a static. Metoda podporuje všechny typy: primitivy, objekty, kolekce a pole. fromJson provádí opačný převod, přijímá JSON řetězec a třídu cílového objektu a vrací instanci s vyplněnými poli.

Převod objektu na JSON

Při serializaci Gson rekurzivně prochází všechna pole objektu, včetně vnořených. Cyklické reference vedou k StackOverflowError, proto je nutné je vyloučit pomocí anotace @Expose nebo vlastního adaptéru. Pro kolekce Gson zachovává typ prvků, ale při deserializaci seznamu s generikami je vyžadován TypeToken pro zachování informace o typu.

// data class s vnořeným objektem
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"))

// Serializace do JSON
val json = gson.toJson(employee)

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

Anotace a konfigurace

Gson poskytuje sadu anotací pro řízení procesu serializace. @SerializedName určuje název JSON klíče odlišný od názvu pole. @Expose řídí zahrnutí pole do serializace: Gson vytvořený přes GsonBuilder.excludeFieldsWithoutExposeAnnotation() bude zpracovávat pouze pole s @Expose. @Since a @Until řídí verzování polí.

@SerializedName a @Expose

Anotace @SerializedName řeší problém nesouladu názvů: server může používat snake_case, zatímco v kódu je přijat camelCase. Anotace přijímá hodnotu a volitelné alternativy pro zpětnou kompatibilitu. @Expose umožňuje skrýt citlivá pole (hesla, tokeny) před serializací označením jako @Expose(serialize = false). Kromě zahrnutí a vyloučení lze @Expose kombinovat s GsonBuilder.excludeFieldsWithoutExposeAnnotation pro vytvoření bílé listiny polí, což pomáhá řídit útočnou plochu při serializaci objektů s velkým počtem polí.

// Model s anotacemi 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 s filtrováním @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

Práce s generikami

Problém generik v Java a Kotlin spočívá v mazání typů během kompilace. Když Gson deserializuje List<User>, nezná typ prvku a vrací List<Map<String, Any>>. Pro zachování informace o typu poskytuje Gson TypeToken — abstraktní třídu, která zachycuje parametr typu prostřednictvím anonymní třídy. Bez TypeToken by vývojář musel ručně převádět každý prvek z Map do cílového typu, což vede k rozsáhlému kódu a ztrátě výkonu.

TypeToken pro seznamy

TypeToken řeší problém mazání typů. Vývojář vytvoří anonymního potomka TypeToken s požadovaným parametrem typu a Gson použije informaci z podpisu třídy pro správnou deserializaci. TypeToken také funguje s Map, Set a jakýmikoli jinými parametrizovanými typy, včetně vnořených generik. Konkrétně pro Map<String, List<User>> je vyžadován TypeToken s úplným podpisem vnořeného typu, jinak Gson deserializuje hodnoty jako List<Map<String, Any>> místo List<User>.

// TypeToken pro deserializaci seznamu
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)

// Vlastní deserializátor
class LocalDateAdapter :
    JsonDeserializer<LocalDate> {

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

Pro vlastní logiku serializace Gson podporuje rozhraní JsonSerializer a JsonDeserializer. Registrují se přes GsonBuilder.registerTypeAdapter() a umožňují zpracování typů, které knihovna nemůže automaticky serializovat: data Java 8, Enum s nestandardními hodnotami nebo třídy třetích stran bez přístupu ke zdrojovému kódu. Při implementaci adaptéru je důležité sledovat výkon: volání reflexe uvnitř vlastního adaptéru ruší výhody ručního řízení, proto se preferují přímá volání metod a polí. V ekosystému Gson existuje také modul gson-extras poskytující adaptéry pro běžné typy jako UUID, Optional a datové typy Joda-Time.

Konfigurace pomocí GsonBuilder

GsonBuilder poskytuje desítky metod pro jemné doladění serializace. setPrettyPrinting přidává odsazení a nové řádky do výstupního JSON pro čitelnost. disableHtmlEscaping vypíná escapování HTML znaků v řetězcích. setDateFormat nastavuje formát data, což je kritické při práci se servery používajícími nestandardní reprezentaci času. setLenient zapíná volný režim parsování, který ignoruje některé chyby formátování JSON. addDeserializationExclusionStrategy umožňuje programové vyloučení polí z deserializace na základě vlastních strategií. Pro ladění je metoda setPrettyPrinting užitečná v kombinaci s logováním — dělá JSON odpovědi čitelné v logech a zjednodušuje hledání nesrovnalostí.

Důležitou schopností GsonBuilder je řízení verzování polí pomocí anotací @Since a @Until. Vývojář určuje verzi objektu pomocí setVersion a Gson automaticky zahrnuje nebo vylučuje pole v závislosti na jejich verzi anotace. To je užitečné při evoluci API, kdy je stejný model používán pro různé verze serverového protokolu. GsonBuilder také podporuje registraci TypeAdapterFactory pro globální zpracování rodin typů a complexMapKeySerialization pro správnou práci s komplexními klíči Map.