Ktor — Grundkonzepte, Client-Bibliothek und Kotlin Multiplatform

Was ist Ktor?

Ktor ist ein Framework zum Erstellen von HTTP-Clients und -Servern in Kotlin, entwickelt von JetBrains. Im Gegensatz zu traditionellen Bibliotheken wurde Ktor von Anfang an für die plattformübergreifende Entwicklung konzipiert und läuft auf allen von Kotlin unterstützten Plattformen.

Ktor verwendet einen Middleware-Handler-Ansatz, inspiriert von der Architektur von Kodein und Express.js. Jede Anfrage durchläuft eine Pipeline von Handler-Funktionen, die die Anfrage und Antwort modifizieren können. Dies bietet eine Flexibilität, die in Bibliotheken mit starrer annotierungsbasierter Architektur nicht verfügbar ist.

Die aktuelle Version Ktor 3.0 enthält Unterstützung für Kotlin 2.0, den K2-Compiler und eine neue CIO (Coroutine I/O)-Engine mit verbesserter Leistung. Die Bibliothek wird unter der Apache 2.0-Lizenz vertrieben und ist ohne Einschränkungen für die kommerzielle Nutzung verfügbar.

Die Client-Seite von Ktor ist vollständig auf Kotlin-Koroutinen aufgebaut und ermöglicht eine effiziente asynchrone Ausführung von Anfragen ohne Thread-Blockierung. Die Server-Seite ermöglicht die Erstellung von HTTP-Servern mit Routing, Anfrageverarbeitung und WebSocket-Verbindungen.

Ktor verwendet eine Plugin-Architektur: Alle zusätzlichen Funktionen — Logging, Serialisierung, Authentifizierung — werden über Plugins angebunden. Dies macht die Bibliothek modular und ermöglicht es, nur die benötigten Komponenten anzubinden, wodurch die Größe der endgültigen Anwendung reduziert wird.

Dank einer einheitlichen API auf allen Plattformen muss der Entwickler keine verschiedenen HTTP-Clients für iOS und Android erlernen. In einem plattformübergreifenden Projekt ist der Code der Netzwerkschicht vollständig gemeinsam genutzt, und die plattformspezifische Implementierung ist hinter der HttpClient-Engine verborgen. Dies reduziert die Entwicklungszeit und verringert die Anzahl von Fehlern im Zusammenhang mit Plattformunterschieden.

Hauptfunktionen von Ktor

Ktor bietet eine Reihe von Funktionen, die es zu einer attraktiven Wahl für moderne Kotlin-Projekte machen, insbesondere für plattformübergreifende.

Plattformübergreifende Unterstützung

Ktor läuft auf JVM, Android, iOS, macOS, Windows, Linux, JavaScript und Wasm. Der gleiche HTTP-Client-Code wird ohne Änderungen auf allen Plattformen ausgeführt. Dies ist ein wesentlicher Vorteil gegenüber Bibliotheken, die an OkHttp oder URLSession gebunden sind.

Asynchron mit Koroutinen

Koroutinen in Kotlin bieten eine natürliche Asynchronität ohne Callbacks. Jede Anfrage ist eine Suspend-Funktion, die von jeder Koroutine aus aufgerufen werden kann. Ktor unterstützt das Streaming von Antworten über Flow, was für lange Verbindungen und WebSocket praktisch ist.

Plugin-Architektur

Ktor-Plugins werden über einen install-Block verbunden und separat konfiguriert. Haupt-Plugins: ContentNegotiation für Serialisierung, Logging für Protokollierung, Auth für Authentifizierung und WebSockets für bidirektionale Kommunikation. Jedes Plugin kann unabhängig aktiviert oder deaktiviert werden.

Fehlerbehandlung und Timeouts

Die Fehlerbehandlung in Ktor basiert auf Ausnahmen. Die Klasse ClientRequestException wird bei 4xx-Codes ausgelöst, ServerResponseException bei 5xx und IOException bei Netzwerkfehlern. Timeouts werden über das HttpTimeout-Plugin konfiguriert, das die Wartezeit für Verbindung, Lesen und Schreiben festlegt. Für Wiederholungsversuche wird das Retry-Plugin mit Einstellungen für Anzahl der Versuche und Verzögerung verwendet.

Wie funktioniert Ktor?

Ktor verwendet eine Pipeline-Architektur, bei der jede Anfrage eine Kette von Handlern durchläuft. Der Client erstellt eine HttpClient-Konfiguration mit installierten Plugins, und jeder Aufruf von get oder post durchläuft die Plugins in der Reihenfolge ihrer Verbindung.

HttpClient-Architektur

Das HttpClient-Objekt wird mit einer plattformspezifischen Engine erstellt: CIO für JVM und Android, Darwin für iOS und macOS, OkHttp für Android-Kompatibilität, Js für Browser. Die Engine kann explizit ausgewählt oder der automatischen Auswahl überlassen werden. Jede Anfrage gibt ein HttpResponse zurück, das den Antwortkörper, Header und Status enthält.

val client = HttpClient(CIO) {
    install(ContentNegotiation) {
        json(Json {
            ignoreUnknownKeys = true
        })
    }
}

suspend fun fetchUsers(): List<User> {
    return client.get("https://api.example.com/users").body()
}

Installation und Konfiguration von Ktor

Die Installation von Ktor erfolgt über Gradle oder Maven. Für plattformübergreifende Projekte werden die Abhängigkeiten in sourceSets für jedes Ziel angegeben. Ktor wird über Maven Central vertrieben.

Verbindung über Gradle

Fügen Sie in build.gradle.kts die Abhängigkeit ktor-client-core für gemeinsamen Code und eine Engine für die jeweilige Plattform hinzu. Die Ktor-Version wird über eine Variable in gradle.properties festgelegt. Ktor 3.x erfordert Kotlin 2.0+ und unterstützt den K2-Compiler.

val ktorVersion = "3.0.3"

dependencies {
    implementation("io.ktor:ktor-client-core:$ktorVersion")
    implementation("io.ktor:ktor-client-cio:$ktorVersion")
    implementation("io.ktor:ktor-client-content-negotiation:$ktorVersion")
    implementation("io.ktor:ktor-serialization-kotlinx-json:$ktorVersion")
    implementation("io.ktor:ktor-client-logging:$ktorVersion")
}

Konfiguration für iOS

Für iOS wird die Darwin-Engine verwendet, die native URLSession kapselt. In Kotlin Multiplatform bietet dies maximale Leistung und Integration mit den iOS-System-Caching-Mechanismen. Die Engine wird als separate Abhängigkeit im iOS sourceSet hinzugefügt.

Eine wichtige Funktion von Ktor ist die Unterstützung verschiedener Serialisierungsformate über ContentNegotiation. Neben JSON unterstützt das Plugin Protobuf, CBOR, XML und benutzerdefinierte Formate. Für die Serialisierung werden die Bibliotheken kotlinx.serialization oder Jackson verwendet, und der Entwickler kann zwischen ihnen wechseln, ohne den Anfragecode zu ändern.

Beispiele zur Verwendung von Ktor

Die folgenden Beispiele zeigen typische Szenarien für die Arbeit mit dem Ktor-Client: eine einfache GET-Anfrage, Datensendung und Arbeit mit plattformübergreifendem Code.

GET-Anfrage mit JSON-Deserialisierung

Eine einfache GET-Anfrage mit automatischer Deserialisierung der Antwort in eine Data Class. Ktor verwendet das ContentNegotiation-Plugin mit kotlinx.serialization, um JSON in Objekte zu konvertieren. Der Code ist prägnant und typsicher.

@Serializable
data class Post(
    val id: Int,
    val title: String,
    val body: String
)

suspend fun getPosts(): List<Post> {
    val response = client.get("https://jsonplaceholder.typicode.com/posts")
    return response.body()
}

POST-Anfrage mit JSON-Körper

Eine POST-Anfrage in Ktor sendet eine Data Class als JSON-Körper über die post-Methode mit contentType und setBody. Das ContentNegotiation-Plugin serialisiert das Objekt automatisch in einen JSON-String. Die Antwort kann synchron oder asynchron verarbeitet werden.

suspend fun createPost(): Post {
    val newPost = Post(
        id = 0,
        title = "Neuer Beitrag",
        body = "Beitragsinhalt"
    )
    val response = client.post("https://jsonplaceholder.typicode.com/posts") {
        contentType(ContentType.Application.Json)
        setBody(newPost)
    }
    return response.body()
}

Datei-Upload per Multipart

Die submitFormWithBinaryData-Methode in Ktor ermöglicht das Senden von Dateien und Formularen im Multipart-Format. Ktor teilt die Daten automatisch in Teile auf und fügt Header hinzu. Zur Verfolgung des Fortschritts wird onUpload verwendet, das die Bytes der gesendeten Daten empfängt.

suspend fun uploadFile(fileBytes: ByteArray) {
    client.submitFormWithBinaryData(
        url = "https://api.example.com/upload",
        formData = formData {
            append("file", fileBytes, Headers.build {
                append(HttpHeaders.ContentType, "image/png")
                append(HttpHeaders.ContentDisposition, "filename=\"photo.png\"")
            })
        }
    )
}

Ktor oder Retrofit: Was wählen?

Die Wahl zwischen Ktor und Retrofit hängt von der Projektarchitektur und den Plattformanforderungen ab. Retrofit bleibt der Standard für reine Android-Projekte, während Ktor die beste Wahl für Kotlin Multiplatform ist.

Ktor bietet auch integrierte WebSocket- und SSE (Server-Sent Events)-Unterstützung, was es für Echtzeitanwendungen praktisch macht. Retrofit unterstützt WebSocket nicht direkt — dafür ist eine separate OkHttp WebSocket-Bibliothek erforderlich. Ktor ist dank seines Plugin-Systems auch einfacher für verschiedene Umgebungen zu konfigurieren, bei dem jedes Plugin für eine Funktion verantwortlich ist.

Authentifizierung in Ktor

Das Auth-Plugin in Ktor unterstützt Basisauthentifizierung, Bearer-Tokens, Digest und OAuth2. Die Authentifizierungskonfiguration erfolgt deklarativ: Der Entwickler gibt den Anbieter, die Token-Quelle und den Bereich an. Ktor fügt automatisch Authentifizierungs-Header zu Anfragen hinzu und kann das Token bei Ablauf erneuern.

Wenn ein Projekt Kotlin Multiplatform mit gemeinsam genutztem Code auf iOS und Android verwendet, ist Ktor die einzige Option, die ohne zusätzliche Schichten auf beiden Plattformen funktioniert. Retrofit ist eng an OkHttp und JVM gebunden, was es für iOS ungeeignet macht.

Für reine Android-Projekte bietet Retrofit eine ausgereiftere API, eine größere Anzahl von Konvertern und OkHttp-Interceptoren. Ktor funktioniert auch in diesem Szenario, aber sein Plugin-Ökosystem ist weniger umfangreich. Beide Bibliotheken unterstützen Koroutinen und bieten vergleichbare Leistung.