Ktor — nyckelbegrepp, klientbibliotek och Kotlin Multiplatform

Vad är Ktor?

Ktor — är ett ramverk för att skapa HTTP-klienter och servrar på språket Kotlin, utvecklat av företaget JetBrains. Till skillnad från traditionella bibliotek har Ktor från början utformats för multiplattformsutveckling och fungerar på alla plattformar som stöds av Kotlin.

Ktor använder en metod med mellanliggande hanterare, inspirerad av arkitekturen i Kodein och Express.js. Varje förfrågan passerar genom en pipeline av hanterarfunktioner som kan modifiera förfrågan och svar. Detta ger flexibilitet som inte är tillgänglig i bibliotek med stel arkitektur baserad på annotationer.

Den aktuella versionen Ktor 3.0 inkluderar stöd för Kotlin 2.0, K2-kompilatorn och en ny CIO (Coroutine I/O)-motor med förbättrad prestanda. Biblioteket distribueras under licensen Apache 2.0 och är tillgängligt för kommersiellt bruk utan begränsningar.

Klientdelen av Ktor är helt byggd på Kotlin-korutiner, vilket säkerställer effektiv asynkron utförande av förfrågningar utan att blockera trådar. Serverdelen gör det möjligt att skapa HTTP-servrar med routing, förfrågningshantering och WebSocket-anslutningar.

Ktor använder en plugin-arkitektur: alla extra funktioner — loggning, serialisering, autentisering — ansluts via plugin. Detta gör biblioteket modulärt och gör det möjligt att endast ansluta nödvändiga komponenter, vilket minskar storleken på den slutliga applikationen.

Tack vare enhetligt API på alla plattformar behöver utvecklaren inte lära sig olika HTTP-klienter för iOS och Android. I ett multiplattformsprojekt är koden för nätverkslagret helt delad och den plattformsspecifika implementeringen är dold bakom HttpClient-motorn. Detta förkortar utvecklingstiden och minskar antalet fel relaterade till plattformsskillnader.

Viktiga funktioner i Ktor

Ktor erbjuder en uppsättning funktioner som gör det till ett attraktivt val för moderna Kotlin-projekt, särskilt multiplattformsprojekt.

Multiplattformsstöd

Ktor fungerar på JVM, Android, iOS, macOS, Windows, Linux, JavaScript och Wasm. Samma HTTP-klientkod körs på alla plattformar utan ändringar. Detta är en viktig fördel jämfört med bibliotek som är bundna till OkHttp eller URLSession.

Asynkronicitet på korutiner

Kotlin-korutiner ger naturlig asynkronicitet utan återanrop. Varje förfrågan är en suspend-funktion som kan anropas från valfri korutin. Ktor stöder strömning av svar via Flow, vilket är praktiskt för långa anslutningar och WebSocket.

Plugin-arkitektur

Ktor-plugin ansluts via ett install-block och konfigureras separat. Huvudplugin: ContentNegotiation för serialisering, Logging för loggning, Auth för autentisering och WebSockets för tvåvägskommunikation. Varje plugin kan aktiveras eller inaktiveras oberoende.

Felhantering och timeout

Felhantering i Ktor är baserad på undantag. Klassen ClientRequestException kastas vid 4xx-koder, ServerResponseException vid 5xx och IOException vid nätverksfel. Timeout konfigureras via HttpTimeout-plugin, som ställer in väntetiden för anslutning, läsning och skrivning. För återförsök används Retry-plugin med inställningar för antal försök och fördröjning.

Hur fungerar Ktor?

Ktor använder en pipeline-arkitektur där varje förfrågan passerar genom en kedja av hanterare. Klienten skapar en HttpClient-konfiguration med installerade plugin, och varje anrop av get- eller post-metoden passerar genom plugin i den ordning de är anslutna.

HttpClient-arkitektur

HttpClient-objektet skapas med en plattformsspecifik motor: CIO för JVM och Android, Darwin för iOS och macOS, OkHttp för Android-kompatibilitet, Js för webbläsare. Motorn kan väljas explicit eller lämnas för automatiskt val. Varje förfrågan returnerar HttpResponse som innehåller svarstext, rubriker och status.

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 och konfiguration av Ktor

Installation av Ktor görs via Gradle eller Maven. I multiplattformsprojekt anges beroenden i sourceSets för varje mål. Ktor distribueras via Maven Central.

Anslutning via Gradle

I build.gradle.kts lägger du till beroendet ktor-client-core för delad kod och motorn för den specifika plattformen. Ktor-versionen ställs in via en variabel i gradle.properties. Ktor 3.x kräver Kotlin 2.0+ och stöder K2-kompilatorn.

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 används Darwin-motorn som omsluter den inbyggda URLSession. I Kotlin Multiplatform gör detta det möjligt att uppnå maximal prestanda och integration med iOS-systemets cachningsmekanismer. Motorn läggs till som ett separat beroende i iOS sourceSet.

En viktig egenskap hos Ktor — stöd för olika serialiseringsformat via ContentNegotiation. Förutom JSON stöder plugin Protobuf, CBOR, XML och anpassade format. För serialisering används biblioteken kotlinx.serialization eller Jackson och utvecklaren kan växla mellan dem utan att ändra förfrågningskoden.

Exempel på användning av Ktor

Exempel nedan visar typiska scenarier för arbete med Ktor-klienten: grundläggande GET-förfrågan, dataöverföring och arbete med multiplattformskod.

GET-förfrågan med JSON-deserialisering

En enkel GET-förfrågan med automatisk deserialisering av svaret till en dataklass. Ktor använder ContentNegotiation-plugin med kotlinx.serialization för att konvertera JSON till objekt. Koden är koncis och typsäker.

@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-förfrågan med JSON-kropp

POST-förfrågan i Ktor skickar en dataklass som JSON-kropp via post-metoden med contentType och setBody. ContentNegotiation-plugin serialiserar automatiskt objektet till en JSON-sträng. Svaret kan bearbetas synkront eller asynkront.

suspend fun createPost(): Post {
    val newPost = Post(
        id = 0,
        title = "Nytt inlägg",
        body = "Innehåll i inlägget"
    )
    val response = client.post("https://jsonplaceholder.typicode.com/posts") {
        contentType(ContentType.Application.Json)
        setBody(newPost)
    }
    return response.body()
}

Filuppladdning via Multipart

Metoden submitFormWithBinaryData i Ktor gör det möjligt att skicka filer och formulär i multipart-format. Ktor delar automatiskt upp data i delar och lägger till rubriker. För att följa förloppet används onUpload som tar emot byte av skickad data.

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 eller Retrofit: vad ska man välja?

Valet mellan Ktor och Retrofit beror på projektets arkitektur och kraven på multiplattform. Retrofit förblir standarden för Android-only-projekt, medan Ktor är ett bättre val för Kotlin Multiplatform.

Ktor tillhandahåller även inbyggt stöd för WebSocket och SSE (Server-Sent Events), vilket gör det bekvämt för realtidsapplikationer. Retrofit stöder inte WebSocket direkt — för detta krävs ett separat OkHttp WebSocket-bibliotek. Ktor är också lättare att konfigurera för olika miljöer tack vare pluginsystemet där varje plugin ansvarar för en funktion.

Autentisering i Ktor

Auth-plugin i Ktor stöder grundläggande autentisering, Bearer-token, Digest och OAuth2. Konfiguration av autentisering görs deklarativt: utvecklaren anger leverantör, tokenkälla och verkningsområde. Ktor lägger automatiskt till autentiseringsrubriker till förfrågningar och kan uppdatera token när den löper ut.

Om projektet använder Kotlin Multiplatform med delad kod på iOS och Android, är Ktor det enda alternativet som fungerar på båda plattformarna utan extra lager. Retrofit är hårt bundet till OkHttp och JVM, vilket gör det olämpligt för iOS.

För Android-only-projekt erbjuder Retrofit ett mer moget API, fler konverterare och OkHttp-interceptors. Ktor fungerar även i detta scenario, men dess plugin-ekosystem är mindre omfattande. Båda biblioteken stöder korutiner och erbjuder jämförbar prestanda.