Retrofit — bu nədir, HTTP-kitabxanası və tətbiqlərdə istifadəsi

Retrofit nədir?

Retrofit Square şirkəti tərəfindən hazırlanmış, Android tətbiqlərində HTTP sorğularını yerinç yetirmək üçün kitabxanadır. O, REST API-lərinin Java interfeysləri və annotasiyalar vasitəsilə deklarativ təyin edilməsini təmin edir ki, bu da şəbəkə qarşılıqlı əlaqə kodunu təmiz və proqnozlaşdırıla bilən edir.

Retrofit-in əsas ideyası ondan ibarətdir ki, proqramçı API-i metodlar və annotasiyalarla interfeys kimi təsvir edir, kitabxana isə müstəqil şəkildə tətbiqi yaradır. Bu yanaşma bütün endpointlərin tipləşdirildiyini və URL və ya parametrlərdəki səhvlərin icra zamanı deyil, kompilasiya mərhələsində aşkarlanmasını təmin edir.

Retrofit bütün populyar HTTP metodlarını və data formatlarını dəstəkləyir. Kitabxana Square və icma tərəfindən aktiv şəkildə dəstəklənir: yeni versiyalar müzəmmədən buraxılır, cari versiya 2.11 isə Java 17 və Kotlin 2.0 dəstəyini əhatə edir. Retrofit Android üçün ən populyar HTTP-klient olaraq qalır.

Retrofit OkHttp üzərində işləyir — həmçinin Square tərəfindən olan səmərəli HTTP-klient. Bu birləşmə nəqliyyat protokolu səviyyəsində keşləmə, sorğu interceptorları və bağlantı idarəetməsini təmin edir. Kitabxana həm sinxron, həm də asinxron çağırışları dəstəkləyir.

2013-cü ildəki ilk buraxılışından bəri Retrofit bir neçə böyük yenilənmə keçmişdir. Cari Retrofit 2 versiyası birinci versiyanın istifadə təcrübəsi nəzərə alınaraq tamamilə yenidən yazılmışdır və asinxronluq üçün daha çevik konvertor və adapter sistemi təklif edir.

Retrofit-in arxitekturası bölgü prinsipinə əməl edir: interfeys yalnız API müqaviləsini təyin edir, konvertorlər serializasiyaya cavabdehdir, adapterlər isə asinxronluğu idarə edir. Bu, qalan kodu dəyişdirmədən istənilən komponenti əvəz etməyə imkan verir. Məsələn, endpoint təriflərini dəyişdirmədən Gson-dan Moshi-yə keçmək olar.

Retrofit-in əsas imkanları

Retrofit mobil tətbiqlərdə şəbəkə qarşılıqlı əlaqəsinin demək olar ki, bütün ssenarilərini əhatə edən funksiyalar dəsti təqdim edir. əsas üstünlük API-nin deklarativ üslubda təyin edilməsidir.

Endpointlərin deklarativ annotasiyaları

Annotasiyalar @GET, @POST, @PUT, @PATCH, @DELETE və @HTTP birbaşa interfeysdə HTTP metodunu və URL şablonunu təyin etməyə imkan verir. Yol parametrləri @Path vasitəsilə, sorğu parametrləri @Query vasitəsilə, sorğu gövdəsi isə @Body vasitəsilə təyin edilir. Bu yanaşma tətbiqin API qatını tamamilə tipləşdirilmiş edir.

Serializasiya üçün konvertorlər

Konvertorlər HTTP cavablarını Java obyektlərinə və əksinə çevirir. Retrofit Gson, Moshi, Jackson, Protobuf və Wire-i dəstəkləyir. Proqramçı Converter.Factory vasitəsilə lazımi konvertoru qoşur və kitabxana onu avtomatik olaraq bütün sorğu və cavablara tətbiq edir.

Asinxronluq üçün adapterlər

Adapterlər CallAdapter API metodlarının qaytarılan dəyər tipini dəyişdirməyə imkan verir. Standart Call əvəzinə RxJava üçün Observable, Kotlin korutinləri üçün Deferred və ya LiveData istifadə edilə bilər. Bu, şəbəkə sorğularını seçilmiş tətbiq arxitekturası ilə inteqrasiya edir.

Dinamik URL və başlıqlar

Dinamik URL-lər @Url annotasiyaları vasitəsilə təyin edilir ki, bu da endpointi icra zamanı ötürməyə imkan verir. Başlıqlar statik olaraq @Headers və ya dinamik olaraq @Header parametri vasitəsilə göstərilə bilər. Bütün sorğular üçün qlobal başlıqlar üçün OkHttp interceptorundan istifadə olunur.

Retrofit necə işləyir?

Retrofit üç mərhələdə işləyir: API interfeysinin təyini, Retrofit nümunəsinin yaradılması və sorğunun icrası. Kitabxana annotasiyalar və konvertorlər əsasında interfeysin tətbiqini icra zamanı yaradır.

Sorğun həyat dövrü

API metodu çağırıldıqda, Retrofit annotasiyalar və arqumentlər əsasında Request obyekti yaradır. Sorğu icra üçün OkHttp-ya ötürülür. Cavab alındıqdan sonra kitabxana onu lazımi tipə çevirmək üçün Converter.Factory-yə göndərir. CallAdapter nəticəni asinxron sarğıcıya bükür. Hər bir mərhələ fərdiləşdirilə bilər.

interface ApiService {
    @GET("users/{id}")
    suspend fun getUser(@Path("id") id: Int): User
}

val retrofit = Retrofit.Builder()
    .baseUrl("https://api.example.com/")
    .addConverterFactory(GsonConverterFactory.create())
    .build()

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

Retrofit-in quraşdırılması və konfiqurasiyası

Quraşdırma Retrofit Android-in standart yığma sistemi olan Gradle vasitəsilə həyata keçirilir. Kitabxana Maven Central vasitəsilə yayılır və layihənin build.gradle faylına bir neçə asılılıq əlavə edilməsini tələb edir.

Asılılıqların əlavə edilməsi

build.gradle faylına (modul səviyyəsi) Retrofit, Gson konvertoru və OkHttp üçün asılılıqlar əlavə edin. Kitabxana versiyalarının mərkəzləşdirilmiş idarə edilməsi üçün kök build.gradle-də dəyişənlərə çıxarılması tövsiyə olunur. Retrofit 2 minimum Android API 21 tələb edir.

dependencies {
    implementation "com.squareup.retrofit2:retrofit:2.11.0"
    implementation "com.squareup.retrofit2:converter-gson:2.11.0"
    implementation "com.squareup.okhttp3:okhttp:4.12.0"
    implementation "com.squareup.okhttp3:logging-interceptor:4.12.0"
}

Retrofit nümunəsinin yaradılması

Retrofit nümunəsi Builder vasitəsilə yaradılır. Məcburi parametrlər: baseUrl və ConverterFactory. Artıq bağlantıların yaranmasının qarşısını almaq üçün Retrofit və OkHttpClient üçün sinqltondan istifadə etmək tövsiyə olunur. Logging-interceptor əlavə etmək inkişaf zamanı şəbəkə sorğularının sazlanmasını asanlaşdırır.

Kotlin layihələri üçün API interfeysində Call tipləri əvəzinə suspend-funksiyalardan istifadə etmək tövsiyə olunur. Bu, kodu sadələşdirir və korutinlərin strukturlaşdırılmış paralelliyindən istifadə etməyə imkan verir. Call-dan suspend-ə keçid zamanı interfeysdə qaytarılan tipi dəyişmək kifayətdir — qalan kod avtomatik uyğullaşır.

Retrofit istifadə nümunələri

Nümunələr aşağıda Android tətbiqlərində Retrofit ilə işin tipik ssenarilərini nümayiş etdirir: sadə GET sorğusundan faylı serverə yükləməyə qədər.

Query parametrləri ilə GET sorğusu

Sadə GET sorğusu sorğu sətri parametrləri ilə əsas əməliyyatdır. @Query annotasiyası parametrləri avtomatik olaraq URL-ə əlavə edir, suspend-funksiya isə əsas axını bloklamadan korutindən sorğu çağırmağa imkan verir.

interface UserApi {
    @GET("users")
    suspend fun getUsers(
        @Query("page") page: Int,
        @Query("limit") limit: Int = 20
    ): List<User>
}

val users = api.getUsers(page = 1)

JSON gövdəsi ilə POST sorğusu

POST sorğusu JSON gövdəsi ilə obyekti ötürmək üçün @Body annotasiyasından istifadə edir. GsonConverterFactory User obyektini avtomatik olaraq JSON-a serializasiya edir. Kotlin korutinləri Callback interfeysləri olmadan sorğun fon axınında icrasını təmin edir.

interface UserApi {
    @POST("users")
    suspend fun createUser(@Body user: User): User
}

val user = User(name = "Anna Ivanova", email = "anna@example.com")
val created = api.createUser(user)

Faylın Multipart vasitəsilə yüklənməsi

@Multipart annotasiyası @Part ilə faylları serverə yükləməyə imkan verir. Retrofit avtomatik olaraq lazımi başlıqlarla multipart sorğu yaradır. OkHttp yükləmə prosesini RequestBody vasitəsilə idarə edir ki, bu da istifadəçiyə göstərici göstərməyə imkan verir.

interface FileApi {
    @Multipart
    @POST("upload")
    suspend fun uploadImage(
        @Part file: MultipartBody.Part
    ): UploadResponse
}

val body = "image.jpg".toRequestBody("image/jpeg".toMediaTypeOrNull())
val part = MultipartBody.Part.createFormData("file", "image.jpg", body)

Retrofit-də xəta idarəetməsi və interceptorlar

Xəta idarəetməsi Retrofit-də OkHttp mexanizmlərinin və Kotlin korutinlərinin birləşməsinə əsaslanır. OkHttp interceptorları sorğuları qeydiyyata almağa, autentifikasiya başlıqları əlavə etməyə və səhvləri tətbiq koduna çatmamış əvvəl idarə etməyə imkan verir.

Mərkəzləşdirilmiş xəta idarəetməsi üçün tez-tez API çağırışları üzərində sealed class Result şəklində sarğıcı yaradılır. Belə sinif iki varis ehtiva edir: məlumatlarla Success və istisna ilə Error. ViewModel vahid nəticə alır və hər funksiyada xəta idarəetmə kodunu təkrarlamadan istifadəçi interfeysinin müvafiq vəziyyətini göstərə bilər.

Interceptorlar iki növdür: tətbiq interceptorları sorğunu serverə göndərməzdən əvvəl dəyişdirir, şəbəkə interceptorları isə cavabı aldıqdan sonra işləyir. Məsələn, interceptor 401 cavabı aldıqda avtomatik olaraq giriş tokenini yeniləyə və yeni tokenlə sorğunu təkrarlaya bilər.

Interceptor vasitəsilə sorğuların qeydiyyatı

Logging interceptor HttpLoggingInterceptor şəbəkə sorğularının sazlanması üçün əvəzedilməz vasitədir. O, Logcat-də sorğu metodunu, URL-i, başlıqları, gövdəni və cavab kodunu göstərir. Qeydiyyat səviyyəsi konfiqurasiya edilə bilər: BASIC minimal məlumat üçün, HEADERS başlıqlar üçün və ya BODY tam məzmun üçün. İstehsalatda BASIC istifadə etmək və ya qeydiyyatı tamamilə söndürmək tövsiyə olunur.

Interceptorlar OkHttp-də iki növə bölünür: sorğunu dəyişdirmək üçün tətbiq interceptorları və xam şəbəkə məlumatları ilə işləmək üçün şəbəkə interceptorları. Logging interceptor avtomatik olaraq sorğu və cavab detallarını Logcat-də göstərir.

Xəta idarəetməsi korutin səviyyəsində suspend-funksiya çağırışı ətrafında try-catch vasitəsilə həyata keçirilir. Retrofit 4xx və 5xx kodları üçün HttpException, şəbəkə olmadıqda UnknownHostException və vaxt limiti aşıldıqda SocketTimeoutException şəklində səhvlər qaytarır. Vahid idarəetmə üçün sealed class Result istifadə etmək tövsiyə olunur.