Ktor: bu nədir, asinxron HTTP müştərisinin xüsusiyyətləri

Ktor nədir?

Ktor JetBrains şirkəti tərəfindən yaradılmış Kotlin dilində asinxron server və müştəri tətbiqləri qurmaq üçün freymvorkdur. Ktor Client — freymvorkun müştəri hissəsidir, Kotlin korutinləri, çoxplatformalılıq (JVM, Native, JS) və plaginlər üzərində modul arxitekturası ilə HTTP müştərisi təmin edir.

Ktor 2018-ci ildə Kotlin-first layihələri üçün Retrofit və OkHttp-ya alternativ olaraq ortaya çıxdı. Annotasiyalarla Java yanaşmasını portlayan Retrofit-dən fərqli olaraq, Ktor Client sorğuları konfiqurasiya etmək üçün Kotlin DSL istifadə edir — annotasiyalar və refleksiya olmadan. Bu, kodu Kotlin tərtibatçıları üçün daha oxunaqlı və tip-təhlükəsiz edir.

Kotlin Multiplatform 2024 sorğusuna görə, Ktor Client Kotlin Multiplatform Mobile (KMM) layihələrinin 35%-də istifadə olunur və bu onu Kotlin icmasında OkHttp-dan sonra ikinci ən populyar HTTP müştərisi edir. Ktor çoxplatformalılıq və Kotlin ekosistemi ilə native inteqrasiyanın vacib olduğu layihələrdə üstünlük təşkil edir.

Ktor Client necə işləyir

Ktor Client arxitekturası plaginlərdən ibarət boru kəmərinə (pipeline) əsaslanır. Hər bir sorğu quraşdırılmış plaginlər ardıcıllığından keçir, onlar sorğunu, cavabı dəyişdirə və ya əlavə hərəkətlər edə bilər — günləmə, sıxlaşdırma, serializasiya, autentifikasiya.

HttpClient { } DSL bloku vasitəsilə HTTP müştərisi yaradarkən siz mühərriki (OkHttp, Android, CIO, Darwin) təyin edir və plaginləri quraşdırırsınız. Hər bir mühərrik müəyyən platforma üçün aşağı səviyyəli sorğu göndərməni həyata keçirir: Android-də OkHttp mühərriki, iOS-da Darwin (URLSession), Desktop-da CIO (Coroutine-based I/O) istifadə olunur. HttpClient cari platforma üçün optimal mühərriki avtomatik seçir.

Ktor Client-də sorğu suspend-funksiya vasitəsilə icra olunur, bu da korutinlərlə tam inteqrasiya deməkdir. Heç bir Callback, RxJava və ya LiveData — yalnız axını bloklamadan asinxron işləyən suspend ilə ardıcıl kod.

Sorğunun emal boru kəməri

Ktor boru kəməri fazalardan ibarətdir: əvvəlcə sorğu quraşdırılmış plaginlərdən keçir (məsələn, JSON üçün ContentNegotiation, günlər üçün Logging), sonra mühərrik HTTP sorğusunu icra edir və cavab deserializasiya üçün yenidən plaginlərdən keçir. Hər bir plugin boru kəmərinin korutinində icra olunan suspend-funksiyadır.

Ktor boru kəmərinin vacib üstünlüyü şərti emal imkanıdır. Plugin sorğunun URL və ya başlıqlarını yoxlaya və şərt yerinə yetirilməzsə, emalı keçə bilər. Məsələn, gzip ilə ContentEncoding yalnız Content-Encoding: gzip başlığı olan cavablara tətbiq olunur, Auth isə yalnız qorunan endpoint-lər üçün işləyir, ictimai API-lərə təsir etmir.

Belə boru kəməri yanaşması plaginləri çevik birləşdirməyə imkan verir: siz JSON ilə ContentNegotiation quraşdıra, Bearer token ilə Auth əlavə edə, ContentEncoding sıxlaşdırma və HttpTimeout-u aktivləşdirə bilərsiniz — və hamısı düzgün ardıcıllıqla birlikdə işləyəcək. Plaginlərin quraşdırılma sırası əhəmiyyətlidir: birinci quraşdırılan sorğunu digərlərindən əvvəl emal edəcək.

Ktor Client plaginləri

Plaginlər — Retrofit annotasiyalarını və OkHttp interceptorlarını əvəz edən Ktor-un modul genişləndirmə sistemidir. Hər bir plugin konkret tapşırığı həll edir və HttpClient blokunda install() funksiyası vasitəsilə quraşdırılır. Ktor daxili plaginlər təqdim edir, həmçinin xüsusi plaginlər yaratmağa imkan verir.

Xüsusi plaginlər

Xüsusi tapşırıqlar üçün createClientPlugin vasitəsilə fərdi plugin yaradılır. Plugin sorğunu (onRequest), cavabı (onResponse) intercept edə və ya xətaları (onError) idarə edə bilər. Bu, OkHttp-dən Interceptor-u tamamilə əvəz edir, lakin tipli Kotlin-API və suspend-funksiyalar dəstəyi ilə.

Xüsusi plaginlər metrikalar, avtomatik təkrar cəhd məntiqi, sorğu izləmə və ya endpoint-lərin A/B testi əlavə etmək üçün əlverişlidir. OkHttp interceptorlarından fərqli olaraq, Ktor plaginləri Kotlin dilində yazılır və korutin kontekstində işləyir, bu da xəta və vaxt aşımı idarəsini asanlaşdırır.

Sorğuların debug edilməsi üçün ALL, HEADERS və ya BODY səviyyəsi ilə Logging pluginindən istifadə olunur. Logging metodu, URL, status, başlıqlar və sorğu/cavab gövdəsini göstərir. OkHttp-dən HttpLoggingInterceptor-dan fərqli olaraq, Ktor Logging asinxron işləyir və konfiqurasiyanı dəyişmək üçün tətbiqi dayandırmadan log səviyyəsinə (ERROR, WARN, INFO, DEBUG) görə filtrləməyə konfiqurasiya edilə bilər.

Kotlin-də Ktor Client kod nümunələri

Əsas GET sorğusunu Ktor Client vasitəsilə nəzərdən keçirək. JSON üçün quraşdırılmış ContentNegotiation plugin ilə HttpClient yaradılır. Sorğu suspend get() funksiyası vasitəsilə icra olunur, nəticə avtomatik olaraq data class-a deserializasiya olunur.

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övdə ilə POST sorğusu üçün contentType() və body() ilə post() funksiyası istifadə olunur. Ktor quraşdırılmış ContentNegotiation vasitəsilə obyekti avtomatik JSON-a serializasiya edir. DSL üslubu kodu ardıcıl və oxunaqlı edir.

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

Vaxt aşımı və başlıqların konfiqurasiyası

HttpTimeout və DefaultRequest — konfiqurasiya üçün iki əsas plagin. HttpTimeout vaxt məhdudiyyətlərini təyin edir, DefaultRequest isə bütün sorğular üçün başlıqları və URL parametrlərini təyin edərək hər çağırışda kodun təkrarlanmasının qarşısını alır.

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

Ktor-un çoxplatformalı dəstəyi

Çoxplatformalılıq — Ktor-un OkHttp və Retrofit-dən əsas üstünlüyü. Ktor Client JVM (Android, Server), Native (iOS, macOS, Windows, Linux) və JS (Browser) üzərində işləyir. HTTP müştərisinin eyni kodu bütün platformalarda dəyişiklik olmadan işləyir, bu xüsusilə Kotlin Multiplatform layihələri üçün dəyərlidir.

Hər bir platforma üçün Ktor öz mühərrikindən (engine) istifadə edir. Android-də standart olaraq OkHttp mühərriki tətbiq olunur, OkHttp ekosistemi ilə tam uyğunluq təmin edir. iOS-da URLSession-ə əsaslanan DarwinEngine istifadə olunur. Server üçün — CIOEngine (Coroutine I/O). Mühərrik açıq şəkildə göstərilə bilər: HttpClient(OkHttp) { } və ya HttpClient(Darwin) { }.

Mühərrik seçərkən onun imkanlarını nəzərə alın: OkHttp mühərriki HTTP/2 və qoşulma hovuzunu dəstəkləyir, DarwinEngine — iOS şəbəkəsi ilə native inteqrasiya və URLSession fon sessiyaları, CIOEngine — xarici asılılıqlar olmadan təmiz korutin tətbiqi. Web hədəfləri üçün fetch API vasitəsilə işləyən JsEngine və ya BrowserEngine istifadə olunur.

Bütün platformalarda vahid API sayəsində məlumat yükləmə kodu Android, iOS və Desktop-da eyni görünür. Bu, Retrofit (Android) və URLSession (iOS) üzrə ayrıca tətbiqlərlə müqayisədə KMM layihələrində kodun təkrarlanmasını 60–80% azaldır. Plaginlər də dəyişiklik olmadan bütün platformalarda işləyir.

Ktor ilə işləyərkən tipik səhvlər

HttpClient-in bağlanmasını nəzərə almamaq — Ktor-da geniş yayılmış səhvdir. HttpClient Closeable interfeysini həyata keçirir və tətbiq işini bitirdikdə client.close() vasitəsilə bağlanmalıdır. Android-də bu, onDestroy() Activity və ya ViewModel.onCleared() metodlarında edilir. Bağlanmamış müştəri korutin və mühərrik thread-lərinin sızmasına səbəb olur.

Plaginlərin səhv sırası sorğunun emalını poza bilər. Məsələn, ContentNegotiation DefaultRequest-dən əvvəl quraşdırılmalıdır ki, məzmun tipi düzgün tətbiq olunsun. Logging-in sonuncu quraşdırılması tövsiyə olunur ki, bütün dəyişikliklərdən sonra sorğunun son versiyası günlənə bilsin. Plaginlər gözlənilməz davranarsa, sıra ilə eksperiment edin.

suspend-funksiyalarda istisnaların idarə edilməməsi. Ktor şəbəkə xətalarında IOException və HTTP 4xx statuslarında ClientRequestException atır. Hər get(), post() və digər metod çağırışı üçün try-catch bloku məcburidir. Hər metoddə try-catch təkrarlanmasının qarşısını almaq üçün HttpClient blokunda HttpResponseValidator-dan istifadə edin.