Retrofit — bu nima, HTTP-kutubxonasi va ilovalarda foydalanish

Retrofit nima?

Retrofit Square kompaniyasi tomonidan ishlab chiqilgan, Android ilovalarida HTTP so'rovlarini bajarish uchun kutubxonadir. U REST API-larini Java interfeyslari va annotatsiyalar orqali deklarativ aniqlashni ta'minlaydi, bu tarmoq aloqasi kodini toza va bashorat qilinadigan qiladi.

Retrofit-ning asosiy g'oyasi shundan iboratki, dasturchi API-ni metodlar va annotatsiyalar bilan interfeys sifatida tavsiflaydi, kutubxona esa mustaqil ravishda implementatsiyani yaratadi. Bunday yondashuv barcha endpointlarning tiplanganligini va URL yoki parametrlardagi xatolarning ish vaqtida emas, kompilyatsiya bosqichida aniqlanishini kafolatlaydi.

Retrofit barcha mashhur HTTP metodlari va ma'lumot formatlarini qo'llab-quvvatlaydi. Kutubxona Square va jamoa tomonidan faol qo'llab-quvvatlanadi: yangi versiyalar muntazam chiqariladi, joriy versiya 2.11 esa Java 17 va Kotlin 2.0 qo'llab-quvvatlashni o'z ichiga oladi. Retrofit Android uchun eng mashhur HTTP-klient bo'lib qolmoqda.

Retrofit OkHttp ustida ishlaydi — shuningdek Square tomonidan yaratilgan samarali HTTP-klient. Bu birikma transport protokoli darajasida keshlash, so'rov interceptorlari va ulanishlarni boshqarishni ta'minlaydi. Kutubxona ham sinxron, ham asinxron chaqiruvlarni qo'llab-quvvatlaydi.

2013-yildagi birinchi relizdan beri Retrofit bir nechta katta yangilanishlardan o'tdi. Joriy Retrofit 2 versiyasi birinchi versiya tajribasini hisobga olgan holda to'liq qayta yozilgan va asinxronlik uchun yanada moslashuvchan konvertor va adapter tizimini taklif qiladi.

Retrofit arxitekturasi ajratish tamoyiliga amal qiladi: interfeys faqat API shartnomasini belgilaydi, konvertorlar serializatsiya uchun javobgar, adapterlar esa asinxronlikni boshqaradi. Bu qolgan kodni o'zgartirmasdan istalgan komponentni almashtirish imkonini beradi. Masalan, endpoint ta'riflarini o'zgartirmasdan Gson-dan Moshi-ga o'tish mumkin.

Retrofit-ning asosiy imkoniyatlari

Retrofit mobil ilovalarda tarmoq aloqasining deyarli barcha stsenariylarini qamrab oluvchi funksiyalar to'plamini taqdim etadi. Asosiy afzallik — API-ni deklarativ usulda aniqlash.

Endpointlarning deklarativ annotatsiyalari

Annotatsiyalar @GET, @POST, @PUT, @PATCH, @DELETE va @HTTP to'g'ridan-to'g'ri interfeysda HTTP metodini va URL shablonini aniqlash imkonini beradi. Yo'l parametrlari @Path orqali, so'rov parametrlari @Query orqali, so'rov tanasi esa @Body orqali belgilanadi. Bunday yondashuv ilovaning API qatlamini to'liq tiplangan qiladi.

Serializatsiya uchun konvertorlar

Konvertorlar HTTP javoblarini Java obyektlariga va aksincha aylantiradi. Retrofit Gson, Moshi, Jackson, Protobuf va Wire-ni qo'llab-quvvatlaydi. Dasturchi Converter.Factory orqali kerakli konvertorni ulaydi va kutubxona uni avtomatik ravishda barcha so'rov va javoblarga qo'llaydi.

Asinxronlik uchun adapterlar

Adapterlar CallAdapter API metodlarining qaytariladigan qiymat turini o'zgartirish imkonini beradi. Standart Call o'rniga RxJava uchun Observable, Kotlin korutinlari uchun Deferred yoki LiveData ishlatilishi mumkin. Bu tarmoq so'rovlarini tanlangan ilova arxitekturasi bilan integratsiyalaydi.

Dinamik URL va sarlavhalar

Dinamik URL-lar @Url annotatsiyalari orqali belgilanadi, bu esa endpointni ish vaqtida uzatish imkonini beradi. Sarlavhalar statik ravishda @Headers yoki dinamik ravishda @Header parametri orqali ko'rsatilishi mumkin. Barcha so'rovlar uchun global sarlavhalar uchun OkHttp interceptoridan foydalaniladi, u har bir chiquvchi so'rovga sarlavhalar qo'shadi.

Retrofit qanday ishlaydi?

Retrofit uch bosqichda ishlaydi: API interfeysini aniqlash, Retrofit namunasini yaratish va so'rovni bajarish. Kutubxona annotatsiyalar va konvertorlar asosida interfeys implementatsiyasini ish vaqtida yaratadi.

So'rovning hayot aylanishi

API metodi chaqirilganda, Retrofit annotatsiyalar va argumentlar asosida Request obyektini yaratadi. So'rov bajarish uchun OkHttp-ga uzatiladi. Javob olingandan so'ng, kutubxona uni kerakli turga aylantirish uchun Converter.Factory-ga yuboradi. CallAdapter natijani asinxron o'ramga o'raydi. Har bir bosqich moslashtirilishi mumkin.

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-ni o'rnatish va sozlash

O'rnatish Retrofit Gradle — Android-ning standart qurish tizimi orqali amalga oshiriladi. Kutubxona Maven Central orqali tarqatiladi va loyihaning build.gradle fayliga bir nechta bog'liqlik qo'shishni talab qiladi.

Bog'liqliklarni qo'shish

build.gradle fayliga (modul darajasi) Retrofit, Gson konvertori va OkHttp uchun bog'liqliklarni qo'shing. Kutubxona versiyalarini markazlashtirilgan boshqarish uchun ildiz build.gradle-da o'zgaruvchilarga chiqarish tavsiya etiladi. Retrofit 2 minimal Android API 21 ni talab qiladi.

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 namunasini yaratish

Retrofit namunasi Builder orqali yaratiladi. Majburiy parametrlar: baseUrl va ConverterFactory. Ortiqcha ulanishlar yaratilishining oldini olish uchun Retrofit va OkHttpClient uchun singletondan foydalanish tavsiya etiladi. Logging-interceptor qo'shish rivojlanish vaqtida tarmoq so'rovlarini tuzatishni osonlashtiradi.

Kotlin loyihalari uchun API interfeysida Call turlari o'rniga suspend funksiyalardan foydalanish tavsiya etiladi. Bu kodni soddalashtiradi va korutinlarning tuzilgan parallelligidan foydalanish imkonini beradi. Call-dan suspend-ga o'tishda interfeysdagi qaytariladigan turni o'zgartirish kifoya — qolgan kod avtomatik moslashadi.

Retrofit-dan foydalanish misollari

Misollar quyida Android ilovalarida Retrofit bilan ishlashning odatiy stsenariylarini namoyish etadi: oddiy GET so'rovidan faylni serverga yuklashgacha.

Query parametrlari bilan GET so'rovi

Oddiy GET so'rovi so'rov satri parametrlari bilan — asosiy operatsiya. @Query annotatsiyasi parametrlarni avtomatik ravishda URL-ga qo'shadi, suspend funksiya esa asosiy oqimni bloklamasdan korutindan so'rovni chaqirish imkonini beradi.

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 tanasi bilan POST so'rovi

POST so'rovi JSON tanasi bilan ob'ektni uzatish uchun @Body annotatsiyasidan foydalanadi. GsonConverterFactory User ob'ektini avtomatik ravishda JSON-ga serializatsiya qiladi. Kotlin korutinlari Callback interfeyslarisiz so'rovning fon oqimida bajarilishini ta'minlaydi.

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)

Faylni Multipart orqali yuklash

@Multipart annotatsiyasi @Part bilan fayllarni serverga yuklash imkonini beradi. Retrofit avtomatik ravishda kerakli sarlavhalar bilan multipart so'rovini yaratadi. OkHttp yuklash jarayonini RequestBody orqali boshqaradi, bu esa foydalanuvchiga indikator ko'rsatish imkonini beradi.

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-da xato boshqaruvi va interceptorlar

Xato boshqaruvi Retrofit-da OkHttp mexanizmlari va Kotlin korutinlarining kombinatsiyasiga asoslanadi. OkHttp interceptorlari so'rovlarni qayd etish, autentifikatsiya sarlavhalarini qo'shish va xatolarni ilova kodiga yetib bormasdan oldin boshqarish imkonini beradi.

Markazlashtirilgan xato boshqaruvi uchun ko'pincha API chaqiruvlari ustida sealed class Result ko'rinishida o'ram yaratiladi. Bunday sinf ikkita vorisni o'z ichiga oladi: ma'lumotlar bilan Success va istisno bilan Error. ViewModel birlashtirilgan natijani oladi va har bir funksiyada xato boshqaruvi kodini takrorlamasdan foydalanuvchi interfeysining tegishli holatini ko'rsatishi mumkin.

Interceptorlar ikki turga bo'linadi: ilova interceptorlari so'rovni serverga yuborishdan oldin o'zgartiradi, tarmoq interceptorlari esa javobni olgandan keyin ishlaydi. Masalan, interceptor 401 javobini olganda avtomatik ravishda kirish tokenini yangilab, so'rovni yangi token bilan takrorlashi mumkin.

Interceptor orqali so'rovlarni qayd etish

Logging-interceptor HttpLoggingInterceptor tarmoq so'rovlarini tuzatishda ajralmas vositadir. U Logcat-da so'rov metodini, URL-ni, sarlavhalarni, tanani va javob kodini ko'rsatadi. Qayd etish darajasini sozlash mumkin: BASIC minimal ma'lumot uchun, HEADERS sarlavhalar uchun yoki BODY to'liq tarkib uchun. Ishlab chiqarishda BASIC dan foydalanish yoki qayd etishni butunlay o'chirish tavsiya etiladi.

Interceptorlar OkHttp-da ikki turga bo'linadi: so'rovni o'zgartirish uchun ilova interceptorlari va xom tarmoq ma'lumotlari bilan ishlash uchun tarmoq interceptorlari. Logging-interceptor avtomatik ravishda so'rov va javob tafsilotlarini Logcat-da ko'rsatadi.

Xato boshqaruvi korutin darajasida suspend funksiya chaqiruvi atrofida try-catch orqali amalga oshiriladi. Retrofit 4xx va 5xx kodlari uchun HttpException, tarmoq bo'lmaganda UnknownHostException va vaqt chegarasi oshib ketganda SocketTimeoutException ko'rinishida xatolarni qaytaradi. Birlashtirilgan boshqaruv uchun sealed class Result dan foydalanish tavsiya etiladi.