Ktor: co to je, vlastnosti asynchronního HTTP klienta

Co je Ktor?

Ktor je framework pro vytváření asynchronních serverových a klientských aplikací v Kotlinu, vytvořený společností JetBrains. Ktor Client — klientská část frameworku, poskytující HTTP klienta s plnou podporou korutin Kotlinu, multiplatformnosti (JVM, Native, JS) a modulární architektury založené na pluginech.

Ktor se objevil v roce 2018 jako alternativa k Retrofit a OkHttp pro projekty zaměřené na Kotlin. Na rozdíl od Retrofit, který portoval přístup Javy s anotacemi, používá Ktor Client Kotlin DSL pro konfiguraci požadavků — bez anotací a reflexe. To činí kód čitelnějším a typově bezpečnějším pro vývojáře v Kotlinu.

Podle průzkumu Kotlin Multiplatform 2024 se Ktor Client používá ve 35 % projektů Kotlin Multiplatform Mobile (KMM), což ho činí druhým nejoblíbenějším HTTP klientem po OkHttp v komunitě Kotlinu. Ktor je preferován v projektech, kde je důležitá multiplatformnost a nativní integrace s ekosystémem Kotlinu.

Jak funguje Ktor Client

Architektura Ktor Client je založena na potrubí (pipeline) pluginů. Každý požadavek prochází sekvencí nainstalovaných pluginů, které mohou požadavek, odpověď upravit nebo provádět vedlejší akce — logování, kompresi, serializaci, autentizaci.

Při vytváření HTTP klienta pomocí bloku HttpClient { } DSL zadáte engine (OkHttp, Android, CIO, Darwin) a nainstalujete pluginy. Každý engine implementuje odesílání požadavků na nízké úrovni pro konkrétní platformu: na Androidu se používá engine OkHttp, na iOS — Darwin (URLSession), na Desktop — CIO (Coroutine-based I/O). HttpClient automaticky vybírá optimální engine pro aktuální platformu.

Požadavek v Ktor Client se provádí pomocí funkce suspend, což znamená plnou integraci s korutinami. Žádné Callback, RxJava nebo LiveData — pouze sekvenční kód se suspend, který funguje asynchronně bez blokování vlákna.

Potrubí zpracování požadavku

Potrubí Ktor se skládá z fází: nejprve požadavek prochází nainstalovanými pluginy (např. ContentNegotiation pro JSON, Logging pro logy), poté engine provede HTTP požadavek a odpověď znovu prochází pluginy pro deserializaci. Každý plugin je funkce suspend, která se provádí v korutině potrubí.

Důležitou výhodou potrubí Ktor je možnost podmíněného zpracování. Plugin může zkontrolovat URL nebo hlavičky požadavku a přeskočit zpracování, pokud není podmínka splněna. Například ContentEncoding s gzip se aplikuje pouze na odpovědi obsahující hlavičku Content-Encoding: gzip, a Auth funguje pouze pro chráněné endpointy, aniž by ovlivňoval veřejná API.

Tento přístup potrubí umožňuje flexibilní kombinování pluginů: můžete nainstalovat ContentNegotiation s JSON, přidat Auth s Bearer tokenem, zapnout kompresi ContentEncoding a HttpTimeout — a všechny budou spolupracovat ve správném pořadí. Pořadí instalace pluginů je důležité: první nainstalovaný zpracuje požadavek dříve než ostatní.

Pluginy Ktor Client

Pluginy — modulární rozšiřovací systém Ktor, který nahrazuje anotace Retrofit a interceptory OkHttp. Každý plugin řeší konkrétní úkol a instaluje se pomocí funkce install() v bloku HttpClient. Ktor poskytuje vestavěné pluginy a také umožňuje vytvářet vlastní.

Vlastní pluginy

Pro specifické úkoly se vytváří vlastní plugin pomocí createClientPlugin. Plugin může zachytávat požadavek (onRequest), odpověď (onResponse) nebo zpracovávat chyby (onError). To zcela nahrazuje Interceptor z OkHttp, ale s typovaným Kotlin-API a podporou funkcí suspend.

Vlastní pluginy jsou vhodné pro přidávání metrik, automatické logiky opakování, trasování požadavků nebo A/B testování endpointů. Na rozdíl od interceptorů OkHttp jsou pluginy Ktor napsány v Kotlinu a pracují v kontextu korutiny, což zjednodušuje zpracování chyb a časových limitů.

Pro ladění požadavků se používá plugin Logging s úrovní ALL, HEADERS nebo BODY. Logging zobrazuje metodu, URL, status, hlavičky a tělo požadavku a odpovědi. Na rozdíl od HttpLoggingInterceptor z OkHttp pracuje Ktor Logging asynchronně a lze jej nakonfigurovat pro filtrování podle úrovně logu (ERROR, WARN, INFO, DEBUG) bez zastavení aplikace pro změnu konfigurace.

Příklady kódu Ktor Client v Kotlinu

Podívejme se na základní GET požadavek přes Ktor Client. Vytvoří se HttpClient s nainstalovaným pluginem ContentNegotiation pro JSON. Požadavek se provádí pomocí funkce suspend get(), výsledek se automaticky deserializuje do 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()
}

Pro POST požadavek s tělem se používá funkce post() s contentType() a body(). Ktor automaticky serializuje objekt do JSON přes nainstalovaný ContentNegotiation. Styl DSL činí kód sekvenčním a čitelným.

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

Konfigurace časových limitů a hlaviček

HttpTimeout a DefaultRequest — dva klíčové pluginy pro konfiguraci. HttpTimeout nastavuje časové limity a DefaultRequest určuje hlavičky a parametry URL pro všechny požadavky, čímž eliminuje duplikaci kódu v každém volání.

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

Multiplatformní podpora Ktor

Multiplatformnost — hlavní výhoda Ktor oproti OkHttp a Retrofit. Ktor Client pracuje na JVM (Android, Server), Native (iOS, macOS, Windows, Linux) a JS (Browser). Stejný kód HTTP klienta běží na všech platformách bez změn, což je zvláště cenné pro projekty Kotlin Multiplatform.

Pro každou platformu Ktor používá vlastní engine. Na Androidu se standardně aplikuje engine OkHttp, který poskytuje plnou kompatibilitu s ekosystémem OkHttp. Na iOS se používá DarwinEngine založený na URLSession. Pro Server — CIOEngine (Coroutine I/O). Engine lze explicitně zadat: HttpClient(OkHttp) { } nebo HttpClient(Darwin) { }.

Při výběru enginu zohledněte jeho schopnosti: engine OkHttp podporuje HTTP/2 a fond spojení, DarwinEngine — nativní integraci se sítí iOS a relace na pozadí URLSession, CIOEngine — čistou implementaci korutin bez externích závislostí. Pro Web cíle se používá JsEngine nebo BrowserEngine pracující přes fetch API.

Díky jednotnému API na všech platformách vypadá kód pro načítání dat stejně na Androidu, iOS i Desktopu. To snižuje duplikaci kódu o 60–80 % v projektech KMM ve srovnání s oddělenými implementacemi na Retrofit (Android) a URLSession (iOS). Pluginy také fungují na všech platformách beze změn.

Typické chyby při práci s Ktor

Ignorování uzavření HttpClient — častá chyba v Ktor. HttpClient implementuje Closeable a musí být uzavřen při ukončení aplikace pomocí client.close(). V Androidu se to provádí v onDestroy() aktivity nebo ViewModel.onCleared(). Neuzavřený klient vede k úniku korutin a vláken enginu.

Nesprávné pořadí pluginů může narušit zpracování požadavku. Například ContentNegotiation by měl být nainstalován před DefaultRequest, aby byl typ obsahu správně aplikován. Logging se doporučuje instalovat jako poslední, aby se logovala konečná verze požadavku po všech úpravách. Experimentujte s pořadím, pokud se pluginy chovají neočekávaně.

Chybějící zpracování výjimek v suspend funkcích. Ktor vyhazuje IOException při síťových chybách a ClientRequestException při stavech HTTP 4xx. Blok try-catch je povinný pro každé volání get(), post() a dalších metod. Použijte HttpResponseValidator v bloku HttpClient pro globální zpracování chyb bez duplikace try-catch v každé metodě.