Ktor: mi ez, az aszinkron HTTP-kliens jellemzői

Mi az a Ktor?

A Ktor egy keretrendszer aszinkron szerver- és kliensalkalmazások építéséhez Kotlinban, amelyet a JetBrains hozott létre. A Ktor Client — a keretrendszer kliens része, amely egy HTTP-klienst biztosít a Kotlin-korutinok, a többplatformosság (JVM, Native, JS) és a pluginokon alapuló moduláris architektúra teljes támogatásával.

A Ktor 2018-ban jelent meg a Retrofit és OkHttp alternatívájaként Kotlin-first projektek számára. Ellentétben a Retrofit-tal, amely a Java annotációs megközelítést portolta, a Ktor Client Kotlin DSL-t használ a kérések konfigurálásához — annotációk és reflexió nélkül. Ez olvashatóbbá és típusbiztosabbá teszi a kódot a Kotlin-fejlesztők számára.

A Kotlin Multiplatform 2024 felmérés szerint a Ktor Client a Kotlin Multiplatform Mobile (KMM) projektek 35%-ában használatos, ami a második legnépszerűbb HTTP-klienssé teszi az OkHttp után a Kotlin közösségben. A Ktor-t olyan projektekben részesítik előnyben, ahol fontos a többplatformosság és a natív integráció a Kotlin-ökoszisztémával.

Hogyan működik a Ktor Client

A Ktor Client architektúrája pluginok csővezetékén (pipeline) alapul. Minden kérés áthalad a telepített pluginok sorozatán, amelyek módosíthatják a kérést, a választ, vagy mellékhatásokat hajthatnak végre — naplózás, tömörítés, szerializáció, hitelesítés.

A HTTP-kliens létrehozásakor a HttpClient { } DSL blokkon keresztül megadja a motort (OkHttp, Android, CIO, Darwin) és telepíti a pluginokat. Minden motor alacsony szintű kérésküldést valósít meg egy adott platformhoz: Androidon az OkHttp motor használatos, iOS-en — Darwin (URLSession), Desktop-on — CIO (Coroutine-based I/O). A HttpClient automatikusan kiválasztja az optimális motort az aktuális platformhoz.

A Ktor Client-ben a kérés suspend-függvényen keresztül hajtódik végre, ami teljes integrációt jelent a korutinokkal. Nincs Callback, RxJava vagy LiveData — csak szekvenciális kód suspend-del, amely aszinkron működik a szál blokkolása nélkül.

A kérés feldolgozásának csővezetéke

A Ktor csővezeték fázisokból áll: először a kérés áthalad a telepített pluginokon (pl. ContentNegotiation JSON-hoz, Logging naplókhoz), majd a motor végrehajtja a HTTP-kérést, és a válasz ismét áthalad a pluginokon a deszerializációhoz. Minden plugin egy suspend-függvény, amely a csővezeték korutinjában hajtódik végre.

A Ktor csővezeték fontos előnye a feltételes feldolgozás lehetősége. A plugin ellenőrizheti a kérés URL-jét vagy fejléceit, és kihagyhatja a feldolgozást, ha a feltétel nem teljesül. Például a gzip-pel történő ContentEncoding csak azokra a válaszokra alkalmazandó, amelyek tartalmazzák a Content-Encoding: gzip fejlécet, és az Auth csak a védett végpontokra aktiválódik, anélkül hogy befolyásolná a nyilvános API-kat.

Ez a csővezeték-megközelítés lehetővé teszi a pluginok rugalmas kombinálását: telepítheti a ContentNegotiation-t JSON-nal, hozzáadhatja az Auth-t Bearer token-nel, bekapcsolhatja a ContentEncoding tömörítést és a HttpTimeout-ot — és mindegyik együttműködik a megfelelő sorrendben. A pluginok telepítési sorrendje számít: az elsőként telepített dolgozza fel a kérést a többi előtt.

Ktor Client pluginok

A pluginok a Ktor moduláris bővítményrendszere, amely felváltja a Retrofit annotációkat és az OkHttp elfogókat. Minden plugin egy adott feladatot old meg, és a HttpClient blokkban az install() függvényen keresztül telepíthető. A Ktor beépített pluginokat kínál, és lehetővé teszi egyedi pluginok létrehozását is.

Egyedi pluginok

Speciális feladatokhoz egyedi plugin hozható létre a createClientPlugin segítségével. A plugin elfoghatja a kérést (onRequest), a választ (onResponse) vagy kezelheti a hibákat (onError). Ez teljesen helyettesíti az OkHttp Interceptor-ját, de tipizált Kotlin-API-val és suspend-függvények támogatásával.

Az egyedi pluginok hasznosak metrikák, automatikus újrapróbálkozási logika, kérések nyomon követése vagy végpontok A/B tesztelésének hozzáadásához. Az OkHttp elfogóktól eltérően a Ktor pluginok Kotlin nyelven íródnak, és a korutin kontextusában működnek, ami egyszerűsíti a hiba- és időtúllépés-kezelést.

A kérések hibakereséséhez a Logging plugin használatos ALL, HEADERS vagy BODY szinttel. A Logging megjeleníti a metódust, URL-t, státuszt, fejléceket és a kérés/válasz törzsét. Az OkHttp HttpLoggingInterceptor-jától eltérően a Ktor Logging aszinkron működik, és beállítható naplózási szint szerinti szűrésre (ERROR, WARN, INFO, DEBUG) anélkül, hogy le kellene állítani az alkalmazást a konfiguráció módosításához.

Ktor Client kódpéldák Kotlinban

Tekintsük át az alap GET kérést a Ktor Client segítségével. Létrehozunk egy HttpClient-t a telepített ContentNegotiation pluginnal JSON-hoz. A kérés a suspend get() függvényen keresztül hajtódik végre, az eredmény automatikusan deszerializálódik egy data class-ba.

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

POST kéréshez törzzsel a post() függvény használatos contentType() és body() paraméterekkel. A Ktor automatikusan szerializálja az objektumot JSON-ba a telepített ContentNegotiation segítségével. A DSL-stílus szekvenciálissá és olvashatóvá teszi a kódot.

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

Időtúllépések és fejlécek konfigurálása

A HttpTimeout és DefaultRequest — két kulcsfontosságú plugin a konfigurációhoz. A HttpTimeout időkorlátokat állít be, a DefaultRequest pedig fejléceket és URL-paramétereket határoz meg minden kéréshez, kiküszöbölve a kódismétlést minden hívásban.

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

A Ktor többplatformos támogatása

A többplatformosság — a Ktor fő előnye az OkHttp-val és Retrofit-tal szemben. A Ktor Client JVM-en (Android, Server), Native-on (iOS, macOS, Windows, Linux) és JS-en (Browser) működik. Ugyanaz a HTTP-kliens kód minden platformon változtatás nélkül fut, ami különösen értékes a Kotlin Multiplatform projektek számára.

Minden platformhoz a Ktor a saját motorját (engine) használja. Androidon alapértelmezés szerint az OkHttp motor kerül alkalmazásra, amely teljes kompatibilitást biztosít az OkHttp ökoszisztémával. iOS-en a URLSession-ra épülő DarwinEngine használatos. Szerverhez — CIOEngine (Coroutine I/O). A motor kifejezetten megadható: HttpClient(OkHttp) { } vagy HttpClient(Darwin) { }.

A motor kiválasztásakor vegye figyelembe a képességeit: az OkHttp motor támogatja a HTTP/2-t és a kapcsolati készletet, a DarwinEngine — a natív iOS hálózati integrációt és a URLSession háttér-munkameneteket, a CIOEngine — tiszta korutin implementációt külső függőségek nélkül. Web célokhoz a JsEngine vagy BrowserEngine használatos, amely a fetch API-n keresztül működik.

Az egységes API-nak köszönhetően minden platformon az adatbetöltő kód ugyanúgy néz ki Androidon, iOS-en és Desktop-on. Ez 60–80%-kal csökkenti a kódismétlést a KMM projektekben a Retrofit (Android) és URLSession (iOS) külön implementációihoz képest. A pluginok is változtatás nélkül működnek minden platformon.

Gyakori hibák a Ktor használatakor

A HttpClient bezárásának elmulasztása — gyakori hiba a Ktor-ban. A HttpClient megvalósítja a Closeable interfészt, és az alkalmazás befejezésekor be kell zárni a client.close() segítségével. Androidon ez az Activity onDestroy()-jában vagy a ViewModel.onCleared()-jében történik. A be nem zárt kliens korutin- és motor-szálak szivárgásához vezet.

A pluginok helytelen sorrendje megtörheti a kérés feldolgozását. Például a ContentNegotiation-t a DefaultRequest előtt kell telepíteni, hogy a tartalomtípus helyesen kerüljön alkalmazásra. A Logging-et ajánlott utolsóként telepíteni, hogy a kérés végleges verziója az összes módosítás után kerüljön naplózásra. Kísérletezzen a sorrenddel, ha a pluginok váratlanul viselkednek.

A kivételek kezelésének hiánya a suspend-függvényekben. A Ktor IOException-t dob hálózati hibák esetén és ClientRequestException-t HTTP 4xx státuszoknál. A try-catch blokk kötelező minden get(), post() és más metódus hívásához. Használja a HttpResponseValidator-t a HttpClient blokkban a globális hibakezeléshez, elkerülve a try-catch ismétlését minden metódusban.