Retrofit: nedir, Android HTTP istemcisinin özellikleri

Retrofit nedir?

Retrofit, Square tarafından geliştirilen, Android platformunda REST API ile tür belirtilmiş etkileşim için bir kütüphanedir. Ek açıklamalarla Java veya Kotlin arayüzleri aracılığıyla HTTP isteklerini tanımlamanın bildirimsel bir yolunu sunar ve manuel JSON ayrıştırma ve HTTP bağlantı yönetimi ihtiyacını tamamen ortadan kaldırır.

Kütüphane, 2013 yılında AsyncTask ve HttpURLConnection gibi hantal çözümlere alternatif olarak ortaya çıktı. 2025 itibarıyla Retrofit, basitliği ve tür güvenliği sayesinde Android uygulamalarında ağ iletişimi için fiili standart olmaya devam etmektedir. JetBrains Developer Ecosystem 2024 anketine göre, Android geliştiricilerin %65'inden fazlası ticari projelerde Retrofit kullanmaktadır.

Retrofit'in alternatiflerden temel farkı bildirimsel yaklaşımdır: geliştirici ne yapılacağını (hangi endpoint'in çağrılacağı, hangi parametrelerin iletileceği) tanımlar, nasıl yapılacağını değil (bağlantının nasıl açılacağı, InputStream'in nasıl okunacağı, JSON'ın nasıl ayrıştırılacağı). Bu, HttpURLConnection'un manuel kullanımına kıyasla boilerplate kodunu %60–70 oranında azaltır.

Retrofit nasıl çalışır

Çalışma prensibi Retrofit, Java dinamik proxy'lerine dayanır. Geliştirici, ek açıklamalı bir arayüzün yöntemini çağırdığında, Retrofit, Proxy.newProxyInstance mekanizması aracılığıyla çağrıyı yakalar ve bir HTTP isteğine dönüştürür. Tüm süreç, derleme zamanında kod oluşturulmadan çalışma zamanında gerçekleşir.

Bir Retrofit.Builder örneği oluşturulurken temel URL ve dönüştürücü fabrikası belirtilir. Builder, OkHttpClient'ı yapılandırır — zaman aşımlarını, interceptors'ları, bağlantı havuzunu ve önbelleği ayarlar. create(Class) yöntemi, arayüz uygulamasını oluşturur ve normal bir sınıf gibi çağrılabilen bir proxy nesnesi döndürür.

İstek yürütme zinciri şöyle görünür: ek açıklamalar HTTP yöntemini çıkarır, parametreler URL veya istek gövdesine eklenir, dönüştürücü gövdeyi serileştirir, OkHttp isteği yürütür, dönüştürücü yanıtı seri durumdan çıkarır ve sonuç belirtilen türde döndürülür. Her aşama izole edilmiştir ve özel bir uygulamayla değiştirilebilir, örneğin test için OkHttpClient'ı MockWebServer ile değiştirmek veya API değiştirirken dönüştürücüyü değiştirmek.

Önemli bir özellik — Retrofit, veri akışını doğrudan desteklemez. Akış için, arayüz yönteminin dönüş türü olarak OkHttp ResponseBody kullanılır. Retrofit ayrıca istek iptalini otomatik olarak yönetmez — iptal etmek için Call'a bir referans tutmak ve cancel() çağırmak gerekir. Kotlin'de suspend işlevleriyle, üst coroutine iptal edildiğinde istek iptali otomatik olarak gerçekleşir.

Call nesnesinin yaşam döngüsü

Call<T>, tek bir HTTP isteğini temsil eden bir nesnedir. Yürütmeden (execute veya enqueue) sonra bir Call yeniden kullanılamaz — tekrarlanan bir istek için arayüz yöntemi çağrılarak yeni bir Call oluşturulmalıdır. Bu, aynı isteğin yanlışlıkla iki kez gönderilmesini önler, bu da sunucuda yinelenen işlemlere yol açabilir.

Kotlin'de, Call yerine suspend işlevleri kullanılır ve bunlar isteğin yaşam döngüsünü otomatik olarak yönetir. Retrofit, yürütmeyi Dispatchers.IO'ya geçirir ve sonucu coroutine'e döndürür. Bu, Call ve Callback sürümüne kıyasla kodu %30–40 oranında azaltır.

HTTP yöntemleri için Retrofit ek açıklamaları

Ek açıklamalar, Retrofit'te HTTP isteklerini yapılandırmanın ana mekanizmasıdır. Her ek açıklama, standart bir HTTP yöntemine karşılık gelir ve endpoint'e göreli bir yol kabul eder. Retrofit, GET, POST, PUT, DELETE, PATCH, HEAD ve OPTIONS'ı destekler.

İstek parametresi ek açıklamaları

@Path, bir URL segmentine değer ekler: @Path("id") Int id, yoldaki {id}'yi değiştirir. @Query, bir sorgu parametresi ekler: @Query("page") Int page, ?page=5'e dönüşür. @Body, seçilen dönüştürücü aracılığıyla otomatik serileştirme ile istek gövdesinde bir nesne iletir. @Header ve @Headers, HTTP başlıklarını yönetir — statik veya dinamik.

Bu ek açıklamaları birleştirerek herhangi bir REST endpoint'i tanımlanabilir. Örneğin, POST /api/users/{id}/posts?limit=10 endpoint'i için @POST, id için @Path, limit için @Query ve iletilen nesne için @Body gerekir. Retrofit otomatik olarak doğru bir HTTP isteği oluşturacaktır. Ayrıca @Url (dinamik URL), @Field (form kodlu gövde), @Part ve @PartMap (dosyalı çok parçalı istekler için) desteklenir.

Kotlin'de Retrofit kod örnekleri

Pratik bir örneğe bakalım — GitHub API'si için bir arayüz. Depo listesini almak için bir yöntemle bir Kotlin arayüzü oluşturulur. Repo veri sınıfı, JSON yanıt yapısını tanımlar.

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>
}

Arayüz tanımlandıktan sonra, Builder aracılığıyla bir Retrofit örneği oluşturulur. Temel URL, dönüştürücü ve OkHttpClient bir kez yapılandırılır ve bağımlılık enjeksiyonu yoluyla yeniden kullanılır.

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 sarmalayıcısıyla yanıt işleme

HTTP durum kodlarının esnek bir şekilde işlenmesi için Response<T> sarmalayıcısını kullanın. 4xx ve 5xx hatalarında istisna oluşturmadan yanıt koduna, başlıklara ve gövdeye erişim sağlar. Bu, try-catch olmadan 404 ve 500'ü işlemeye olanak tanır.

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", "Error: ${response.code()}")
}

Retrofit'te dönüştürücüler ve serileştirme

Dönüştürücüler, nesneleri HTTP gövdesine ve geri dönüştürmekten sorumlu Retrofit bileşenleridir. Retrofit, serileştirmeyi çekirdeğine gömmez — bunun yerine Converter.Factory aracılığıyla modüler bir yaklaşım kullanır ve herhangi bir serileştirme kütüphanesinin bağlanmasına izin verir.

En popüler dönüştürücü, Gson kütüphanesini temel alan Google'ın GsonConverterFactory'sidir. Çoğu projede çalışır, özel TypeAdapter ve JsonDeserializer'ı destekler. Ancak Gson, yansıma kullanır ve Kotlin'in null güvenliğine saygı göstermez, bu da beklenmeyen null alanlarda NPE'ye yol açabilir.

Bir alternatif, Square'in MoshiConverterFactory'sidir: türler konusunda daha katı, daha iyi Kotlin desteği (null güvenliği, varsayılan değerler) ve yansıma yok. Saf Kotlin projeleri için, derleme zamanında @Serializable ek açıklamalarıyla çalışan Kotlinx Serialization Converter idealdir. Yansıma kullanmaz, sealed class, varsayılan değerler ve çoklu platformu destekler.

Dönüştürücü seçimi performansı ve tür güvenliğini etkiler. Gson, özel yapılandırma olmadan Kotlin'in null olmayan alanına null seri durumdan çıkarabilir ve erişimde NPE'ye neden olabilir. Moshi, bu sorunu @Json(name) ek açıklaması ve failOnUnknown aracılığıyla çözer. Kotlinx Serialization en güvenlisidir — derleme zamanında kod oluşturarak çalışma zamanı tür hatalarını tamamen ortadan kaldırır.

Retrofit ile çalışırken yaygın hatalar

Suspend işlevlerinde HTTP hata işleme eksikliği en yaygın sorundur. Sunucu 4xx veya 5xx döndürürse, Retrofit HttpException fırlatır. Try-catch olmadan uygulama çöker. Dönüş türü olarak Response<T> kullanmak, gövdeye erişmeden önce isSuccessful'i kontrol etmeye izin vererek bu sorunu çözer.

Yanlış önbellek yapılandırması aşırı trafiğe yol açar. Retrofit, yanıtları kendi başına önbelleğe almaz — bu görevi OkHttpClient, Cache aracılığıyla gerçekleştirir. Önbellek olmadan, veri değişmemiş olsa bile her istek tamamen yürütülür. OkHttpClient'a 10 MB'lık bir önbellek eklemek, aynı bilginin tekrarlanan isteklerinde trafiği %40–60 oranında azaltır.

Her istek için Retrofit oluşturmak yeni başlayanların yaygın bir hatasıdır. Retrofit.Builder, çalışma zamanında proxy sınıfı oluşturmayı içeren kaynak yoğun bir işlemdir. Doğru uygulama, tek bir Retrofit örneği oluşturmak ve bunu DI çerçeveleri aracılığıyla yeniden kullanmaktır. Hilt, Koin veya Dagger, tüm uygulama için tek bir Retrofit örneği sağlayarak bellekten tasarruf sağlar ve istekleri hızlandırır.

Yetkilendirme için Interceptor'ı göz ardı etmek dördüncü sorundur. Her çağrıya manuel olarak Authorization başlığı eklemek yerine, OkHttpClient'ta genel bir Interceptor yapılandırın. Interceptor her isteği yakalar, Bearer token'ı ekler ve Authenticator, 401 yanıtını işleyerek token'ı yeniler ve isteği otomatik olarak tekrarlar. Bu, kimlik doğrulama mantığını merkezileştirir.