Ktor: ce este, caracteristicile clientului HTTP asincron

Ce este Ktor?

Ktor este un framework pentru construirea aplicațiilor asincrone server și client în Kotlin, creat de compania JetBrains. Ktor Client — partea client a framework-ului, care oferă un client HTTP cu suport complet pentru corutinele Kotlin, multi-platformă (JVM, Native, JS) și arhitectură modulară bazată pe pluginuri.

Ktor a apărut în 2018 ca alternativă la Retrofit și OkHttp pentru proiecte Kotlin-first. Spre deosebire de Retrofit, care a portat abordarea Java cu adnotări, Ktor Client folosește Kotlin DSL pentru configurarea cererilor — fără adnotări și reflecție. Acest lucru face codul mai lizibil și tip-sigur pentru dezvoltatorii Kotlin.

Conform sondajului Kotlin Multiplatform 2024, Ktor Client este utilizat în 35% din proiectele Kotlin Multiplatform Mobile (KMM), ceea ce îl face al doilea cel mai popular client HTTP după OkHttp în comunitatea Kotlin. Ktor este preferat în proiectele unde multi-platforma și integrarea nativă cu ecosistemul Kotlin sunt importante.

Cum funcționează Ktor Client

Arhitectura Ktor Client se bazează pe o conductă (pipeline) de pluginuri. Fiecare cerere trece printr-o secvență de pluginuri instalate, care pot modifica cererea, răspunsul sau efectua acțiuni secundare — logare, compresie, serializare, autentificare.

La crearea clientului HTTP prin blocul HttpClient { } DSL, specificați motorul (OkHttp, Android, CIO, Darwin) și instalați pluginurile. Fiecare motor implementează trimiterea la nivel scăzut a cererii pentru o platformă specifică: pe Android se folosește motorul OkHttp, pe iOS — Darwin (URLSession), pe Desktop — CIO (Coroutine-based I/O). HttpClient selectează automat motorul optim pentru platforma curentă.

Cererea în Ktor Client se execută prin funcția suspend, ceea ce înseamnă integrare completă cu corutinele. Niciun Callback, nicio RxJava sau LiveData — doar cod secvențial cu suspend care funcționează asincron fără a bloca firul de execuție.

Conducta de procesare a cererii

Conducta Ktor constă în faze: mai întâi cererea trece prin pluginurile instalate (de exemplu, ContentNegotiation pentru JSON, Logging pentru jurnale), apoi motorul execută cererea HTTP, iar răspunsul trece din nou prin pluginuri pentru deserializare. Fiecare plugin este o funcție suspend care se execută în corutina conductei.

Un avantaj important al conductei Ktor este posibilitatea procesării condiționate. Pluginul poate verifica URL-ul sau anteturile cererii și poate sări peste procesare dacă condiția nu este îndeplinită. De exemplu, ContentEncoding cu gzip se aplică doar răspunsurilor care conțin antetul Content-Encoding: gzip, iar Auth acționează doar pentru endpoint-urile protejate, fără a afecta API-urile publice.

Această abordare de conductă permite combinarea flexibilă a pluginurilor: puteți instala ContentNegotiation cu JSON, adăuga Auth cu token Bearer, activa compresia ContentEncoding și HttpTimeout — și toate vor funcționa împreună în ordinea corectă. Ordinea instalării pluginurilor contează: primul instalat va procesa cererea înaintea celorlalte.

Pluginuri Ktor Client

Pluginurile — sistemul modular de extensii al Ktor, care înlocuiește adnotările Retrofit și interceptoarele OkHttp. Fiecare plugin rezolvă o sarcină specifică și se instalează prin funcția install() în blocul HttpClient. Ktor oferă pluginuri încorporate și, de asemenea, permite crearea de pluginuri personalizate.

Pluginuri personalizate

Pentru sarcini specifice se creează un plugin personalizat prin createClientPlugin. Pluginul poate intercepta cererea (onRequest), răspunsul (onResponse) sau gestiona erorile (onError). Acesta înlocuiește complet Interceptor din OkHttp, dar cu API tipizat Kotlin și suport pentru funcții suspend.

Pluginurile personalizate sunt utile pentru adăugarea de metrici, logică automată de reîncercare, trasarea cererilor sau testarea A/B a endpoint-urilor. Spre deosebire de interceptoarele OkHttp, pluginurile Ktor sunt scrise în Kotlin și funcționează în contextul corutinei, ceea ce simplifică gestionarea erorilor și timeout-urilor.

Pentru depanarea cererilor se folosește pluginul Logging cu nivelul ALL, HEADERS sau BODY. Logging afișează metoda, URL-ul, statusul, anteturile și corpul cererii și răspunsului. Spre deosebire de HttpLoggingInterceptor din OkHttp, Ktor Logging funcționează asincron și poate fi configurat pentru filtrarea după nivelul de jurnal (ERROR, WARN, INFO, DEBUG) fără a opri aplicația pentru schimbarea configurației.

Exemple de cod Ktor Client în Kotlin

Să examinăm cererea GET de bază prin Ktor Client. Se creează un HttpClient cu pluginul ContentNegotiation instalat pentru JSON. Cererea se execută prin funcția suspend get(), rezultatul este deserializat automat într-un data class.

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

Pentru cererea POST cu corp se folosește funcția post() cu contentType() și body(). Ktor serializează automat obiectul în JSON prin ContentNegotiation instalat. Stilul DSL face codul secvențial și lizibil.

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

Configurarea timeout-urilor și anteturilor

HttpTimeout și DefaultRequest — două pluginuri cheie pentru configurare. HttpTimeout stabilește limitele de timp, iar DefaultRequest specifică anteturile și parametrii URL pentru toate cererile, eliminând duplicarea codului în fiecare apel.

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

Suportul multi-platformă Ktor

Multi-platforma — principalul avantaj al Ktor față de OkHttp și Retrofit. Ktor Client funcționează pe JVM (Android, Server), Native (iOS, macOS, Windows, Linux) și JS (Browser). Același cod al clientului HTTP rulează pe toate platformele fără modificări, ceea ce este deosebit de valoros pentru proiectele Kotlin Multiplatform.

Pentru fiecare platformă Ktor folosește propriul motor (engine). Pe Android implicit se aplică motorul OkHttp, care oferă compatibilitate completă cu ecosistemul OkHttp. Pe iOS se folosește DarwinEngine bazat pe URLSession. Pentru Server — CIOEngine (Coroutine I/O). Motorul poate fi specificat explicit: HttpClient(OkHttp) { } sau HttpClient(Darwin) { }.

La alegerea motorului luați în considerare capacitățile sale: motorul OkHttp suportă HTTP/2 și pool-ul de conexiuni, DarwinEngine — integrare nativă cu rețeaua iOS și sesiuni de fundal URLSession, CIOEngine — implementare pură pe corutine fără dependențe externe. Pentru ținte Web se folosește JsEngine sau BrowserEngine care funcționează prin fetch API.

Datorită API-ului uniform pe toate platformele, codul pentru încărcarea datelor arată la fel pe Android, iOS și Desktop. Aceasta reduce duplicarea codului cu 60–80% în proiectele KMM comparativ cu implementări separate pe Retrofit (Android) și URLSession (iOS). Pluginurile funcționează și ele pe toate platformele fără modificări.

Erori tipice la lucrul cu Ktor

Ignorarea închiderii HttpClient — o eroare frecventă în Ktor. HttpClient implementează Closeable și trebuie închis la terminarea aplicației prin client.close(). În Android, aceasta se face în onDestroy() al Activity sau ViewModel.onCleared(). Un client neînchis duce la scurgeri de corutine și fire de execuție ale motorului.

Ordinea incorectă a pluginurilor poate strica procesarea cererii. De exemplu, ContentNegotiation trebuie instalat înainte de DefaultRequest pentru ca tipul de conținut să fie aplicat corect. Logging se recomandă a fi instalat ultimul pentru a jurnaliza versiunea finală a cererii după toate modificările. Experimentați cu ordinea dacă pluginurile se comportă neașteptat.

Lipsa gestionării excepțiilor în funcțiile suspend. Ktor aruncă excepții IOException la erori de rețea și ClientRequestException la statusurile HTTP 4xx. Blocul try-catch este obligatoriu pentru fiecare apel get(), post() și alte metode. Folosiți HttpResponseValidator în blocul HttpClient pentru gestionarea globală a erorilor fără duplicarea try-catch în fiecare metodă.