Retrofit: bu nədir, Android HTTP-klientinin xüsusiyyətləri

Retrofit nədir?

Retrofit — Square şirkəti tərəfindən hazırlanmış Android platformasında REST API ilə tipizə edilmiş qarşılıqlı əlaqə üçün kitabxanadır. O, annotasiyalarla Java və ya Kotlin interfeysləri vasitəsilə HTTP sorğularını təsvir etməyin deklarativ üsulunu təmin edir, proqramçını JSON-un əl ilə pars edilməsindən və HTTP bağlantılarının idarə edilməsindən tamamilə azad edir.

Kitabxana 2013-cü ildə AsyncTask və HttpURLConnection kimi yöndəmsiz həllərə alternativ olaraq ortaya çıxdı. 2025-ci ilə qədər Retrofit sadəliyi və tip təhlükəsizliyi sayəsində Android tətbiqlərində şəbəkə qarşılıqlı əlaqəsi üçün de-fakto standart olaraq qalır. JetBrains Developer Ecosystem 2024 sorğusuna görə, Retrofit kommersiya layihələrində Android proqramçılarının 65%-dən çoxu tərəfindən istifadə olunur.

Retrofit-in analoqlardan əsas fərqi — deklarativ yanaşmadır: proqramçı nə edəcəyini (hansı endpoint-i çağırmaq, hansı parametrləri ötürmək) təsvir edir, necə edəcəyini yox (əlaqəni necə açmaq, InputStream-i necə oxumaq, JSON-u necə pars etmək). Bu, HttpURLConnection-un əl ilə istifadəsi ilə müqayisədə boilerplate kodun miqdarını 60–70% azaldır.

Retrofit necə işləyir

İş prinsipi — Retrofit Java dinamik proksilərinə əsaslanır. Proqramçı annotasiyalarla işarələnmiş interfeys metodunu çağırdıqda, Retrofit Proxy.newProxyInstance mexanizmi vasitəsilə çağırışı ələ keçirir və onu HTTP sorğusuna çevirir. Bütün proses kompilyasiya mərhələsində kod generasiyası olmadan runtime-da baş verir.

Retrofit.Builder nümunəsi yaradılarkən baza URL-i və konvertor fabriki göstərilir. Builder OkHttpClient-i konfiqurasiya edir — timeout-lar, interceptor-lar, bağlantı hovuzu və keş təyin edir. create(Class) metodu interfeysin implementasiyasını yaradır, adi sinif kimi çağrıla bilən proksi-obyekti qaytarır.

Sorğunun icra zənciri belə görünür: annotasiyalar HTTP metodunu çıxarır, parametrlər URL-ə və ya sorğu gövdəsinə yerləşdirilir, konvertor gövdəni serializasiya edir, OkHttp sorğunu yerinə yetirir, konvertor cavabı deserializasiya edir, nəticə göstərilən tipdə qaytarılır. Hər mərhələ təcrid olunub və fərdi implementasiya ilə əvəz edilə bilər, məsələn, test üçün OkHttpClient-in MockWebServer ilə əvəz edilməsi və ya API dəyişikliyində konvertorun dəyişdirilməsi.

Vacib xüsusiyyət — Retrofit birbaşa məlumat axını ötürməni dəstəkləmir. Axın üçün interfeys metodunun qaytarma tipi kimi OkHttp ResponseBody istifadə olunur. Retrofit həmçinin sorğuların ləğvini avtomatik idarə etmir — ləğv etmək üçün Call-a istinadı saxlayıb cancel() çağırmaq lazımdır. Kotlin-də suspend funksiyaları ilə sorğunun ləğvi valideyn korutinin ləğvində avtomatik baş verir.

Call obyektinin həyat dövrü

Call<T> — bir HTTP sorğusunu təmsil edən obyektdir. İcradan sonra (execute və ya enqueue) Call təkrar istifadə edilə bilməz — təkrar sorğu üçün interfeys metodunu çağıraraq yeni Call yaradılmalıdır. Bu, eyni sorğunun təsadüfən iki dəfə göndərilməsindən qoruyur ki, bu da serverdə əməliyyatların təkrarlanmasına səbəb ola bilər.

Kotlin-də Call əvəzinə avtomatik idarə edən suspend funksiyaları istifadə olunur. Retrofit özü icranı Dispatchers.IO-ya keçirir və nəticəni korutinə qaytarır. Bu, Call və Callback versiyası ilə müqayisədə kodu 30–40% qısaldır.

HTTP metodları üçün Retrofit annotasiyaları

Annotasiyalar — Retrofit-də HTTP sorğularının konfiqurasiyasının əsas mexanizmidir. Hər annotasiya standart HTTP metoduna uyğun gəlir və endpoint-ə nisbi yol qəbul edir. Retrofit GET, POST, PUT, DELETE, PATCH, HEAD və OPTIONS-ı dəstəkləyir.

Sorğu parametrlərinin annotasiyaları

@Path dəyəri URL seqmentində əvəz edir: @Path(id) Int id {id}-ni yolda əvəz edir. @Query query-parametr əlavə edir: @Query(page) Int page ?page=5-ə çevrilir. @Body seçilmiş konvertor vasitəsilə avtomatik serializasiya ilə obyekti sorğu gövdəsində ötürür. @Header və @Headers statik və ya dinamik HTTP başlıqlarını idarə edir.

Bu annotasiyaları birləşdirərək istənilən REST endpoint-i təsvir etmək olar. Məsələn, POST /api/users/{id}/posts?limit=10 endpoint-i üçün @POST, id üçün @Path, limit üçün @Query və ötürülən obyekt üçün @Body tələb olunur. Retrofit avtomatik düzgün HTTP sorğusu yığacaq. Əlavə olaraq @Url (dinamik URL), @Field (form-encoded body), @Part və @PartMap fayllarla multipart sorğular üçün dəstəklənir.

Kotlin-də Retrofit kod nümunələri

Praktik nümunəni nəzərdən keçirək — GitHub API üçün interfeys. Repozitoriyaların siyahısını almaq metodu ilə Kotlin interfeysi yaradılır. Data class Repo JSON cavabının strukturunu təsvir edir.

data class Repo(
    val name: String,
    val description: String?,
    val stargazersCount: Int,
    val forksCount: Int
)

interface GitHubApi {
    @GET("users/{user}/repos")
    suspend fun getRepos(
        @Path("user") user: String,
        @Query("sort") sort: String = "updated"
    ): List<Repo>
}

Interfeys təsvir edildikdən sonra Builder vasitəsilə Retrofit nümunəsi yaradılır. Baza URL, konvertor və OkHttpClient bir dəfə konfiqurasiya edilir və dependency injection vasitəsilə təkrar istifadə olunur.

val retrofit = Retrofit.Builder()
    .baseUrl("https://api.github.com/")
    .addConverterFactory(GsonConverterFactory.create())
    .client(OkHttpClient.Builder()
        .connectTimeout(30, TimeUnit.SECONDS)
        .build())
    .build()

val api = retrofit.create(GitHubApi::class.java)

Response ilə cavabın emalı

HTTP statuslarının çevik emalı üçün Response<T> örtüyündən istifadə edin. O, cavab koduna, başlıqlara və gövdəyə giriş imkanı verir, 4xx və 5xx səhvlərində istisna atmır. Bu, 404 və 500-ü try-catch olmadan emal etməyə imkan verir.

interface GitHubApi {
    @GET("users/{user}/repos")
    suspend fun getRepos(
        @Path("user") user: String
    ): Response<List<Repo>>
}

val response = api.getRepos("octocat")
if (response.isSuccessful) {
    println(response.body()?.size)
} else {
    Log.e("API", "Xəta: ${response.code()}")
}

Retrofit-də konvertorlar və serializasiya

Konvertorlar — obyektləri HTTP gövdəsinə və əksinə çevirməyə cavabdeh olan Retrofit komponentləridir. Retrofit serializasiyanı nüvəyə daxil etmir — bunun əvəzinə Converter.Factory vasitəsilə modul yanaşması istifadə olunur, istənilən serializasiya kitabxanasını qoşmağa imkan verir.

Ən populyar konvertor — Google-dan GsonConverterFactory Gson kitabxanası əsasında. Əksər layihələr üçün uyğundur, fərdi TypeAdapter və JsonDeserializer dəstəkləyir. Lakin Gson refeksiyadan istifadə edir və Kotlin-in null safety-ni nəzərə almır ki, bu da gözlənilməz null sahələrində NPE-yə səbəb ola bilər.

Alternativ — Square-dən MoshiConverterFactory: tiplərə daha ciddi, Kotlin-in daha yaxşı dəstəyi ilə (null safety, default values) və refeksiyasız. Təmiz Kotlin layihələri üçün optimal — kompilyasiya mərhələsində @Serializable annotasiyalarında işləyən Kotlinx Serialization Converter. Refeksiyadan istifadə etmir, sealed class, default values və multiplatformanı dəstəkləyir.

Konvertor seçimi məhsuldarlığa və təhlükəsizliyə təsir edir. Gson fərdi konfiqurasiya olmadan null-u Kotlin-in non-null sahəsinə deserializasiya edə bilər, müraciətdə NPE-yə səbəb olur. Moshi bu problemi @Json(name) annotasiyası və failOnUnknown vasitəsilə həll edir. Kotlinx Serialization ən təhlükəsizdir — kompilyasiya mərhələsində kod yaradır, runtime tip səhvlərini tamamilə istisna edir.

Retrofit ilə işdə tipik səhvlər

HTTP səhvlərinin emal edilməməsi suspend funksiyalarında — ən geniş yayılmış problem. Server 4xx və ya 5xx qaytardıqda, Retrofit HttpException atır. Try-catch olmadan tətbiq qəzaya uğrayacaq. Qaytarma tipi kimi Response<T> istifadəsi bu problemi həll edir, body-yə girişdən əvvəl isSuccessful-i yoxlamağa imkan verir.

Keşləmənin səhv konfiqurasiyası həddindən artıq trafikə səbəb olur. Retrofit cavabları özü keşləmir — bu tapşırığı OkHttpClient Cache vasitəsilə həll edir. Keş olmadan hər sorğu tam yerinə yetirilir, hətta məlumat dəyişmədikdə belə. OkHttpClient-də 10 MB ölçüsündə Cache əlavə etmək təkrar sorğularda trafiki 40–60% azaldır.

Hər sorğu üçün Retrofit yaratmaq — yeni başlayanların ümumi səhvi. Retrofit.Builder runtime-da proksi-siniflərin generasiyasını əhatə edən resurs tutumlu əməliyyatdır. Düzgün təcrübə — bir Retrofit nümunəsi yaratmaq və onu DI framework-ləri vasitəsilə təkrar istifadə etməkdir. Hilt, Koin və ya Dagger bütün tətbiq üçün Retrofit-in singleton nümunəsini təmin edir, bu da yaddaşa qənaət edir və sorğuları sürətləndirir.

Autorizasiya üçün Interceptor-un nəzərə alınmaması — dördüncü problem. Hər çağırışda Authorization başlığını əl ilə əlavə etmək əvəzinə OkHttpClient-də qlobal Interceptor konfiqurasiya edin. Interceptor hər sorğunu ələ keçirir, Bearer token əlavə edir, Authenticator isə 401 cavabını emal edir, tokeni yeniləyərək sorğunu avtomatik təkrarlayır. Bu, autentifikasiya məntiqini mərkəzləşdirir.