Ktor — temel kavramlar, istemci kütüphanesi ve Kotlin Multiplatform

Ktor nedir?

Ktor, JetBrains tarafından geliştirilen Kotlin'de HTTP istemcileri ve sunucuları oluşturmak için bir framework'tür. Geleneksel kütüphanelerin aksine, Ktor en başından itibaren çoklu platform geliştirme için tasarlanmıştır ve Kotlin tarafından desteklenen tüm platformlarda çalışır.

Ktor, Kodein ve Express.js mimarisinden ilham alan bir middleware işleyici yaklaşımı kullanır. Her istek, isteği ve yanıtı değiştirebilen işleyici işlevlerinden oluşan bir pipeline'dan geçer. Bu, katı açıklama tabanlı mimariye sahip kütüphanelerde bulunmayan esneklik sağlar.

Mevcut sürüm Ktor 3.0, Kotlin 2.0, K2 derleyicisi ve geliştirilmiş performansa sahip yeni CIO (Coroutine I/O) motoru için destek içerir. Kütüphane Apache 2.0 lisansı altında dağıtılır ve kısıtlama olmaksızın ticari kullanım için mevcuttur.

Ktor'un istemci tarafı tamamen Kotlin coroutines üzerine inşa edilmiştir ve iş parçacığı engellemesi olmadan verimli async istek yürütme sağlar. Sunucu tarafı, yönlendirme, istek işleme ve WebSocket bağlantılarıyla HTTP sunucuları oluşturmaya olanak tanır.

Ktor bir eklenti mimarisi kullanır: tüm ek özellikler — loglama, serileştirme, kimlik doğrulama — eklentiler aracılığıyla bağlanır. Bu, kütüphaneyi modüler hale getirir ve yalnızca gerekli bileşenlerin bağlanmasına izin vererek son uygulama boyutunu küçültür.

Tüm platformlarda birleşik API sayesinde, geliştiricinin iOS ve Android için farklı HTTP istemcileri öğrenmesi gerekmez. Çoklu platform projesinde, ağ katmanı kodu tamamen paylaşılır ve platforma özgü uygulama HttpClient motorunun arkasında gizlenir. Bu, geliştirme süresini kısaltır ve platform farklılıklarıyla ilgili hata sayısını azaltır.

Ktor'un temel özellikleri

Ktor, onu modern Kotlin projeleri, özellikle çoklu platform projeleri için cazip bir seçim haline getiren bir dizi özellik sunar.

Çoklu platform desteği

Ktor, JVM, Android, iOS, macOS, Windows, Linux, JavaScript ve Wasm üzerinde çalışır. Aynı HTTP istemci kodu değişiklik yapılmadan tüm platformlarda çalışır. Bu, OkHttp veya URLSession'a bağlı kütüphanelere göre önemli bir avantajdır.

Coroutines ile async

Kotlin'deki coroutines, geri aramalar olmadan doğal asenkronluk sağlar. Her istek, herhangi bir coroutine'den çağrılabilen bir suspend işlevidir. Ktor, uzun bağlantılar ve WebSocket için uygun olan Flow aracılığıyla yanıt akışını destekler.

Eklenti mimarisi

Ktor eklentileri bir install bloğu aracılığıyla bağlanır ve ayrı ayrı yapılandırılır. Ana eklentiler: serileştirme için ContentNegotiation, loglama için Logging, kimlik doğrulama için Auth ve çift yönlü iletişim için WebSockets. Her eklenti bağımsız olarak etkinleştirilebilir veya devre dışı bırakılabilir.

Hata işleme ve zaman aşımları

Ktor'da hata işleme istisnalara dayanır. ClientRequestException sınıfı 4xx kodları için, ServerResponseException 5xx için ve IOException ağ hataları için fırlatılır. Zaman aşımları, bağlantı, okuma ve yazma için bekleme süresini ayarlayan HttpTimeout eklentisi aracılığıyla yapılandırılır. Yeniden denemeler için, deneme sayısı ve gecikme ayarlarıyla Retry eklentisi kullanılır.

Ktor nasıl çalışır?

Ktor, her isteğin bir işleyici zincirinden geçtiği pipeline mimarisini kullanır. İstemci, yüklenmiş eklentilerle bir HttpClient yapılandırması oluşturur ve get veya post çağrılarının her biri, bağlanma sırasına göre eklentilerden geçer.

HttpClient mimarisi

HttpClient nesnesi, platforma özgü bir motorla oluşturulur: JVM ve Android için CIO, iOS ve macOS için Darwin, Android uyumluluğu için OkHttp, tarayıcı için Js. Motor açıkça seçilebilir veya otomatik seçime bırakılabilir. Her istek, yanıt gövdesini, başlıkları ve durumu içeren bir HttpResponse döndürür.

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

suspend fun fetchUsers(): List<User> {
    return client.get("https://api.example.com/users").body()
}

Ktor kurulumu ve yapılandırması

Ktor kurulumu Gradle veya Maven aracılığıyla yapılır. Çoklu platform projeleri için bağımlılıklar her hedef için sourceSets içinde belirtilir. Ktor, Maven Central aracılığıyla dağıtılır.

Gradle ile bağlantı

build.gradle.kts dosyasına, ortak kod için ktor-client-core bağımlılığını ve belirli platform için bir motor ekleyin. Ktor sürümü, gradle.properties içindeki bir değişken aracılığıyla ayarlanır. Ktor 3.x, Kotlin 2.0+ gerektirir ve K2 derleyicisini destekler.

val ktorVersion = "3.0.3"

dependencies {
    implementation("io.ktor:ktor-client-core:$ktorVersion")
    implementation("io.ktor:ktor-client-cio:$ktorVersion")
    implementation("io.ktor:ktor-client-content-negotiation:$ktorVersion")
    implementation("io.ktor:ktor-serialization-kotlinx-json:$ktorVersion")
    implementation("io.ktor:ktor-client-logging:$ktorVersion")
}

iOS için yapılandırma

iOS için, yerel URLSession'ı sarmalayan Darwin motoru kullanılır. Kotlin Multiplatform'da bu, maksimum performans ve iOS sistem önbellekleme mekanizmalarıyla entegrasyon sağlar. Motor, iOS sourceSet'inde ayrı bir bağımlılık olarak eklenir.

Ktor'un önemli bir özelliği, ContentNegotiation aracılığıyla farklı serileştirme biçimlerini desteklemesidir. JSON'a ek olarak, eklenti Protobuf, CBOR, XML ve özel biçimleri destekler. Serileştirme için kotlinx.serialization veya Jackson kütüphaneleri kullanılır ve geliştirici istek kodunu değiştirmeden bunlar arasında geçiş yapabilir.

Ktor kullanım örnekleri

Aşağıdaki örnekler, Ktor istemcisiyle çalışmanın tipik senaryolarını gösterir: temel GET isteği, veri gönderme ve çoklu platform koduyla çalışma.

JSON deserileştirme ile GET isteği

Yanıtın bir data class'a otomatik olarak deserileştirildiği basit bir GET isteği. Ktor, JSON'u nesnelere dönüştürmek için kotlinx.serialization ile ContentNegotiation eklentisini kullanır. Kod kısa ve tür güvenlidir.

@Serializable
data class Post(
    val id: Int,
    val title: String,
    val body: String
)

suspend fun getPosts(): List<Post> {
    val response = client.get("https://jsonplaceholder.typicode.com/posts")
    return response.body()
}

JSON gövdesi ile POST isteği

Ktor'da POST isteği, contentType ve setBody ile post yöntemi aracılığıyla bir data class'ı JSON gövdesi olarak gönderir. ContentNegotiation eklentisi nesneyi otomatik olarak bir JSON dizesine serileştirir. Yanıt eşzamanlı veya eşzamansız olarak işlenebilir.

suspend fun createPost(): Post {
    val newPost = Post(
        id = 0,
        title = "Yeni gönderi",
        body = "Gönderi içeriği"
    )
    val response = client.post("https://jsonplaceholder.typicode.com/posts") {
        contentType(ContentType.Application.Json)
        setBody(newPost)
    }
    return response.body()
}

Multipart ile dosya yükleme

Ktor'daki submitFormWithBinaryData yöntemi, multipart biçiminde dosya ve form göndermeye olanak tanır. Ktor verileri otomatik olarak parçalara ayırır ve başlıklar ekler. İlerlemeyi izlemek için, gönderilen verilerin baytlarını alan onUpload kullanılır.

suspend fun uploadFile(fileBytes: ByteArray) {
    client.submitFormWithBinaryData(
        url = "https://api.example.com/upload",
        formData = formData {
            append("file", fileBytes, Headers.build {
                append(HttpHeaders.ContentType, "image/png")
                append(HttpHeaders.ContentDisposition, "filename=\"photo.png\"")
            })
        }
    )
}

Ktor veya Retrofit: hangisi seçilmeli?

Seçim, proje mimarisine ve çoklu platform gereksinimlerine bağlıdır. Retrofit, yalnızca Android projeleri için standart olmaya devam ederken, Ktor Kotlin Multiplatform için en iyi seçimdir.

Ktor ayrıca WebSocket ve SSE (Server-Sent Events) için yerleşik destek sağlayarak onu gerçek zamanlı uygulamalar için uygun hale getirir. Retrofit, WebSocket'i doğrudan desteklemez — bunun için ayrı bir OkHttp WebSocket kütüphanesi gerekir. Ktor, her eklentinin bir işlevden sorumlu olduğu eklenti sistemi sayesinde farklı ortamlar için yapılandırması da daha kolaydır.

Ktor'da kimlik doğrulama

Ktor'daki Auth eklentisi, temel kimlik doğrulama, Bearer tokenları, Digest ve OAuth2'yi destekler. Kimlik doğrulama yapılandırması bildirimsel olarak yapılır: geliştirici sağlayıcıyı, token kaynağını ve kapsamı belirtir. Ktor, isteklere otomatik olarak kimlik doğrulama başlıkları ekler ve token süresi dolduğunda yenileyebilir.

Bir proje iOS ve Android'de paylaşılan kodla Kotlin Multiplatform kullanıyorsa, Ktor ek katmanlar olmadan her iki platformda da çalışan tek seçenektir. Retrofit, OkHttp ve JVM'ye sıkı sıkıya bağlıdır ve bu da onu iOS için uygunsuz hale getirir.

Yalnızca Android projeleri için Retrofit daha olgun bir API, daha fazla sayıda dönüştürücü ve OkHttp interceptoru sağlar. Ktor bu senaryoda da çalışır, ancak eklenti ekosistemi daha az kapsamlıdır. Her iki kütüphane de coroutines'i destekler ve karşılaştırılabilir performans sunar.