Ktor: vad är det, egenskaper hos den asynkrona HTTP-klienten

Vad är Ktor?

Ktor är ett ramverk för att bygga asynkrona server- och klientapplikationer i Kotlin, skapat av JetBrains. Ktor Client — klientdelen av ramverket, som tillhandahåller en HTTP-klient med fullt stöd för Kotlins korutiner, multiplattform (JVM, Native, JS) och modulär arkitektur baserad på plugin-program.

Ktor dök upp 2018 som ett alternativ till Retrofit och OkHttp för Kotlin-first-projekt. Till skillnad från Retrofit, som portade Java-metoden med annotationer, använder Ktor Client Kotlin DSL för att konfigurera förfrågningar — utan annotationer och reflektion. Detta gör koden mer läsbar och typ-säker för Kotlin-utvecklare.

Enligt Kotlin Multiplatform-undersökningen 2024 används Ktor Client i 35% av Kotlin Multiplatform Mobile (KMM)-projekten, vilket gör det till den näst mest populära HTTP-klienten efter OkHttp i Kotlin-gemenskapen. Ktor föredras i projekt där multiplattform och native integration med Kotlin-ekosystemet är viktiga.

Hur fungerar Ktor Client

Arkitekturen för Ktor Client är baserad på en pipeline av plugin-program. Varje förfrågan går igenom en sekvens av installerade plugin-program som kan modifiera förfrågan, svaret eller utföra sidoåtgärder — loggning, komprimering, serialisering, autentisering.

När du skapar en HTTP-klient via HttpClient { } DSL-blocket anger du motorn (OkHttp, Android, CIO, Darwin) och installerar plugin-program. Varje motor implementerar lågnivå-sändning av förfrågningar för en specifik plattform: på Android används OkHttp-motorn, på iOS — Darwin (URLSession), på Desktop — CIO (Coroutine-based I/O). HttpClient väljer automatiskt den optimala motorn för den aktuella plattformen.

En förfrågan i Ktor Client utförs via en suspend-funktion, vilket innebär full integration med korutiner. Inga Callback, RxJava eller LiveData — bara sekventiell kod med suspend som fungerar asynkront utan att blockera tråden.

Pipeline för bearbetning av förfrågan

Ktor-pipelinen består av faser: först går förfrågan igenom de installerade plugin-programmen (t.ex. ContentNegotiation för JSON, Logging för loggar), sedan utför motorn HTTP-förfrågan, och svaret går igenom plugin-programmen igen för deserialisering. Varje plugin-program är en suspend-funktion som körs i pipelinens korutin.

En viktig fördel med Ktor-pipelinen är möjligheten till villkorlig bearbetning. Ett plugin-program kan kontrollera URL:en eller rubrikerna för förfrågan och hoppa över bearbetning om villkoret inte är uppfyllt. Till exempel tillämpas ContentEncoding med gzip endast på svar som innehåller rubriken Content-Encoding: gzip, och Auth aktiveras endast för skyddade endpoints utan att påverka offentliga API:er.

Denna pipeline-metod möjliggör flexibel kombination av plugin-program: du kan installera ContentNegotiation med JSON, lägga till Auth med Bearer-token, aktivera ContentEncoding-komprimering och HttpTimeout — och alla fungerar tillsammans i rätt ordning. Installationsordningen för plugin-program är viktig: det första installerade kommer att bearbeta förfrågan tidigare än de andra.

Ktor Client-plugin-program

Plugin-program — Ktors modulära expansionssystem som ersätter Retrofit-annotationer och OkHttp-interceptors. Varje plugin-program löser en specifik uppgift och installeras via funktionen install() i HttpClient-blocket. Ktor tillhandahåller inbyggda plugin-program och tillåter också att skapa anpassade.

Anpassade plugin-program

För specifika uppgifter skapas ett anpassat plugin-program via createClientPlugin. Plugin-programmet kan fånga upp förfrågan (onRequest), svaret (onResponse) eller hantera fel (onError). Detta ersätter helt Interceptor från OkHttp, men med typat Kotlin-API och stöd för suspend-funktioner.

Anpassade plugin-program är användbara för att lägga till mätvärden, automatisk omförsökslogik, spårning av förfrågningar eller A/B-testning av endpoints. Till skillnad från OkHttp-interceptors är Ktor-plugin-program skrivna i Kotlin och fungerar i korutinkontext, vilket förenklar fel- och timeout-hantering.

För felsökning av förfrågningar används plugin-programmet Logging med nivån ALL, HEADERS eller BODY. Logging visar metoden, URL:en, status, rubriker och kroppen för förfrågan och svaret. Till skillnad från HttpLoggingInterceptor från OkHttp fungerar Ktor Logging asynkront och kan konfigureras för filtrering efter loggnivå (ERROR, WARN, INFO, DEBUG) utan att stoppa applikationen för konfigurationsändring.

Kodexempel för Ktor Client i Kotlin

Låt oss titta på en grundläggande GET-förfrågan via Ktor Client. En HttpClient skapas med installerat plugin-program ContentNegotiation för JSON. Förfrågan utförs via suspend-funktionen get(), resultatet deserialiseras automatiskt till en 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()
}

För en POST-förfrågan med kropp används funktionen post() med contentType() och body(). Ktor serialiserar automatiskt objektet till JSON via den installerade ContentNegotiation. DSL-stilen gör koden sekventiell och läsbar.

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

Konfiguration av timeout och rubriker

HttpTimeout och DefaultRequest — två viktiga plugin-program för konfiguration. HttpTimeout ställer in tidsgränser och DefaultRequest anger rubriker och URL-parametrar för alla förfrågningar, vilket eliminerar kodduplicering i varje anrop.

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

Ktors multiplattformsstöd

Multiplattform — den främsta fördelen med Ktor jämfört med OkHttp och Retrofit. Ktor Client fungerar på JVM (Android, Server), Native (iOS, macOS, Windows, Linux) och JS (Browser). Samma HTTP-klientkod körs på alla plattformar utan ändringar, vilket är särskilt värdefullt för Kotlin Multiplatform-projekt.

För varje plattform använder Ktor sin egen motor. På Android används som standard OkHttp-motorn, som ger full kompatibilitet med OkHttp-ekosystemet. På iOS används DarwinEngine baserad på URLSession. För Server — CIOEngine (Coroutine I/O). Motorn kan anges explicit: HttpClient(OkHttp) { } eller HttpClient(Darwin) { }.

När du väljer motor, överväg dess kapacitet: OkHttp-motorn stöder HTTP/2 och anslutningspool, DarwinEngine — native integration med iOS-nätverket och URLSession-bakgrundssessioner, CIOEngine — ren korutinimplementering utan externa beroenden. För Web-mål används JsEngine eller BrowserEngine som fungerar via fetch API.

Tack vare det enhetliga API:et på alla plattformar ser koden för dataladdning likadan ut på Android, iOS och Desktop. Detta minskar kodduplicering med 60–80% i KMM-projekt jämfört med separata implementeringar på Retrofit (Android) och URLSession (iOS). Plugin-program fungerar också på alla plattformar utan ändringar.

Vanliga misstag vid arbete med Ktor

Att ignorera stängning av HttpClient — ett vanligt misstag i Ktor. HttpClient implementerar Closeable och måste stängas när applikationen avslutas via client.close(). I Android görs detta i onDestroy() för Activity eller ViewModel.onCleared(). En ostängd klient leder till läckage av korutiner och motortrådar.

Felaktig ordning på plugin-program kan störa bearbetningen av förfrågan. Till exempel måste ContentNegotiation installeras före DefaultRequest för att innehållstypen ska tillämpas korrekt. Logging rekommenderas att installeras sist för att logga den slutliga versionen av förfrågan efter alla ändringar. Experimentera med ordningen om plugin-program beter sig oväntat.

Brist på undantagshantering i suspend-funktioner. Ktor kastar IOException vid nätverksfel och ClientRequestException vid HTTP-status 4xx. Ett try-catch-block är obligatoriskt för varje anrop av get(), post() och andra metoder. Använd HttpResponseValidator i HttpClient-blocket för global felhantering utan att duplicera try-catch i varje metod.