Gson — co to jest, biblioteka JSON dla Java i Kotlin

Co to jest Gson

Gson — to biblioteka Java opracowana przez Google do konwersji obiektów na reprezentację JSON i odwrotnie. Wykorzystuje refleksję do analizy struktury klas, co umożliwia pracę bez wstępnej konfiguracji. Gson obsługuje dowolne obiekty Java, kolekcje, tablice, typy generyczne i klasy zagnieżdżone. Biblioteka nie wymaga adnotacji do podstawowego użycia, ale udostępnia je do precyzyjnego dostrajania. Główną wadą refleksji jest spadek wydajności podczas inicjalizacji i brak możliwości optymalizacji na etapie kompilacji, co jest szczególnie widoczne przy zimnym starcie aplikacji Android podczas deserializacji setek modeli. Mimo to Gson pozostaje niezawodnym wyborem dla większości projektów dzięki stabilności i obszernej dokumentacji.

Historia i miejsce w ekosystemie

Gson został wydany przez Google w 2008 roku i szybko stał się standardem de facto dla JSON w aplikacjach Android. Przed pojawieniem się Moshi i kotlinx.serialization Gson pozostawał jedynym popularnym wyborem dla projektów Kotlin. Prostota podłączenia — dodanie jednej zależności w build.gradle — i brak obowiązkowych adnotacji sprawiły, że Gson stał się popularny wśród programistów na każdym poziomie zaawansowania.

// Podłączenie Gson w build.gradle
dependencies {
    implementation 'com.google.code.gson:gson:2.10.1'
}

// Podstawowe użycie
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"}

Oprócz podstawowej serializacji, Gson udostępnia GsonBuilder do konfiguracji zachowania: formatowanie dat, wyłączanie escape'owania HTML, rejestr kluczy i niestandardowe instancje. GsonBuilder umożliwia również rejestrowanie niestandardowych JsonSerializer i JsonDeserializer dla typów, których biblioteka nie może przetworzyć automatycznie. Elastyczność konfiguracji czyni GsonBuilder niezbędnym i użytecznym narzędziem podczas dostosowywania biblioteki do specyficznych wymagań projektu w nowoczesnym programowaniu Android.

Podstawowe operacje toJson i fromJson

toJson przekształca obiekt Java w ciąg JSON, analizując jego pola poprzez refleksję. Domyślnie Gson uwzględnia wszystkie pola z wyjątkiem transient i static. Metoda obsługuje dowolne typy: prymitywy, obiekty, kolekcje i tablice. fromJson wykonuje odwrotną konwersję, przyjmując ciąg JSON i klasę docelowego obiektu, i zwraca instancję z wypełnionymi polami.

Konwersja obiektu na JSON

Podczas serializacji Gson rekurencyjnie przechodzi przez wszystkie pola obiektu, w tym zagnieżdżone. Odwołania cykliczne prowadzą do StackOverflowError, dlatego należy je wykluczyć za pomocą adnotacji @Expose lub niestandardowego adaptera. Dla kolekcji Gson zachowuje typ elementów, ale przy deserializacji listy z typami generycznymi wymagany jest TypeToken do zachowania informacji o typie.

// data class z zagnieżdżonym obiektem
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"))

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

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

Adnotacje i konfiguracja

Gson udostępnia zestaw adnotacji do zarządzania procesem serializacji. @SerializedName określa nazwę klucza JSON różniącą się od nazwy pola. @Expose zarządza uwzględnianiem pola w serializacji: Gson utworzony przez GsonBuilder.excludeFieldsWithoutExposeAnnotation() będzie przetwarzać tylko pola z @Expose. @Since i @Until kontrolują wersjonowanie pól.

@SerializedName i @Expose

Adnotacja @SerializedName rozwiązuje problem niezgodności nazw: serwer może używać snake_case, a w kodzie przyjęto camelCase. Adnotacja przyjmuje wartość i opcjonalne alternatywy dla wstecznej kompatybilności. @Expose pozwala ukryć wrażliwe pola (hasła, tokeny) przed serializacją, oznaczając je jako @Expose(serialize = false). Oprócz włączania i wyłączania, @Expose można łączyć z GsonBuilder.excludeFieldsWithoutExposeAnnotation w celu utworzenia białej listy pól, co pomaga kontrolować powierzchnię ataku podczas serializacji obiektów z dużą liczbą pól.

// Model z adnotacjami 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 z filtrowaniem @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

Praca z typami generycznymi

Problem typów generycznych w Java i Kotlin polega na wymazywaniu typów podczas kompilacji. Gdy Gson deserializuje List<User>, nie zna typu elementu i zwraca List<Map<String, Any>>. Aby zachować informację o typie, Gson udostępnia TypeToken — abstrakcyjną klasę, która przechwytuje parametr typu przez anonimową klasę. Bez TypeToken programista musiałby ręcznie konwertować każdy element z Map na docelowy typ, co prowadzi do rozwlekłego kodu i utraty wydajności.

TypeToken dla list

TypeToken rozwiązuje problem wymazywania typów. Programista tworzy anonimowego potomka TypeToken z wymaganym parametrem typu, a Gson wykorzystuje informacje z sygnatury klasy do poprawnej deserializacji. TypeToken działa również z Map, Set i dowolnymi innymi typami parametryzowanymi, w tym zagnieżdżonymi typami generycznymi. W szczególności dla Map<String, List<User>> wymagany jest TypeToken z pełną sygnaturą zagnieżdżonego typu, w przeciwnym razie Gson deserializuje wartości jako List<Map<String, Any>> zamiast List<User>.

// TypeToken do deserializacji listy
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)

// Niestandardowy deserializator
class LocalDateAdapter :
    JsonDeserializer<LocalDate> {

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

Do niestandardowej logiki serializacji Gson obsługuje interfejsy JsonSerializer i JsonDeserializer. Są one rejestrowane przez GsonBuilder.registerTypeAdapter() i umożliwiają przetwarzanie typów, których biblioteka nie może serializować automatycznie: dat Java 8, Enum z niestandardowymi wartościami lub klas zewnętrznych bez dostępu do kodu źródłowego. Podczas implementacji adaptera ważne jest monitorowanie wydajności: wywołanie refleksji wewnątrz niestandardowego adaptera niweczy zalety ręcznego zarządzania, dlatego zaleca się bezpośrednie wywołania metod i pól. W ekosystemie Gson istnieje również moduł gson-extras udostępniający adaptery dla popularnych typów, takich jak UUID, Optional i typy dat Joda-Time.

Konfiguracja przez GsonBuilder

GsonBuilder udostępnia dziesiątki metod do precyzyjnej konfiguracji serializacji. setPrettyPrinting dodaje wcięcia i znaki nowej linii w wyjściowym JSON dla czytelności. disableHtmlEscaping wyłącza escape'owanie znaków HTML w ciągach. setDateFormat ustawia format dat, co jest krytyczne przy pracy z serwerami używającymi niestandardowej reprezentacji czasu. setLenient włącza luźny tryb parsowania, który ignoruje niektóre błędy formatowania JSON. addDeserializationExclusionStrategy umożliwia programowe wykluczanie pól z deserializacji na podstawie niestandardowych strategii. Do debugowania przydatna jest metoda setPrettyPrinting w połączeniu z logowaniem — sprawia, że odpowiedzi JSON są czytelne w logach i ułatwia znajdowanie niezgodności.

Ważną możliwością GsonBuilder jest zarządzanie wersjonowaniem pól za pomocą adnotacji @Since i @Until. Programista określa wersję obiektu przez setVersion, a Gson automatycznie włącza lub wyklucza pola w zależności od ich adnotacji wersji. Jest to przydatne przy ewolucji API, gdy ten sam model jest używany dla różnych wersji protokołu serwerowego. GsonBuilder obsługuje również rejestrację TypeAdapterFactory do globalnego przetwarzania rodzin typów oraz complexMapKeySerialization do poprawnej pracy ze złożonymi kluczami Map.