Ktor: was ist das, Eigenschaften des asynchronen HTTP-Clients

Was ist Ktor?

Ktor ist ein Framework zum Erstellen asynchroner Server- und Client-Anwendungen in Kotlin, entwickelt von JetBrains. Ktor Client ist der Client-Teil des Frameworks und bietet einen HTTP-Client mit vollständiger Unterstützung für Kotlin-Koroutinen, Multiplattform (JVM, Native, JS) und einer modularen Plugin-basierten Architektur.

Ktor entstand 2018 als Alternative zu Retrofit und OkHttp für Kotlin-First-Projekte. Im Gegensatz zu Retrofit, das den Java-Ansatz mit Annotationen portierte, verwendet Ktor Client Kotlin DSL für die Anfragekonfiguration — ohne Annotationen und Reflektion. Dies macht den Code für Kotlin-Entwickler lesbarer und typsicherer.

Laut der Kotlin-Multiplattform-Umfrage 2024 wird Ktor Client in 35% der Kotlin Multiplatform Mobile (KMM)-Projekte verwendet und ist damit der zweitbeliebteste HTTP-Client nach OkHttp in der Kotlin-Community. Ktor wird in Projekten bevorzugt, bei denen Multiplattform-Unterstützung und native Integration in das Kotlin-Ökosystem wichtig sind.

Wie Ktor Client funktioniert

Die Ktor Client Architektur basiert auf einer Pipeline von Plugins. Jede Anfrage durchläuft eine Sequenz installierter Plugins, die die Anfrage, Antwort oder Nebenaktionen wie Protokollierung, Komprimierung, Serialisierung und Authentifizierung modifizieren können.

Beim Erstellen eines HTTP-Clients über den HttpClient { } DSL-Block geben Sie die Engine (OkHttp, Android, CIO, Darwin) an und installieren Plugins. Jede Engine implementiert das Low-Level-Senden von Anfragen für eine bestimmte Plattform: Auf Android wird die OkHttp-Engine verwendet, auf iOS — Darwin (URLSession), auf Desktop — CIO (Coroutine I/O). HttpClient wählt automatisch die optimale Engine für die aktuelle Plattform aus.

Eine Anfrage in Ktor Client wird über eine suspend-Funktion ausgeführt, was eine vollständige Integration mit Koroutinen bedeutet. Keine Callbacks, kein RxJava oder LiveData — nur sequenzieller Code mit suspend, der asynchron ohne Blockieren des Threads arbeitet.

Anfrageverarbeitungspipeline

Die Ktor-Pipeline besteht aus Phasen: Zuerst durchläuft die Anfrage installierte Plugins (z.B. ContentNegotiation für JSON, Logging für Protokolle), dann führt die Engine die HTTP-Anfrage aus, und die Antwort durchläuft erneut die Plugins zur Deserialisierung. Jedes Plugin ist eine suspend-Funktion, die in der Pipeline-Koroutine ausgeführt wird.

Ein wichtiger Vorteil der Ktor-Pipeline ist die Fähigkeit zur bedingten Verarbeitung. Ein Plugin kann die URL oder Anfrageheader überprüfen und die Verarbeitung überspringen, wenn die Bedingung nicht erfüllt ist. Beispielsweise wird ContentEncoding mit gzip nur auf Antworten angewendet, die den Content-Encoding: gzip-Header enthalten, und Auth wird nur für geschützte Endpunkte ausgelöst, ohne öffentliche APIs zu beeinträchtigen.

Dieser Pipeline-Ansatz ermöglicht es, Plugins flexibel zu kombinieren: Sie können ContentNegotiation mit JSON installieren, Auth mit Bearer-Token hinzufügen, ContentEncoding-Komprimierung und HttpTimeout aktivieren — und alle arbeiten in der richtigen Reihenfolge zusammen. Die Reihenfolge der Plugin-Installation ist wichtig: Das zuerst installierte Plugin verarbeitet die Anfrage vor den anderen.

Ktor Client Plugins

Plugins sind das modulare Erweiterungssystem von Ktor, das Retrofit-Annotationen und OkHttp-Interceptor ersetzt. Jedes Plugin löst eine bestimmte Aufgabe und wird über die install()-Funktion im HttpClient-Block installiert. Ktor bietet integrierte Plugins und erlaubt auch die Erstellung benutzerdefinierter Plugins.

Benutzerdefinierte Plugins

Für spezifische Aufgaben wird ein benutzerdefiniertes Plugin über createClientPlugin erstellt. Das Plugin kann die Anfrage (onRequest), Antwort (onResponse) abfangen oder Fehler (onError) behandeln. Dies ersetzt vollständig den Interceptor von OkHttp, jedoch mit einer typisierten Kotlin-API und Unterstützung für suspend-Funktionen.

Benutzerdefinierte Plugins sind praktisch für das Hinzufügen von Metriken, automatischer Wiederholungslogik, Anfrageverfolgung oder A/B-Tests von Endpunkten. Im Gegensatz zu OkHttp-Interceptoren sind Ktor-Plugins in Kotlin geschrieben und laufen im Koroutinen-Kontext, was die Fehler- und Timeout-Behandlung vereinfacht.

Für das Debugging von Anfragen wird das Logging-Plugin mit Level ALL, HEADERS oder BODY verwendet. Logging gibt Methode, URL, Status, Header und Body der Anfrage und Antwort aus. Im Gegensatz zu OkHttps HttpLoggingInterceptor arbeitet Ktor Logging asynchron und kann so konfiguriert werden, dass es nach Log-Level (ERROR, WARN, INFO, DEBUG) filtert, ohne die Anwendung zum Ändern der Konfiguration zu stoppen.

Ktor Client Codebeispiele in Kotlin

Betrachten wir eine einfache GET-Anfrage mit Ktor Client. Ein HttpClient wird mit dem installierten ContentNegotiation-Plugin für JSON erstellt. Die Anfrage wird über die suspend-Funktion get() ausgeführt, und das Ergebnis wird automatisch in eine Data Class deserialisiert.

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 eine POST-Anfrage mit Body wird die post()-Funktion mit contentType() und body() verwendet. Ktor serialisiert das Objekt automatisch über das installierte ContentNegotiation in JSON. Der DSL-Stil macht den Code sequenziell und lesbar.

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 von Timeouts und Headern

HttpTimeout und DefaultRequest sind zwei wichtige Plugins für die Konfiguration. HttpTimeout legt Zeitlimits fest, und DefaultRequest spezifiziert Header und URL-Parameter für alle Anfragen, wodurch Code-Duplikation in jedem Aufruf vermieden wird.

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

Ktor Multiplattform-Unterstützung

Multiplattform ist der Hauptvorteil von Ktor gegenüber OkHttp und Retrofit. Ktor Client läuft auf JVM (Android, Server), Native (iOS, macOS, Windows, Linux) und JS (Browser). Derselbe HTTP-Client-Code läuft ohne Änderungen auf allen Plattformen, was besonders wertvoll für Kotlin-Multiplattform-Projekte ist.

Für jede Plattform verwendet Ktor eine eigene Engine. Auf Android wird standardmäßig die OkHttp-Engine verwendet, die volle Kompatibilität mit dem OkHttp-Ökosystem bietet. Auf iOS wird DarwinEngine verwendet, basierend auf URLSession. Für Server — CIOEngine (Coroutine I/O). Die Engine kann explizit angegeben werden: HttpClient(OkHttp) { } oder HttpClient(Darwin) { }.

Bei der Auswahl einer Engine berücksichtigen Sie deren Fähigkeiten: Die OkHttp-Engine unterstützt HTTP/2 und Verbindungspooling, DarwinEngine bietet native iOS-Netzwerkintegration und Hintergrund-URLSession-Sitzungen, CIOEngine ist eine reine Koroutinen-Implementierung ohne externe Abhängigkeiten. Für Web-Ziele wird JsEngine oder BrowserEngine verwendet, die über die fetch-API arbeiten.

Dank einer einheitlichen API auf allen Plattformen sieht der Code zum Laden von Daten auf Android, iOS und Desktop gleich aus. Dies reduziert die Code-Duplikation um 60–80% in KMM-Projekten im Vergleich zu separaten Implementierungen auf Retrofit (Android) und URLSession (iOS). Plugins funktionieren ebenfalls ohne Änderungen auf allen Plattformen.

Häufige Fehler bei der Arbeit mit Ktor

Ignorieren des Schließens von HttpClient ist ein häufiger Fehler in Ktor. HttpClient implementiert Closeable und muss beim Beenden der Anwendung über client.close() geschlossen werden. In Android geschieht dies im onDestroy() der Activity oder ViewModel.onCleared(). Ein nicht geschlossener Client führt zu Koroutinen- und Engine-Thread-Leaks.

Falsche Plugin-Reihenfolge kann die Anfrageverarbeitung stören. Beispielsweise sollte ContentNegotiation vor DefaultRequest installiert werden, damit der Inhaltstyp korrekt angewendet wird. Logging sollte zuletzt installiert werden, um die endgültige Version der Anfrage nach allen Änderungen zu protokollieren. Experimentieren Sie mit der Reihenfolge, wenn Plugins sich unerwartet verhalten.

Fehlende Ausnahmebehandlung in suspend-Funktionen. Ktor wirft IOException bei Netzwerkfehlern und ClientRequestException bei HTTP-4xx-Status. Ein try-catch-Block ist für jeden Aufruf von get(), post() und anderen Methoden obligatorisch. Verwenden Sie HttpResponseValidator im HttpClient-Block für globale Fehlerbehandlung ohne try-catch-Duplizierung in jeder Methode.