Ktor — klíčové pojmy, klientská knihovna a Kotlin Multiplatform

Co je Ktor?

Ktor — je framework pro vytváření HTTP klientů a serverů v jazyce Kotlin, vyvinutý společností JetBrains. Na rozdíl od tradičních knihoven byl Ktor od začátku navržen pro multiplatformní vývoj a funguje na všech platformách podporovaných Kotlinem.

Ktor používá přístup prostředních handlerů, inspirovaný architekturou Kodein a Express.js. Každý požadavek prochází potrubím handlerových funkcí, které mohou požadavek a odpověď upravit. To poskytuje flexibilitu, která není dostupná v knihovnách s pevnou architekturou založenou na anotacích.

Aktuální verze Ktor 3.0 zahrnuje podporu pro Kotlin 2.0, kompilátor K2 a nový engine CIO (Coroutine I/O) s vylepšeným výkonem. Knihovna je distribuována pod licencí Apache 2.0 a je k dispozici pro komerční použití bez omezení.

Klientská část Ktor je plně postavena na korutinách Kotlin, což zajišťuje efektivní asynchronní provádění požadavků bez blokování vláken. Serverová část umožňuje vytváření HTTP serverů s routováním, zpracováním požadavků a WebSocket připojeními.

Ktor používá pluginovou architekturu: všechny doplňkové funkce — logování, serializace, autentizace — se připojují přes pluginy. To činí knihovnu modulární a umožňuje připojit pouze potřebné komponenty, čímž se snižuje velikost výsledné aplikace.

Díky jednotnému API na všech platformách se vývojář nemusí učit různé HTTP klienty pro iOS a Android. V multiplatformním projektu je kód síťové vrstvy zcela sdílený a implementace specifická pro platformu je skryta za enginem HttpClient. To zkracuje dobu vývoje a snižuje počet chyb souvisejících s rozdíly platforem.

Klíčové možnosti Ktor

Ktor nabízí sadu funkcí, které z něj činí atraktivní volbu pro moderní Kotlin projekty, zejména multiplatformní.

Multiplatformní podpora

Ktor funguje na JVM, Android, iOS, macOS, Windows, Linux, JavaScript a Wasm. Stejný kód HTTP klienta běží na všech platformách bez změn. To je klíčová výhoda oproti knihovnám vázaným na OkHttp nebo URLSession.

Asynchronnost na korutinách

Korutiny Kotlin poskytují přirozenou asynchronnost bez zpětných volání. Každý požadavek je suspend-funkce, kterou lze volat z libovolné korutiny. Ktor podporuje streamování odpovědí přes Flow, což je vhodné pro dlouhá připojení a WebSocket.

Pluginová architektura

Pluginy Ktor se připojují přes install blok a konfigurují se samostatně. Hlavní pluginy: ContentNegotiation pro serializaci, Logging pro logování, Auth pro autentizaci a WebSockets pro obousměrnou komunikaci. Každý plugin lze nezávisle zapnout nebo vypnout.

Zpracování chyb a časové limity

Zpracování chyb v Ktor je založeno na výjimkách. Třída ClientRequestException se vyhazuje při kódech 4xx, ServerResponseException při 5xx a IOException při síťových chybách. Časové limity se konfigurují přes plugin HttpTimeout, který nastavuje dobu čekání na připojení, čtení a zápis. Pro opakované pokusy se používá plugin Retry s nastavením počtu pokusů a zpoždění.

Jak Ktor funguje?

Ktor používá potrubní architekturu, kde každý požadavek prochází řetězcem handlerů. Klient vytváří konfiguraci HttpClient s nainstalovanými pluginy a každé volání metody get nebo post prochází pluginy v pořadí jejich připojení.

Architektura HttpClient

Objekt HttpClient se vytváří s enginem specifickým pro platformu: CIO pro JVM a Android, Darwin pro iOS a macOS, OkHttp pro kompatibilitu s Android, Js pro prohlížeč. Engine lze explicitně vybrat nebo ponechat automatický výběr. Každý požadavek vrací HttpResponse, který obsahuje tělo odpovědi, hlavičky a stav.

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

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

Instalace a konfigurace Ktor

Instalace Ktor se provádí přes Gradle nebo Maven. V multiplatformních projektech se závislosti uvádějí v sourceSets pro každý cíl. Ktor je distribuován přes Maven Central.

Připojení přes Gradle

V build.gradle.kts přidejte závislost ktor-client-core pro sdílený kód a engine pro konkrétní platformu. Verze Ktor se nastavuje přes proměnnou v gradle.properties. Ktor 3.x vyžaduje Kotlin 2.0+ a podporuje kompilátor K2.

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

Konfigurace pro iOS

Pro iOS se používá engine Darwin, který obaluje nativní URLSession. V Kotlin Multiplatform to umožňuje dosáhnout maximálního výkonu a integrace se systémovými mechanismy ukládání do mezipaměti iOS. Engine se přidává jako samostatná závislost v iOS sourceSet.

Důležitá vlastnost Ktor — podpora různých formátů serializace přes ContentNegotiation. Kromě JSON plugin podporuje Protobuf, CBOR, XML a vlastní formáty. Pro serializaci se používají knihovny kotlinx.serialization nebo Jackson a vývojář může mezi nimi přepínat bez změny kódu požadavků.

Příklady použití Ktor

Příklady níže demonstrují typické scénáře práce s Ktor klientem: základní GET požadavek, odesílání dat a práce s multiplatformním kódem.

GET požadavek s deserializací JSON

Jednoduchý GET požadavek s automatickou deserializací odpovědi do datové třídy. Ktor používá plugin ContentNegotiation s kotlinx.serialization pro převod JSON na objekty. Kód je stručný a typově bezpečný.

@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 požadavek s JSON tělem

POST požadavek v Ktor odesílá datovou třídu jako JSON tělo přes metodu post s contentType a setBody. Plugin ContentNegotiation automaticky serializuje objekt do JSON řetězce. Odpověď lze zpracovat synchronně nebo asynchronně.

suspend fun createPost(): Post {
    val newPost = Post(
        id = 0,
        title = "Nový příspěvek",
        body = "Obsah příspěvku"
    )
    val response = client.post("https://jsonplaceholder.typicode.com/posts") {
        contentType(ContentType.Application.Json)
        setBody(newPost)
    }
    return response.body()
}

Nahrávání souboru přes Multipart

Metoda submitFormWithBinaryData v Ktor umožňuje odesílat soubory a formuláře ve formátu multipart. Ktor automaticky rozděluje data na části a přidává hlavičky. Pro sledování průběhu se používá onUpload, který přijímá bajty odeslaných dat.

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 nebo Retrofit: co vybrat?

Výběr mezi Ktor a Retrofit závisí na architektuře projektu a požadavcích na multiplatformnost. Retrofit zůstává standardem pro projekty pouze pro Android, zatímco Ktor je lepší volbou pro Kotlin Multiplatform.

Ktor také poskytuje vestavěnou podporu pro WebSocket a SSE (Server-Sent Events), což jej činí vhodným pro aplikace v reálném čase. Retrofit nepodporuje WebSocket přímo — k tomu je zapotřebí samostatná knihovna OkHttp WebSocket. Ktor se také snadněji konfiguruje pro různá prostředí díky pluginovému systému, kde každý plugin odpovídá za jednu funkci.

Autentizace v Ktor

Plugin Auth v Ktor podporuje základní autentizaci, Bearer tokeny, Digest a OAuth2. Konfigurace autentizace se provádí deklarativně: vývojář určuje poskytovatele, zdroj tokenu a oblast působnosti. Ktor automaticky přidává autentizační hlavičky k požadavkům a může obnovit token při jeho vypršení.

Pokud projekt používá Kotlin Multiplatform se sdíleným kódem na iOS a Android, Ktor je jedinou možností, která funguje na obou platformách bez dalších vrstev. Retrofit je pevně vázán na OkHttp a JVM, což jej činí nevhodným pro iOS.

Pro projekty pouze pro Android poskytuje Retrofit zralejší API, více konvertorů a OkHttp interceptory. Ktor v tomto scénáři také funguje, ale jeho pluginový ekosystém je méně rozsáhlý. Obě knihovny podporují korutiny a poskytují srovnatelný výkon.