Ktor — əsas anlayışlar, müştəri kitabxanası və Kotlin Multiplatform

Ktor nədir?

Ktor — bu, JetBrains şirkəti tərəfindən hazırlanmış Kotlin dilində HTTP müştəriləri və serverləri yaratmaq üçün freymvorkdur. Ənənəvi kitabxanalardan fərqli olaraq, Ktor əvvəldən multiplatforma inkişafı üçün dizayn edilmişdir və Kotlin tərəfindən dəstəklənən bütün platformalarda işləyir.

Ktor Kodein və Express.js arxitekturasından ilhamlanan aralıq emalçılar yanaşmasından istifadə edir. Hər sorğu sorğu və cavabı dəyişdirə bilən emalçı funksiyalarının boru kəmərindən keçir. Bu, annotasiyalara əsaslanan sərt arxitekturalı kitabxanalarda olmayan çevikliyi təmin edir.

Cari versiya Ktor 3.0 Kotlin 2.0, K2 kompilyatoru və təkmilləşdirilmiş performansa malik yeni CIO (Coroutine I/O) mühərriki üçün dəstək əhatə edir. Kitabxana Apache 2.0 lisenziyası altında yayılır və məhdudiyyətsiz kommersiya istifadəsi üçün əlçatandır.

Ktor-un müştəri hissəsi tamamilə Kotlin korutinləri üzərində qurulmuşdur ki, bu da ipləri bloklamadan səmərəli asinxron sorğu icrasını təmin edir. Server hissəsi marşrutlaşdırma, sorğuların işlənməsi və WebSocket bağlantıları ilə HTTP serverləri yaratmağa imkan verir.

Ktor plagin arxitekturasından istifadə edir: bütün əlavə funksiyalar — loqlama, serializasiya, autentifikasiya — plaginlər vasitəsilə qoşulur. Bu, kitabxananı modul edir və yalnız zəruri komponentləri qoşmağa imkan verir, nəticədə tətbiqin ölçüsünü azaldır.

Bütün platformalarda vahid API sayəsində tərtibatçı iOS və Android üçün fərqli HTTP müştərilərini öyrənmək məcburiyyətində deyil. Multiplatforma layihəsində şəbəkə qatının kodu tamamilə ümumidir və platforma spesifik tətbiq HttpClient mühərrikinin arxasında gizlənir. Bu, inkişaf müddətini qısaldır və platforma fərqləri ilə bağlı səhvlərin sayını azaldır.

Ktor-un əsas imkanları

Ktor müasir Kotlin layihələri, xüsusilə multiplatforma layihələri üçün cəlbedici seçim edən funksiyalar dəsti təqdim edir.

Multiplatforma dəstəyi

Ktor JVM, Android, iOS, macOS, Windows, Linux, JavaScript və Wasm-də işləyir. HTTP müştərisinin eyni kodu bütün platformalarda dəyişiklik olmadan işləyir. Bu, OkHttp və ya URLSession-a bağlı kitabxanalarla müqayisədə əsas üstünlükdür.

Korutinlər üzərində asinxronluq

Korutinlər Kotlin geri çağırışlar olmadan təbii asinxronluğu təmin edir. Hər sorğu istənilən korutindən çağırıla bilən suspend-funksiyadır. Ktor uzun bağlantılar və WebSocket üçün əlverişli olan Flow vasitəsilə cavabların axınını dəstəkləyir.

Plagin arxitekturası

Plaginlər Ktor-da install bloku vasitəsilə qoşulur və ayrıca konfiqurasiya edilir. Əsas plaginlər: serializasiya üçün ContentNegotiation, loqlama üçün Logging, autentifikasiya üçün Auth və ikitərəfli əlaqə üçün WebSockets. Hər plagin müstəqil olaraq aktivləşdirilə və ya söndürülə bilər.

Xəta idarəetməsi və vaxt aşımları

Xəta idarəetməsi Ktor-da istisnalara əsaslanır. ClientRequestException sinfi 4xx kodlarında, ServerResponseException 5xx-də, IOException isə şəbəkə xətalarında atılır. Vaxt aşımları HttpTimeout plagini vasitəsilə konfiqurasiya edilir, bu da qoşulma, oxuma və yazma gözləmə müddətini təyin edir. Təkrar cəhdlər üçün Retry plagini cəhd sayı və gecikmə parametrləri ilə istifadə olunur.

Ktor necə işləyir?

Ktor boru kəməri arxitekturasından istifadə edir, burada hər sorğu emalçılar zəncirindən keçir. Müştəri quraşdırılmış plaginlərlə HttpClient konfiqurasiyası yaradır və hər get və ya post metodu çağırışı plaginlərdən onların qoşulma sırası ilə keçir.

HttpClient arxitekturası

HttpClient obyekti platforma üçün spesifik mühərriklə yaradılır: JVM və Android üçün CIO, iOS və macOS üçün Darwin, Android uyğunluğu üçün OkHttp, brauzer üçün Js. Mühərrik açıq şəkildə seçilə bilər və ya avtomatik seçim buraxıla bilər. Hər sorğu cavab mətnini, başlıqları və statusu ehtiva edən HttpResponse qaytarı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-un qurulması və konfiqurasiyası

Qurulması Ktor Gradle və ya Maven vasitəsilə həyata keçirilir. Multiplatforma layihələrində asılılıqlar hər target üçün sourceSets-də göstərilir. Ktor Maven Central vasitəsilə yayılır.

Gradle vasitəsilə qoşulma

build.gradle.kts-də ümumi kod üçün ktor-client-core asılılığını və konkret platforma üçün mühərrik əlavə edin. Ktor versiyası gradle.properties-də dəyişən vasitəsilə təyin edilir. Ktor 3.x Kotlin 2.0+ tələb edir və K2 kompilyatorunu dəstəkləyir.

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 üçün konfiqurasiya

iOS üçün nativ URLSession-ı bükən Darwin mühərriki istifadə olunur. Kotlin Multiplatform-da bu, maksimal performans və iOS sistem keşləmə mexanizmləri ilə inteqrasiya əldə etməyə imkan verir. Mühərrik iOS sourceSet-də ayrıca asılılıq olaraq əlavə edilir.

Ktor-un vacib xüsusiyyəti — ContentNegotiation vasitəsilə müxtəlif serializasiya formatlarının dəstəklənməsidir. JSON-dan əlavə, plagin Protobuf, CBOR, XML və xüsusi formatları dəstəkləyir. Serializasiya üçün kotlinx.serialization və ya Jackson kitabxanaları istifadə olunur və tərtibatçı sorğu kodunu dəyişmədən onlar arasında keçid edə bilər.

Ktor-dan istifadə nümunələri

Nümunələr aşağıda Ktor müştərisi ilə işin tipik ssenarilərini nümayiş etdirir: əsas GET sorğusu, məlumat göndərmə və multiplatforma kodu ilə iş.

JSON deserializasiyası ilə GET sorğusu

Sadə GET sorğusu cavabın avtomatik deserializasiyası ilə data-sinifə. Ktor JSON-u obyektlərə çevirmək üçün kotlinx.serialization ilə ContentNegotiation plagindən istifadə edir. Kod yığcam və tip təhlükəsizdir.

@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övdəsi ilə POST sorğusu

Ktor-da POST sorğusu contentType və setBody ilə post metodu vasitəsilə data-sinifi JSON gövdəsi olaraq göndərir. ContentNegotiation plagini avtomatik olaraq obyekti JSON sətri serializasiya edir. Cavab sinxron və ya asinxron işlənə bilər.

suspend fun createPost(): Post {
    val newPost = Post(
        id = 0,
        title = "Yeni post",
        body = "Postun məzmunu"
    )
    val response = client.post("https://jsonplaceholder.typicode.com/posts") {
        contentType(ContentType.Application.Json)
        setBody(newPost)
    }
    return response.body()
}

Faylın Multipart vasitəsilə yüklənməsi

Ktor-da submitFormWithBinaryData metodu faylları və formaları multipart formatında göndərməyə imkan verir. Ktor avtomatik olaraq məlumatları hissələrə ayırır və başlıqlar əlavə edir. Proqresin izlənməsi üçün göndərilən məlumatların baytlarını alan onUpload istifadə olunur.

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 və ya Retrofit: nə seçməli?

Seçim Ktor və Retrofit arasında layihənin arxitekturasından və multiplatformalıq tələblərindən asılıdır. Retrofit yalnız Android layihələri üçün standart olaraq qalır, Ktor isə Kotlin Multiplatform üçün daha yaxşı seçimdir.

Ktor həmçinin WebSocket və SSE (Server-Sent Events) üçün daxili dəstək təqdim edir ki, bu da onu real vaxt tətbiqləri üçün əlverişli edir. Retrofit WebSocket-i birbaşa dəstəkləmir — bunun üçün ayrıca OkHttp WebSocket kitabxanası tələb olunur. Ktor həmçinin hər plaginin bir funksiyaya cavabdeh olduğu plagin sistemi sayəsində müxtəlif mühitlər üçün daha asan konfiqurasiya edilir.

Ktor-da autentifikasiya

Ktor-da Auth plagini əsas autentifikasiya, Bearer tokenləri, Digest və OAuth2 dəstəkləyir. Autentifikasiya konfiqurasiyası deklarativ şəkildə aparılır: tərtibatçı provayderi, token mənbəyini və fəaliyyət sahəsini göstərir. Ktor avtomatik olaraq sorğulara autentifikasiya başlıqlarını əlavə edir və tokenin müddəti bitdikdə onu yeniləyə bilər.

Layihə iOS və Android-də ümumi kodla Kotlin Multiplatform istifadə edirsə, Ktor əlavə qatlar olmadan hər iki platformada işləyən yeganə seçimdir. Retrofit sərt şəkildə OkHttp və JVM-ə bağlıdır ki, bu da onu iOS üçün yararsız edir.

Yalnız Android layihələri üçün Retrofit daha yetkin API, daha çox konverter və OkHttp interceptorları təmin edir. Ktor bu ssenaridə də işləyir, lakin onun plagin ekosistemi daha az genişdir. Hər iki kitabxana korutinləri dəstəkləyir və müqayisə edilə bilən performans təmin edir.