Gson — ano ito, library ng JSON para sa Java at Kotlin

Ano ang Gson

Gson — ay isang Java library na binuo ng Google para sa pag-convert ng mga object sa JSON representation at pabalik. Gumagamit ito ng reflection para suriin ang istraktura ng mga klase, na nagpapahintulot sa pagtatrabaho nang walang paunang configuration. Sinusuportahan ng Gson ang mga arbitraryong Java object, koleksyon, array, generics, at nested na klase. Hindi nangangailangan ng mga annotation ang library para sa pangunahing paggamit, ngunit nagbibigay ng mga ito para sa fine-tuning. Ang pangunahing disadvantage ng reflection ay ang pagbaba ng performance sa initialization at ang kawalan ng kakayahang mag-optimize sa compilation stage, na lalong kapansin-pansin sa malamig na pagsisimula ng Android application kapag nagde-deserialize ng daan-daang modelo. Sa kabila nito, nananatiling maaasahang pagpipilian ang Gson para sa karamihan ng mga proyekto dahil sa katatagan at malawak na dokumentasyon.

Kasaysayan at lugar sa ekosistema

Ang Gson ay inilabas ng Google noong 2008 at mabilis na naging de facto na pamantayan para sa JSON sa mga Android application. Bago ang pagdating ng Moshi at kotlinx.serialization, ang Gson ay nanatiling tanging sikat na pagpipilian para sa mga proyekto ng Kotlin. Ang pagiging simple ng koneksyon — pagdagdag ng isang dependency sa build.gradle — at ang kawalan ng mga mandatoryong annotation ay ginawang popular ang Gson sa mga developer sa lahat ng antas.

// Pagdagdag ng Gson sa build.gradle
dependencies {
    implementation 'com.google.code.gson:gson:2.10.1'
}

// Pangunahing paggamit
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"}

Bukod sa pangunahing serialization, nagbibigay ang Gson ng GsonBuilder para sa pag-configure ng pag-uugali: pag-format ng mga petsa, pag-disable ng HTML escaping, rehistro ng key, at mga custom na instance. Pinapayagan din ng GsonBuilder ang pagrehistro ng mga custom na JsonSerializer at JsonDeserializer para sa mga uri na hindi kayang iproseso ng library nang awtomatiko. Ang flexibility ng configuration ay ginagawang kailangang-kailangan at kapaki-pakinabang na tool ang GsonBuilder sa pag-angkop ng library sa mga tiyak na pangangailangan ng proyekto sa modernong pag-develop ng Android.

Mga pangunahing operasyon toJson at fromJson

toJson nagko-convert ng Java object sa JSON string, sinusuri ang mga field nito sa pamamagitan ng reflection. Bilang default, kasama ng Gson ang lahat ng field maliban sa transient at static. Ang pamamaraan ay sumusuporta sa lahat ng uri: primitives, object, koleksyon, at array. fromJson gumaganap ng reverse conversion, tumatanggap ng JSON string at klase ng target na object, at nagbabalik ng instance na may napunong mga field.

Pag-convert ng object sa JSON

Sa serialization, recursive na tinatahak ng Gson ang lahat ng field ng object, kabilang ang mga nested. Ang mga cyclic na referens ay humahantong sa StackOverflowError, kaya dapat silang ibukod sa pamamagitan ng @Expose annotation o custom na adapter. Para sa mga koleksyon, pinapanatili ng Gson ang uri ng mga elemento, ngunit sa deserialization ng listahan na may mga generics, kinakailangan ang TypeToken upang mapanatili ang impormasyon tungkol sa uri.

// data class na may nested na object
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"))

// Serialization sa JSON
val json = gson.toJson(employee)

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

Mga annotation at configuration

Gson nagbibigay ng set ng mga annotation para sa pamamahala ng proseso ng serialization. @SerializedName tumutukoy ng pangalan ng JSON key na naiiba sa pangalan ng field. @Expose namamahala ng pagsasama ng field sa serialization: Gson na nilikha sa pamamagitan ng GsonBuilder.excludeFieldsWithoutExposeAnnotation() ay magpoproseso lamang ng mga field na may @Expose. @Since at @Until kumokontrol sa pag-version ng field.

@SerializedName at @Expose

Ang annotation na @SerializedName ay lumulutas ng problema ng hindi pagkakatugma ng pangalan: ang server ay maaaring gumamit ng snake_case, habang sa code ay ginagamit ang camelCase. Ang annotation ay tumatanggap ng halaga at opsyonal na mga alternatibo para sa backward compatibility. @Expose ay nagpapahintulot na itago ang mga sensitibong field (password, token) mula sa serialization sa pamamagitan ng pagmamarka sa kanila bilang @Expose(serialize = false). Bukod sa pagsasama at pagbubukod, ang @Expose ay maaaring pagsamahin sa GsonBuilder.excludeFieldsWithoutExposeAnnotation upang lumikha ng puting listahan ng mga field, na tumutulong sa pagkontrol sa attack surface sa serialization ng mga object na may maraming field.

// Model na may mga annotation ng 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 na may @Expose na filter
val gson = GsonBuilder()
    .excludeFieldsWithoutExposeAnnotation()
    .setPrettyPrinting()
    .create()

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

Pagtatrabaho sa mga generics

Ang problema ng generics sa Java at Kotlin ay nakasalalay sa pagbura ng mga uri sa panahon ng compilation. Kapag nagde-deserialize ang Gson ng List<User>, hindi nito alam ang uri ng elemento at nagbabalik ng List<Map<String, Any>>. Upang mapanatili ang impormasyon tungkol sa uri, nagbibigay ang Gson ng TypeToken — isang abstract na klase na kumukuha ng parameter ng uri sa pamamagitan ng isang anonymous na klase. Kung walang TypeToken, kailangang manu-manong i-convert ng developer ang bawat elemento mula sa Map patungo sa target na uri, na humahantong sa masalimuot na code at pagkawala ng performance.

TypeToken para sa mga listahan

TypeToken lumulutas ng problema ng pagbura ng uri. Gumagawa ang developer ng anonymous na tagapagmana ng TypeToken na may kinakailangang parameter ng uri, at ginagamit ng Gson ang impormasyon mula sa lagda ng klase para sa tamang deserialization. Gumagana rin ang TypeToken sa Map, Set at anumang iba pang parameterized na uri, kabilang ang mga nested na generics. Sa partikular, para sa Map<String, List<User>>, kinakailangan ang TypeToken na may kumpletong lagda ng nested na uri, kung hindi ay ideserialize ng Gson ang mga halaga bilang List<Map<String, Any>> sa halip na List<User>.

// TypeToken para sa deserialization ng listahan
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)

// Custom na deserializator
class LocalDateAdapter :
    JsonDeserializer<LocalDate> {

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

Para sa custom na lohika ng serialization, sinusuportahan ng Gson ang mga interface na JsonSerializer at JsonDeserializer. Ang mga ito ay nirerehistro sa pamamagitan ng GsonBuilder.registerTypeAdapter() at pinapayagan ang pagproseso ng mga uri na hindi awtomatikong ma-serialize ng library: Java 8 dates, Enum na may hindi karaniwang halaga, o third-party na klase na walang access sa source code. Sa pagpapatupad ng adapter, mahalagang subaybayan ang performance: ang pagtawag ng reflection sa loob ng custom na adapter ay nagpapawalang-bisa sa mga bentahe ng manual na pamamahala, kaya mas gusto ang direktang pagtawag ng mga pamamaraan at field. Sa ekosistema ng Gson, mayroon ding module na gson-extras na nagbibigay ng mga adapter para sa mga karaniwang uri tulad ng UUID, Optional, at mga uri ng petsa ng Joda-Time.

Configuration sa pamamagitan ng GsonBuilder

Ang GsonBuilder ay nagbibigay ng dose-dosenang mga pamamaraan para sa fine-tuning ng serialization. setPrettyPrinting nagdadagdag ng indentation at mga bagong linya sa output JSON para sa pagiging madaling mabasa. disableHtmlEscaping nagdi-disable ng pag-escape ng mga HTML character sa mga string. setDateFormat nagtatakda ng format ng petsa, na kritikal sa pagtatrabaho sa mga server na gumagamit ng hindi karaniwang representasyon ng oras. setLenient nag-a-activate ng maluwag na parsing mode na hindi pinapansin ang ilang error sa pag-format ng JSON. addDeserializationExclusionStrategy nagpapahintulot ng programmatic na pagbubukod ng mga field mula sa deserialization batay sa mga custom na strategy. Para sa debugging, ang pamamaraang setPrettyPrinting ay kapaki-pakinabang kasama ng logging — ginagawang nababasa ang mga JSON response sa log at pinapasimple ang paghahanap ng mga hindi pagkakatugma.

Isang mahalagang kakayahan ng GsonBuilder ay ang pamamahala ng pag-version ng field sa pamamagitan ng @Since at @Until annotation. Tinutukoy ng developer ang bersyon ng object sa pamamagitan ng setVersion, at awtomatikong isasama o ibubukod ng Gson ang mga field depende sa kanilang version annotation. Ito ay kapaki-pakinabang sa ebolusyon ng API, kapag ang parehong modelo ay ginagamit para sa iba't ibang bersyon ng server protocol. Sinusuportahan din ng GsonBuilder ang pagrehistro ng TypeAdapterFactory para sa global na pagproseso ng mga pamilya ng uri at complexMapKeySerialization para sa tamang pagtatrabaho sa mga kumplikadong key ng Map.