Retrofit — nedir, HTTP kütüphanesi ve uygulamalarda kullanım

Retrofit Nedir?

Retrofit, Square tarafından geliştirilmiş, Android uygulamalarında HTTP istekleri yapmak için bir kütüphanedir. Java arayüzleri ve ek açıklamalar aracılığıyla REST API'lerini tanımlamak için bildirimsel bir yaklaşım sunarak ağ etkileşim kodunu temiz ve öngörülebilir hale getirir.

Retrofit'in temel fikri, geliştiricinin API'yi yöntemler ve ek açıklamalar içeren bir arayüz olarak tanımlaması ve kütüphanenin otomatik olarak uygulamayı oluşturmasıdır. Bu yaklaşım, tüm uç noktaların türlenmiş olmasını ve URL veya parametrelerdeki hataların çalışma zamanında değil, derleme zamanında tespit edilmesini sağlar.

Retrofit, tüm popüler HTTP yöntemlerini ve veri formatlarını destekler. Kütüphane Square ve topluluk tarafından aktif olarak bakımı yapılmaktadır: düzenli olarak yeni sürümler yayınlanır ve mevcut sürüm 2.11, Java 17 ve Kotlin 2.0 desteğini içerir. Retrofit, Android için en popüler HTTP istemcisi olmaya devam etmektedir.

Retrofit, yine Square'in verimli bir HTTP istemcisi olan OkHttp üzerinde çalışır. Bu kombinasyon, taşıma protokolü düzeyinde önbellekleme, istek araya girme ve bağlantı yönetimi sağlar. Kütüphane hem senkron hem de asenkron çağrıları destekler.

2013'teki ilk sürümünden bu yana Retrofit birkaç büyük güncellemeden geçti. Mevcut sürüm Retrofit 2, ilk sürümün deneyimine dayanarak tamamen yeniden yazılmıştır ve asenkron işlemler için daha esnek bir dönüştürücü ve adaptör sistemi sunar.

Retrofit'in mimarisi sorumlulukların ayrılması ilkesini takip eder: arayüz yalnızca API sözleşmesini tanımlar, dönüştürücüler serileştirmeyi yönetir ve adaptörler asenkronizasyonu yönetir. Bu, diğer kodu değiştirmeden herhangi bir bileşenin değiştirilmesine olanak tanır. Örneğin, uç nokta tanımlarını değiştirmeden Gson'dan Moshi'ye geçiş yapabilirsiniz.

Retrofit'in Temel Özellikleri

Retrofit, mobil uygulamalarda neredeyse tüm ağ etkileşim senaryolarını kapsayan bir dizi özellik sunar. Temel avantajı, API tanımının bildirimsel stilidir.

Bildirimsel Uç Nokta Ek Açıklamaları

Ek açıklamalar @GET, @POST, @PUT, @PATCH, @DELETE ve @HTTP, arayüzde doğrudan HTTP yöntemini ve URL şablonunu belirlemenizi sağlar. Yol parametreleri @Path aracılığıyla, sorgu parametreleri @Query aracılığıyla ve istek gövdesi @Body aracılığıyla ayarlanır. Bu yaklaşım, uygulamanın API katmanını tamamen türlenmiş hale getirir.

Serileştirme İçin Dönüştürücüler

Dönüştürücüler, HTTP yanıtlarını Java nesnelerine ve tersine dönüştürür. Retrofit, Gson, Moshi, Jackson, Protobuf ve Wire'ı destekler. Geliştirici, Converter.Factory aracılığıyla gerekli dönüştürücüyü bağlar ve kütüphane bunu tüm isteklere ve yanıtlara otomatik olarak uygular.

Asenkron İşlemler İçin Adaptörler

Adaptörler CallAdapter, API yöntemlerinin dönüş türünü değiştirmeyi sağlar. Standart Call yerine, RxJava için Observable, Kotlin coroutines için Deferred veya LiveData kullanılabilir. Bu, ağ isteklerini seçilen uygulama mimarisiyle entegre eder.

Dinamik URL'ler ve Başlıklar

Dinamik URL'ler @Url ek açıklamasıyla ayarlanır ve çalışma zamanında uç noktanın iletilmesine olanak tanır. Başlıklar @Headers aracılığıyla statik olarak veya @Header parametresi aracılığıyla dinamik olarak belirtilebilir. Tüm isteklerdeki genel başlıklar için, her giden isteğe başlık ekleyen bir OkHttp arabulucusu kullanılır.

Retrofit Nasıl Çalışır?

Retrofit üç aşamada çalışır: API arayüzünü tanımlama, Retrofit örneği oluşturma ve isteği yürütme. Kütüphane, ek açıklamalar ve dönüştürücülere dayanarak çalışma zamanında arayüzün uygulamasını oluşturur.

Talep Yaşam Döngüsü

Bir API yöntemi çağrıldığında, Retrofit ek açıklamalar ve argümanlara dayanarak bir Request nesnesi oluşturur. İstek, yürütme için OkHttp'ye iletilir. Yanıt alındıktan sonra kütüphane, gerekli türe dönüştürme için Converter.Factory'ye iletir. CallAdapter, sonucu asenkron bir sarmalayıcıya sarar. Her aşama özelleştirilebilir.

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 Kurulumu ve Yapılandırması

Retrofit'in kurulumu, Android'in standart derleme sistemi olan Gradle aracılığıyla yapılır. Kütüphane Maven Central üzerinden dağıtılır ve projenin build.gradle dosyasına birkaç bağımlılık eklenmesini gerektirir.

Bağımlılıkları Ekleme

build.gradle dosyasına (modül seviyesi), Retrofit, Gson dönüştürücüsü ve OkHttp için bağımlılıklar ekleyin. Merkezi yönetim için kök build.gradle'da kütüphane sürümlerinin değişkenlere çıkarılması önerilir. Retrofit 2, minimum Android API 21 gerektirir.

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 Örneği Oluşturma

Bir Retrofit örneği Builder aracılığıyla oluşturulur. Zorunlu parametreler: baseUrl ve ConverterFactory. Gereksiz bağlantılar oluşturmaktan kaçınmak için Retrofit ve OkHttpClient için tekil kullanım önerilir. Geliştirme sırasında ağ isteklerinde hata ayıklamayı basitleştirmek için bir logging-interceptor eklenmesi önerilir.

Kotlin projeleri için, API arayüzünde Call türleri yerine suspend işlevleri kullanılması önerilir. Bu, kodu basitleştirir ve coroutines'in yapılandırılmış eşzamanlılığını kullanmayı sağlar. Call'dan suspend'a geçerken, yalnızca arayüzdeki dönüş türünü değiştirmek yeterlidir — kodun geri kalanı otomatik olarak uyum sağlar.

Retrofit Kullanım Örnekleri

Aşağıdaki örnekler, Android uygulamalarında Retrofit ile çalışmanın tipik senaryolarını göstermektedir: basit bir GET isteğinden sunucuya dosya yüklemeye kadar.

Sorgu Parametreleriyle GET İsteği

Sorgu dizesi parametreleriyle basit bir GET isteği temel bir işlemdir. @Query ek açıklaması otomatik olarak URL'ye parametre ekler ve suspend işlevi, ana iç parçacığı engellemeden bir coroutine'den istek çağrısına izin 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övdeli POST İsteği

JSON gövdeli bir POST isteği, nesneyi iletmek için @Body ek açıklamasını kullanır. GsonConverterFactory, User nesnesini otomatik olarak JSON'a serileştirir. Kotlin coroutines, Callback arayüzleri olmadan isteğin arka planda yürütülmesini sağlar.

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)

Multipart ile Dosya Yükleme

@Multipart ek açıklaması @Part ile sunucuya dosya yüklemeyi sağlar. Retrofit, gerekli başlıklarla otomatik olarak bir multipart isteği oluşturur. OkHttp, RequestBody aracılığıyla yükleme ilerlemesini yönetir ve kullanıcıya bir gösterge görüntülenmesine olanak tanır.

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'te Hata Yönetimi ve Arabulucular

Retrofit'te hata yönetimi, OkHttp mekanizmaları ve Kotlin coroutines kombinasyonu üzerine kurulmuştur. OkHttp arabulucuları, istekleri günlüklemeye, kimlik doğrulama başlıkları eklemeye ve uygulama koduna ulaşmadan önce hataları işlemeye olanak tanır.

Merkezi hata yönetimi için, API çağrıları etrafında genellikle sealed class Result şeklinde bir sarmalayıcı oluşturulur. Böyle bir sınıfın iki alt sınıfı vardır: verilerle Success ve bir istisnayla Error. ViewModel, birleşik bir sonuç alır ve her işlevde hata yönetimi kodunu tekrarlamadan ilgili kullanıcı arayüzü durumunu görüntüleyebilir.

Arabulucular iki türde gelir: uygulama arabulucuları isteği sunucuya göndermeden önce değiştirir ve ağ arabulucuları yanıt alındıktan sonra yanıtla çalışır. Örneğin, bir arabulucu 401 alındığında erişim belirteci otomatik olarak yenileyebilir ve geliştirici müdahalesi olmadan yeni belirteçle isteği yeniden deneyebilir.

Interceptor ile İstek Günlükleme

Günlükleme arabulucusu HttpLoggingInterceptor, ağ isteklerinde hata ayıklamak için vazgeçilmez bir araçtır. Logcat'e istek yöntemini, URL'yi, başlıkları, gövdeyi ve yanıt kodunu çıkarır. Günlükleme düzeyi yapılandırılabilir: minimum bilgi için BASIC, başlıklar için HEADERS veya tam içerik için BODY. Üretimde, BASIC kullanmanız veya günlüklemeyi tamamen devre dışı bırakmanız önerilir.

OkHttp'deki arabulucular iki türe ayrılır: isteği değiştirmek için uygulama arabulucuları ve ham ağ verileriyle çalışmak için ağ arabulucuları. Günlükleme arabulucusu otomatik olarak istek ve yanıt ayrıntılarını Logcat'e çıkarır.

Coroutine düzeyinde hata yönetimi, suspend işlev çağrısı etrafında try-catch ile yapılır. Retrofit, 4xx ve 5xx kodları için HttpException, ağ olmadığında UnknownHostException ve zaman aşımı durumunda SocketTimeoutException olarak hataları döndürür. Birleşik işlem için sealed class Result kullanılması önerilir.