Ktor: wat is het, kenmerken van de asynchrone HTTP-client

Wat is Ktor?

Ktor is een framework voor het bouwen van asynchrone server- en clientapplicaties in Kotlin, gemaakt door JetBrains. Ktor Client — het clientgedeelte van het framework, dat een HTTP-client biedt met volledige ondersteuning voor Kotlin-coroutines, multiplatform (JVM, Native, JS) en een modulaire architectuur op basis van plug-ins.

Ktor verscheen in 2018 als alternatief voor Retrofit en OkHttp voor Kotlin-first-projecten. In tegenstelling tot Retrofit, dat de Java-benadering met annotaties portte, gebruikt Ktor Client Kotlin DSL voor de configuratie van verzoeken — zonder annotaties en reflectie. Dit maakt de code leesbaarder en type-veiliger voor Kotlin-ontwikkelaars.

Volgens de Kotlin Multiplatform-enquête van 2024 wordt Ktor Client gebruikt in 35% van de Kotlin Multiplatform Mobile (KMM)-projecten, waarmee het de tweede populairste HTTP-client is na OkHttp in de Kotlin-gemeenschap. Ktor heeft de voorkeur in projecten waar multiplatform en native integratie met het Kotlin-ecosysteem belangrijk zijn.

Hoe werkt Ktor Client

De architectuur van Ktor Client is gebaseerd op een pijplijn (pipeline) van plug-ins. Elk verzoek doorloopt een reeks geïnstalleerde plug-ins die het verzoek, het antwoord kunnen wijzigen of nevenacties kunnen uitvoeren — logging, compressie, serialisatie, authenticatie.

Bij het maken van een HTTP-client via het HttpClient { } DSL-blok specificeert u de engine (OkHttp, Android, CIO, Darwin) en installeert u plug-ins. Elke engine implementeert het laag-niveau verzenden van verzoeken voor een specifiek platform: op Android wordt de OkHttp-engine gebruikt, op iOS — Darwin (URLSession), op Desktop — CIO (Coroutine-based I/O). HttpClient selecteert automatisch de optimale engine voor het huidige platform.

Een verzoek in Ktor Client wordt uitgevoerd via een suspend-functie, wat volledige integratie met coroutines betekent. Geen Callbacks, geen RxJava of LiveData — alleen sequentiële code met suspend die asynchroon werkt zonder de thread te blokkeren.

De verwerkingspijplijn van verzoeken

De Ktor-pijplijn bestaat uit fasen: eerst gaat het verzoek door de geïnstalleerde plug-ins (bijv. ContentNegotiation voor JSON, Logging voor logs), dan voert de engine het HTTP-verzoek uit, en het antwoord gaat opnieuw door de plug-ins voor deserialisatie. Elke plug-in is een suspend-functie die wordt uitgevoerd in de coroutine van de pijplijn.

Een belangrijk voordeel van de Ktor-pijplijn is de mogelijkheid van conditionele verwerking. Een plug-in kan de URL of headers van het verzoek controleren en de verwerking overslaan als niet aan de voorwaarde is voldaan. Bijvoorbeeld, ContentEncoding met gzip wordt alleen toegepast op antwoorden die de header Content-Encoding: gzip bevatten, en Auth werkt alleen voor beveiligde endpoints zonder openbare API's te beïnvloeden.

Deze pijplijnbenadering maakt flexibele combinatie van plug-ins mogelijk: u kunt ContentNegotiation met JSON installeren, Auth met Bearer-token toevoegen, ContentEncoding-compressie en HttpTimeout inschakelen — en ze werken allemaal samen in de juiste volgorde. De volgorde van installatie van plug-ins is belangrijk: de eerste geïnstalleerde zal het verzoek eerder verwerken dan de andere.

Ktor Client-plug-ins

Plug-ins — het modulaire uitbreidingssysteem van Ktor, dat Retrofit-annotaties en OkHttp-interceptors vervangt. Elke plug-in lost een specifieke taak op en wordt geïnstalleerd via de functie install() in het HttpClient-blok. Ktor biedt ingebouwde plug-ins en maakt ook het maken van aangepaste plug-ins mogelijk.

Aangepaste plug-ins

Voor specifieke taken wordt een aangepaste plug-in gemaakt via createClientPlugin. Een plug-in kan het verzoek (onRequest), antwoord (onResponse) onderscheppen of fouten (onError) afhandelen. Dit vervangt volledig de Interceptor uit OkHttp, maar met een getypeerde Kotlin-API en ondersteuning voor suspend-functies.

Aangepaste plug-ins zijn handig voor het toevoegen van metrieken, automatische herhaallogica, het traceren van verzoeken of A/B-testen van endpoints. In tegenstelling tot OkHttp-interceptors zijn Ktor-plug-ins geschreven in Kotlin en werken ze in de context van een coroutine, wat fout- en timeout-afhandeling vereenvoudigt.

Voor het debuggen van verzoeken wordt de plug-in Logging gebruikt met niveau ALL, HEADERS of BODY. Logging toont de methode, URL, status, headers en de body van het verzoek en antwoord. In tegenstelling tot HttpLoggingInterceptor uit OkHttp werkt Ktor Logging asynchroon en kan worden geconfigureerd voor filtering op logniveau (ERROR, WARN, INFO, DEBUG) zonder de applicatie te stoppen voor configuratiewijziging.

Ktor Client-codevoorbeelden in Kotlin

Laten we een basis-GET-verzoek via Ktor Client bekijken. Er wordt een HttpClient gemaakt met de geïnstalleerde plug-in ContentNegotiation voor JSON. Het verzoek wordt uitgevoerd via de suspend-functie get(), het resultaat wordt automatisch gedeserialiseerd naar een 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()
}

Voor een POST-verzoek met body wordt de functie post() met contentType() en body() gebruikt. Ktor serialiseert automatisch het object naar JSON via de geïnstalleerde ContentNegotiation. De DSL-stijl maakt de code sequentieel en leesbaar.

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

Configuratie van time-outs en headers

HttpTimeout en DefaultRequest — twee belangrijke plug-ins voor configuratie. HttpTimeout stelt tijdslimieten in, en DefaultRequest specificeert headers en URL-parameters voor alle verzoeken, waardoor code-duplicatie in elke aanroep wordt voorkomen.

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

Multiplatform-ondersteuning van Ktor

Multiplatform — het belangrijkste voordeel van Ktor ten opzichte van OkHttp en Retrofit. Ktor Client werkt op JVM (Android, Server), Native (iOS, macOS, Windows, Linux) en JS (Browser). Dezelfde HTTP-clientcode draait op alle platforms zonder wijzigingen, wat bijzonder waardevol is voor Kotlin Multiplatform-projecten.

Voor elk platform gebruikt Ktor zijn eigen engine. Op Android wordt standaard de OkHttp-engine toegepast, die volledige compatibiliteit met het OkHttp-ecosysteem biedt. Op iOS wordt DarwinEngine gebruikt, gebaseerd op URLSession. Voor Server — CIOEngine (Coroutine I/O). De engine kan expliciet worden opgegeven: HttpClient(OkHttp) { } of HttpClient(Darwin) { }.

Houd bij het kiezen van een engine rekening met de mogelijkheden: de OkHttp-engine ondersteunt HTTP/2 en een verbindingspool, DarwinEngine — native integratie met het iOS-netwerk en URLSession-achtergrondsessies, CIOEngine — een pure coroutine-implementatie zonder externe afhankelijkheden. Voor Web-doelen wordt JsEngine of BrowserEngine gebruikt die via de fetch API werken.

Dankzij de uniforme API op alle platforms ziet de code voor het laden van gegevens er hetzelfde uit op Android, iOS en Desktop. Dit vermindert code-duplicatie met 60–80% in KMM-projecten in vergelijking met afzonderlijke implementaties op Retrofit (Android) en URLSession (iOS). Plug-ins werken ook op alle platforms zonder wijzigingen.

Veelvoorkomende fouten bij het werken met Ktor

Het negeren van het sluiten van HttpClient — een veelvoorkomende fout in Ktor. HttpClient implementeert Closeable en moet bij het beëindigen van de applicatie worden gesloten via client.close(). In Android gebeurt dit in onDestroy() van Activity of ViewModel.onCleared(). Een niet-gesloten client leidt tot lekkage van coroutines en enginethreads.

Onjuiste volgorde van plug-ins kan de verwerking van verzoeken verstoren. Bijvoorbeeld, ContentNegotiation moet vóór DefaultRequest worden geïnstalleerd om het inhoudstype correct toe te passen. Logging wordt aanbevolen als laatste te installeren om de definitieve versie van het verzoek na alle wijzigingen te loggen. Experimenteer met de volgorde als plug-ins zich onverwacht gedragen.

Het ontbreken van uitzonderingsafhandeling in suspend-functies. Ktor gooit IOException bij netwerkfouten en ClientRequestException bij HTTP-status 4xx. Een try-catch-blok is verplicht voor elke aanroep van get(), post() en andere methoden. Gebruik HttpResponseValidator in het HttpClient-blok voor globale foutafhandeling zonder try-catch in elke methode te dupliceren.