Gson — bu nədir, Java və Kotlin üçün JSON kitabxanası

Gson nədir

Gson — Google tərəfindən hazırlanmış, obyektləri JSON təsvirinə və geriyə çevirmək üçün Java kitabxanasıdır. O, siniflərin strukturunu təhlil etmək üçün refleksiyadan istifadə edir ki, bu da ilkin konfiqurasiya olmadan işləməyə imkan verir. Gson ixtiyari Java obyektlərini, kolleksiyaları, massivləri, generikləri və iç-içə sinifləri dəstəkləyir. Kitabxana əsas istifadə üçün annotasiya tələb etmir, lakin incə sazlama üçün onları təqdim edir. Refleksiyanın əsas çatışmazlığı — işəsalma zamanı performansın azalması və kompilasiya mərhələsində optimallaşdırmanın mümkünsüzlüyüdür, bu xüsusilə Android tətbiqinin soyuq başlanğıcında yüzlərlə modelin deserializasiyası zamanı nəzərə çarpır. Buna baxmayaraq, Gson sabitliyi və geniş sənədləşməsi sayəsində əksər layihələr üçün etibarlı seçim olaraq qalır.

Ekosisitemdə tarix və yer

Gson Google tərəfindən 2008-ci ildə buraxıldı və tez bir zamanda Android tətbiqlərində JSON üçün de-fakto standarta çevrildi. Moshi və kotlinx.serialization meydana çıxmazdan əvvəl Gson Kotlin layihələri üçün yeganə populyar seçim olaraq qalırdı. Qoşulmanın sadəliyi — build.gradle-a bir asılılıq əlavə etmək — və məcburi annotasiyaların olmaması Gson-u istənilən səviyyəli tərtibatçılar arasında populyar etdi.

// Gson-u build.gradle-a əlavə etmək
dependencies {
    implementation 'com.google.code.gson:gson:2.10.1'
}

// Əsas istifadə
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"}

Əsas serializasiyadan əlavə, Gson davranışı konfiqurasiya etmək üçün GsonBuilder təqdim edir: tarixlərin formatlaşdırılması, HTML escape-in söndürülməsi, açarların registri və fərdi nümunələr. GsonBuilder həmçinin kitabxananın avtomatik emal edə bilmədiyi tiplər üçün fərdi JsonSerializer və JsonDeserializer qeydiyyatdan keçirməyə imkan verir. Konfiqurasiya elastikliyi GsonBuilder-ı müasir Android proqramlaşdırmasında kitabxananı layihənin spesifik tələblərinə uyğunlaşdırarkən əvəzolunmaz və faydalı alətə çevirir.

Əsas əməliyyatlar toJson və fromJson

toJson Java obyektini JSON sətrinə çevirir, onun sahələrini refleksiya vasitəsilə təhlil edir. Susmaya görə Gson transient və static istisna olmaqla bütün sahələri daxil edir. Metod istənilən tipləri dəstəkləyir: primitivlər, obyektlər, kolleksiyalar və massivlər. fromJson əks çevirməni yerinə yetirir, JSON sətirini və hədəf obyektin sinfini qəbul edir və sahələri doldurulmuş nümunə qaytarır.

Obyektin JSON-a çevrilməsi

Serializasiya zamanı Gson obyektin bütün sahələrini, o cümlədən iç-içə olanları rekursiv şəkildə gəzir. Dövri istinadlar StackOverflowError-a səbəb olur, buna görə də onlar @Expose annotasiyası və ya fərdi adapter vasitəsilə xaric edilməlidir. Kolleksiyalar üçün Gson elementlərin tipini qoruyur, lakin generiklərlə siyahının deserializasiyası zamanı tip haqqında məlumatı qorumaq üçün TypeToken tələb olunur.

// iç-içə obyektlə data class
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"))

// JSON-a serializasiya
val json = gson.toJson(employee)

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

Annotasiyalar və konfiqurasiya

Gson serializasiya prosesini idarə etmək üçün annotasiyalar dəsti təqdim edir. @SerializedName sahə adından fərqlənən JSON açarının adını təyin edir. @Expose sahənin serializasiyaya daxil edilməsini idarə edir: GsonBuilder.excludeFieldsWithoutExposeAnnotation() vasitəsilə yaradılmış Gson yalnız @Expose olan sahələri emal edəcək. @Since və @Until sahələrin versiyalaşdırılmasını idarə edir.

@SerializedName və @Expose

@SerializedName annotasiyası ad uyğunsuzluğu problemini həll edir: server snake_case istifadə edə bilər, kodda isə camelCase qəbul edilmişdir. Annotasiya dəyəri və geriyə uyğunluq üçün isteğe bağlı alternativləri qəbul edir. @Expose həssas sahələri (parollar, tokenlər) @Expose(serialize = false) kimi qeyd edərək serializasiyadan gizlətməyə imkan verir. Daxil etmə və xaric etməkdən əlavə, @Expose GsonBuilder.excludeFieldsWithoutExposeAnnotation ilə birləşdirilərək sahələrin ağ siyahısını yaratmaq olar ki, bu da çox sayda sahəsi olan obyektlərin serializasiyası zamanı hücum səthini idarə etməyə kömək edir.

// Gson annotasiyaları ilə model
data class UserResponse(
    @SerializedName("user_id")
    val userId: Int,

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

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

// @Expose filtri ilə Gson
val gson = GsonBuilder()
    .excludeFieldsWithoutExposeAnnotation()
    .setPrettyPrinting()
    .create()

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

Generiklərlə iş

Generiklər problemi Java və Kotlin-də kompilasiya zamanı tiplərin silinməsindən ibarətdir. Gson List<User>-ı deserializasiya edərkən elementin tipini bilmir və List<Map<String, Any>> qaytarır. Tip haqqında məlumatı qorumaq üçün Gson TypeToken — anonim sinif vasitəsilə tip parametrini tutan abstrakt sinif təqdim edir. TypeToken olmadan tərtibatçı hər bir elementi Map-dan hədəf tipə əl ilə çevirməli olacaq ki, bu da yığcam olmayan kod və performans itkisinə səbəb olur.

Siyahılar üçün TypeToken

TypeToken tiplərin silinməsi problemini həll edir. Tərtibatçı tələb olunan tip parametri ilə anonim TypeToken varisi yaradır və Gson düzgün deserializasiya üçün sinif imzasındakı məlumatdan istifadə edir. TypeToken həmçinin Map, Set və iç-içə generiklər də daxil olmaqla istənilən digər parametrləşdirilmiş tiplərlə işləyir. Xüsusilə, Map<String, List<User>> üçün iç-içə tipin tam imzası ilə TypeToken tələb olunur, əks halda Gson dəyərləri List<User> əvəzinə List<Map<String, Any>> kimi deserializasiya edir.

// Siyahının deserializasiyası üçün TypeToken
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)

// Fərdi deserializator
class LocalDateAdapter :
    JsonDeserializer<LocalDate> {

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

Fərdi serializasiya məntiqi üçün Gson JsonSerializer və JsonDeserializer interfeyslərini dəstəkləyir. Onlar GsonBuilder.registerTypeAdapter() vasitəsilə qeydiyyatdan keçirilir və kitabxananın avtomatik serializasiya edə bilmədiyi tipləri emal etməyə imkan verir: Java 8 tarixləri, qeyri-standart dəyərləri olan Enum və ya mənbə koduna girişi olmayan üçüncü tərəf sinifləri. Adapter tətbiq edərkən performansa nəzarət etmək vacibdir: fərdi adapter daxilində refleksiya çağırışı əl ilə idarəetmənin üstünlüklərini heçə endirir, buna görə də metod və sahələrin birbaşa çağırışlarına üstünlük verilir. Gson ekosistemində həmçinin UUID, Optional və Joda-Time tarix növləri kimi geniş yayılmış tiplər üçün adapterlər təqdim edən gson-extras modulu mövcuddur.

GsonBuilder vasitəsilə konfiqurasiya

GsonBuilder serializasiyanın incə sazlanması üçün onlarla metod təqdim edir. setPrettyPrinting çıxış JSON-a oxunaqlılıq üçün abzas və sətir sonu əlavə edir. disableHtmlEscaping sətirlərdə HTML simvollarının escape edilməsini söndürür. setDateFormat qeyri-standart vaxt təsvirindən istifadə edən serverlərlə işləyərkən kritik olan tarix formatını təyin edir. setLenient JSON formatlaşdırma xətalarının bəzilərini nəzərə almayan boş rejimi aktivləşdirir. addDeserializationExclusionStrategy fərdi strategiyalar əsasında sahələri deserializasiyadan proqramlı şəkildə xaric etməyə imkan verir. Debug üçün setPrettyPrinting metodu logging ilə birlikdə faydalıdır — JSON cavablarını loglarda oxunaqlı edir və uyğunsuzluqların axtarışını asanlaşdırır.

GsonBuilder-ın vacib imkanı @Since və @Until annotasiyaları vasitəsilə sahələrin versiyalaşdırılmasını idarə etməkdir. Tərtibatçı setVersion vasitəsilə obyektin versiyasını təyin edir və Gson versiya annotasiyasından asılı olaraq sahələri avtomatik daxil edir və ya xaric edir. Bu, eyni modelin server protokolunun müxtəlif versiyaları üçün istifadə edildiyi API təkamülü zamanı faydalıdır. GsonBuilder həmçinin tip ailələrinin qlobal emalı üçün TypeAdapterFactory qeydiyyatını və mürəkkəb Map açarları ilə düzgün iş üçün complexMapKeySerialization dəstəkləyir.