Ktor: nedir, asenkron HTTP istemcisinin özellikleri

Ktor Nedir?

Ktor, JetBrains tarafından oluşturulan Kotlin'de asenkron sunucu ve istemci uygulamaları oluşturmak için bir framework'tür. Ktor Client, framework'ün istemci tarafı parçasıdır ve Kotlin coroutine'leri, çoklu platform (JVM, Native, JS) ve modüler eklenti tabanlı mimari için tam destek sağlayan bir HTTP istemcisi sunar.

Ktor, 2018 yılında Kotlin öncelikli projeler için Retrofit ve OkHttp'ye bir alternatif olarak ortaya çıktı. Ek açıklamalarla Java yaklaşımını taşıyan Retrofit'in aksine, Ktor Client istek yapılandırması için Kotlin DSL kullanır — ek açıklamalar ve yansıma olmadan. Bu, kodu Kotlin geliştiricileri için daha okunabilir ve tip güvenli hale getirir.

2024 Kotlin Multiplatform anketine göre, Ktor Client, Kotlin Multiplatform Mobile (KMM) projelerinin %35'inde kullanılmakta ve Kotlin topluluğunda OkHttp'den sonra en popüler ikinci HTTP istemcisi olmaktadır. Ktor, çoklu platform desteği ve Kotlin ekosistemiyle yerel entegrasyonun önemli olduğu projelerde tercih edilir.

Ktor Client Nasıl Çalışır

Ktor Client Mimarisi, eklentilerden oluşan bir pipeline'a dayanır. Her istek, isteği, yanıtı değiştirebilen veya günlük kaydı, sıkıştırma, serileştirme, kimlik doğrulama gibi yan eylemler gerçekleştirebilen yüklü eklentiler dizisinden geçer.

HttpClient { } DSL bloğu aracılığıyla bir HTTP istemcisi oluştururken, motoru (OkHttp, Android, CIO, Darwin) belirtir ve eklentileri yüklersiniz. Her motor, belirli bir platform için düşük seviyeli istek göndermeyi uygular: Android'de OkHttp motoru, iOS'te — Darwin (URLSession), Desktop'ta — CIO (Coroutine I/O) kullanılır. HttpClient geçerli platform için otomatik olarak en uygun motoru seçer.

Ktor Client'te bir istek, bir suspend işlevi aracılığıyla yürütülür, bu da coroutine'lerle tam entegrasyon anlamına gelir. Geri arama yok, RxJava veya LiveData yok — yalnızca iş parçacığını engellemeden asenkron çalışan suspend ile sıralı kod.

İstek işleme pipeline'ı

Ktor pipeline'ı aşamalardan oluşur: önce istek yüklü eklentilerden geçer (örn. JSON için ContentNegotiation, günlükler için Logging), ardından motor HTTP isteğini yürütür ve yanıt, serileştirme çözme için yeniden eklentilerden geçer. Her eklenti, pipeline coroutine'inde yürütülen bir suspend işlevidir.

Ktor pipeline'ının önemli bir avantajı, koşullu işleme yeteneğidir. Bir eklenti, URL'yi veya istek başlıklarını kontrol edebilir ve koşul karşılanmazsa işlemeyi atlayabilir. Örneğin, gzip ile ContentEncoding yalnızca Content-Encoding: gzip başlığını içeren yanıtlara uygulanır ve Auth yalnızca korunan uç noktalar için tetiklenir, genel API'leri etkilemez.

Bu pipeline yaklaşımı, eklentileri esnek bir şekilde birleştirmenize olanak tanır: JSON ile ContentNegotiation yükleyebilir, Bearer token ile Auth ekleyebilir, ContentEncoding sıkıştırması ve HttpTimeout'u etkinleştirebilirsiniz — ve hepsi doğru sırada birlikte çalışır. Eklenti yükleme sırası önemlidir: ilk yüklenen eklenti, isteği diğerlerinden önce işler.

Ktor Client Eklentileri

Eklentiler, Ktor'un Retrofit ek açıklamalarının ve OkHttp interceptor'larının yerini alan modüler genişletme sistemidir. Her eklenti belirli bir görevi çözer ve HttpClient bloğundaki install() işlevi aracılığıyla yüklenir. Ktor, yerleşik eklentiler sağlar ve ayrıca özel eklentiler oluşturulmasına izin verir.

Özel eklentiler

Belirli görevler için createClientPlugin aracılığıyla özel bir eklenti oluşturulur. Eklenti, isteği (onRequest), yanıtı (onResponse) engelleyebilir veya hataları (onError) işleyebilir. Bu, OkHttp'nin Interceptor'ını tamamen değiştirir, ancak yazılan Kotlin API ve suspend işlev desteği ile.

Özel eklentiler, metrik ekleme, otomatik yeniden deneme mantığı, istek izleme veya uç noktaların A/B testi için kullanışlıdır. OkHttp interceptor'larının aksine, Ktor eklentileri Kotlin'de yazılır ve coroutine bağlamında çalışır, hata ve zaman aşımı işlemeyi basitleştirir.

İstek hata ayıklaması için Logging eklentisi ALL, HEADERS veya BODY seviyesinde kullanılır. Logging, yöntemi, URL'yi, durumu, başlıkları ve istek ile yanıtın gövdesini çıktılar. OkHttp'nin HttpLoggingInterceptor'ından farklı olarak, Ktor Logging asenkron çalışır ve yapılandırmayı değiştirmek için uygulamayı durdurmadan günlük seviyesine (ERROR, WARN, INFO, DEBUG) göre filtreleyecek şekilde yapılandırılabilir.

Kotlin'de Ktor Client Kod Örnekleri

Ktor Client kullanarak temel bir GET isteğine bakalım. JSON için ContentNegotiation eklentisi yüklenmiş bir HttpClient oluşturulur. İstek, suspend işlevi get() aracılığıyla yürütülür ve sonuç otomatik olarak bir veri sınıfına serileştirme çözülür.

data class User(
    val login: String,
    val id: Int,
    val avatarUrl: String
)

val client = HttpClient {
    install(ContentNegotiation) {
        json(Json {
            ignoreUnknownKeys = true
        })
    }
}

suspend fun getUser(): User {
    return client.get("https://api.github.com/users/octocat").body()
}

Gövdeli POST isteği için contentType() ve body() ile post() işlevi kullanılır. Ktor, yüklenen ContentNegotiation aracılığıyla nesneyi otomatik olarak JSON'a serileştirir. DSL stili, kodu sıralı ve okunabilir kılar.

data class CreateRepo(
    val name: String,
    val description: String,
    val private: Boolean
)

suspend fun createRepo(): Unit {
    val repo = CreateRepo(
        name = "my-project",
        description = "Sample project",
        private = false
    )
    client.post("https://api.github.com/user/repos") {
        contentType(ContentType.Application.Json)
        setBody(repo)
    }
}

Zaman aşımlarını ve başlıkları yapılandırma

HttpTimeout ve DefaultRequest, yapılandırma için iki anahtar eklentidir. HttpTimeout zaman sınırlarını belirler ve DefaultRequest, her çağrıda kod tekrarını ortadan kaldırarak tüm istekler için başlıkları ve URL parametrelerini belirtir.

val client = HttpClient {
    install(HttpTimeout) {
        connectTimeoutMillis = 15000
        requestTimeoutMillis = 30000
    }
    install(DefaultRequest) {
        url("https://api.github.com/")
        header("Accept", "application/json")
    }
}

Ktor Çoklu Platform Desteği

Çoklu platform, Ktor'un OkHttp ve Retrofit'e göre ana avantajıdır. Ktor Client, JVM (Android, Sunucu), Native (iOS, macOS, Windows, Linux) ve JS (Tarayıcı) üzerinde çalışır. Aynı HTTP istemci kodu, değişiklik yapılmadan tüm platformlarda çalışır ve bu, özellikle Kotlin Multiplatform projeleri için değerlidir.

Her platform için Ktor kendi motorunu kullanır. Android'de varsayılan olarak OkHttp motoru kullanılır ve OkHttp ekosistemiyle tam uyumluluk sağlar. iOS'te URLSession tabanlı DarwinEngine kullanılır. Sunucu için — CIOEngine (Coroutine I/O). Motor açıkça belirtilebilir: HttpClient(OkHttp) { } veya HttpClient(Darwin) { }.

Bir motor seçerken yeteneklerini göz önünde bulundurun: OkHttp motoru HTTP/2 ve bağlantı havuzlamayı destekler, DarwinEngine yerel iOS ağ entegrasyonu ve arka plan URLSession oturumları sağlar, CIOEngine harici bağımlılıklar olmadan saf bir coroutine uygulamasıdır. Web hedefleri için fetch API aracılığıyla çalışan JsEngine veya BrowserEngine kullanılır.

Tüm platformlarda birleşik bir API sayesinde, veri yükleme kodu Android, iOS ve Desktop'ta aynı görünür. Bu, Retrofit (Android) ve URLSession (iOS) üzerindeki ayrı uygulamalara kıyasla KMM projelerinde kod tekrarını %60–80 oranında azaltır. Eklentiler de değişiklik yapılmadan tüm platformlarda çalışır.

Ktor ile Çalışırken Sık Yapılan Hatalar

HttpClient kapatmayı ihmal etmek Ktor'da sık yapılan bir hatadır. HttpClient, Closeable'ı uygular ve uygulama sona erdiğinde client.close() ile kapatılmalıdır. Android'de bu, Activity'nin onDestroy() veya ViewModel.onCleared() yönteminde yapılır. Kapatılmayan bir istemci, coroutine ve motor iş parçacığı sızıntılarına yol açar.

Yanlış eklenti sırası istek işlemeyi bozabilir. Örneğin, ContentNegotiation, içerik türünün doğru uygulanması için DefaultRequest'ten önce yüklenmelidir. Logging'in, tüm değişikliklerden sonra isteğin son sürümünü günlüğe kaydetmek için en son yüklenmesi önerilir. Eklentiler beklenmedik davranırsa sırayı deneyin.

Suspend işlevlerinde istisna işleme eksikliği. Ktor, ağ hataları için IOException ve HTTP 4xx durumları için ClientRequestException fırlatır. get(), post() ve diğer yöntemlere yapılan her çağrı için try-catch bloğu zorunludur. Her yöntemde try-catch'i tekrarlamadan genel hata işleme için HttpClient bloğunda HttpResponseValidator kullanın.