Ktor — kulcsfogalmak, klienskönyvtár és Kotlin Multiplatform

Mi az a Ktor?

Ktor — egy keretrendszer HTTP-kliens és szerver létrehozásához Kotlin nyelven, amelyet a JetBrains cég fejlesztett ki. A hagyományos könyvtáraktól eltérően a Ktor a kezdetektől fogva többplatformos fejlesztésre lett tervezve, és a Kotlin által támogatott összes platformon működik.

A Ktor a köztes kezelők megközelítését használja, amelyet a Kodein és az Express.js architektúrája ihletett. Minden kérés áthalad a kezelőfüggvények csővezetékén, amelyek módosíthatják a kérést és a választ. Ez olyan rugalmasságot biztosít, amely nem elérhető a merev, annotációkra épülő architektúrájú könyvtárakban.

A jelenlegi Ktor 3.0 verzió támogatást nyújt a Kotlin 2.0-hoz, a K2 fordítóhoz és egy új CIO (Coroutine I/O) motorhoz, javított teljesítménnyel. A könyvtár az Apache 2.0 licenc alatt kerül terjesztésre, és korlátozások nélkül használható kereskedelmi célokra.

A Ktor kliens része teljes egészében Kotlin korutinokra épül, ami biztosítja a kérések hatékony aszinkron végrehajtását a szálak blokkolása nélkül. A szerver rész lehetővé teszi HTTP szerverek létrehozását útválasztással, kérések feldolgozásával és WebSocket kapcsolatokkal.

A Ktor plugin architektúrát használ: minden további funkció — naplózás, szerializáció, hitelesítés — plugineken keresztül csatlakozik. Ez modulárisá teszi a könyvtárat, és lehetővé teszi, hogy csak a szükséges komponenseket csatlakoztassa, csökkentve a végleges alkalmazás méretét.

Az egységes API-nak köszönhetően az összes platformon a fejlesztőnek nem kell különböző HTTP-klienseket tanulnia iOS és Android rendszerhez. Egy többplatformos projektben a hálózati réteg kódja teljesen megosztott, a platformspecifikus megvalósítás pedig a HttpClient motor mögött van elrejtve. Ez lerövidíti a fejlesztési időt és csökkenti a platformok közötti különbségekből adódó hibák számát.

A Ktor legfontosabb funkciói

A Ktor olyan funkciókat kínál, amelyek vonzó választássá teszik modern Kotlin projektekhez, különösen többplatformos projektekhez.

Többplatformos támogatás

A Ktor JVM, Android, iOS, macOS, Windows, Linux, JavaScript és Wasm környezetben működik. Ugyanaz a HTTP-kliens kód minden platformon változtatás nélkül fut. Ez kulcsfontosságú előny az OkHttp vagy URLSession kötött könyvtárakhoz képest.

Aszinkronitás korutinokon

A Kotlin korutinok természetes aszinkronitást biztosítanak visszahívások nélkül. Minden kérés egy suspend-függvény, amely bármely korutinból meghívható. A Ktor támogatja a válaszok streamelését Flow-n keresztül, ami kényelmes hosszú kapcsolatokhoz és WebSockethez.

Plugin architektúra

A Ktor pluginei az install blokkon keresztül csatlakoznak és külön konfigurálhatók. Főbb pluginek: ContentNegotiation a szerializációhoz, Logging a naplózáshoz, Auth a hitelesítéshez és WebSockets a kétirányú kommunikációhoz. Minden plugin egymástól függetlenül aktiválható vagy deaktiválható.

Hibakezelés és időtúllépések

A hibakezelés a Ktorban kivételeken alapul. A ClientRequestException osztály 4xx kódoknál, a ServerResponseException 5xx-nél, az IOException pedig hálózati hibáknál kerül kiváltásra. Az időtúllépések a HttpTimeout pluginon keresztül konfigurálhatók, amely beállítja a várakozási időt a kapcsolódáshoz, olvasáshoz és íráshoz. Az újrapróbálkozásokhoz a Retry plugin használható a próbálkozások számának és késleltetésének beállításával.

Hogyan működik a Ktor?

A Ktor csővezeték-architektúrát használ, ahol minden kérés áthalad a kezelők láncán. A kliens létrehoz egy HttpClient konfigurációt a telepített pluginekkel, és minden get vagy post metódus hívás áthalad a plugineken a csatlakoztatásuk sorrendjében.

HttpClient architektúra

Az HttpClient objektum egy platformspecifikus motorral jön létre: CIO a JVM és Android, Darwin az iOS és macOS, OkHttp az Android kompatibilitáshoz, Js a böngészőhöz. A motor kifejezetten kiválasztható, vagy hagyható az automatikus választás. Minden kérés egy HttpResponse-t ad vissza, amely tartalmazza a válasz törzsét, fejléceit és státuszát.

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

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

A Ktor telepítése és konfigurálása

A Ktor telepítése Gradle vagy Maven segítségével történik. Többplatformos projektekben a függőségek a sourceSets-ben vannak megadva minden célplatformhoz. A Ktor a Maven Centralen keresztül terjeszthető.

Csatlakoztatás Gradle segítségével

A build.gradle.kts fájlban adja hozzá a ktor-client-core függőséget a megosztott kódhoz és a motort az adott platformhoz. A Ktor verziója egy változón keresztül van beállítva a gradle.properties fájlban. A Ktor 3.x Kotlin 2.0+ verziót igényel, és támogatja a K2 fordítót.

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

Konfigurálás iOS rendszerhez

iOS rendszerhez a Darwin motor használatos, amely a natív URLSession-t burkolja be. Kotlin Multiplatformban ez lehetővé teszi a maximális teljesítményt és az iOS rendszergyorsítótár mechanizmusaival való integrációt. A motor külön függőségként kerül hozzáadásra az iOS sourceSet-ben.

A Ktor fontos jellemzője — különböző szerializációs formátumok támogatása a ContentNegotiation segítségével. A JSON mellett a plugin támogatja a Protobuf, CBOR, XML és egyéni formátumokat is. A szerializációhoz a kotlinx.serialization vagy Jackson könyvtárak használhatók, és a fejlesztő a kérések kódjának módosítása nélkül válthat közöttük.

Példák a Ktor használatára

Az alábbi példák a Ktor klienssel való munka tipikus forgatókönyveit mutatják be: alap GET kérés, adatok küldése és többplatformos kóddal való munka.

GET kérés JSON deszerializációval

Egy egyszerű GET kérés a válasz automatikus deszerializációjával egy data-osztályba. A Ktor a ContentNegotiation plugint használja a kotlinx.serialization segítségével a JSON objektumokká alakításához. A kód tömör és típusbiztos.

@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 kérés JSON törzzsel

A POST kérés a Ktorban egy data-osztályt küld JSON törzsként a post metóduson keresztül contentType és setBody segítségével. A ContentNegotiation plugin automatikusan szerializálja az objektumot JSON stringgé. A válasz feldolgozható szinkron vagy aszinkron módon.

suspend fun createPost(): Post {
    val newPost = Post(
        id = 0,
        title = "Új bejegyzés",
        body = "Bejegyzés tartalma"
    )
    val response = client.post("https://jsonplaceholder.typicode.com/posts") {
        contentType(ContentType.Application.Json)
        setBody(newPost)
    }
    return response.body()
}

Fájlfeltöltés Multipart segítségével

A submitFormWithBinaryData metódus a Ktorban lehetővé teszi fájlok és űrlapok multipart formátumban történő küldését. A Ktor automatikusan részekre bontja az adatokat és hozzáadja a fejléceket. A folyamat nyomon követéséhez az onUpload használható, amely a küldött adatok bájtjait kapja.

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 vagy Retrofit: mit válasszunk?

A választás a Ktor és a Retrofit között a projekt architektúrájától és a többplatformossági követelményektől függ. A Retrofit továbbra is szabvány a csak Android projektekhez, míg a Ktor jobb választás a Kotlin Multiplatformhoz.

A Ktor beépített támogatást nyújt a WebSocket és SSE (Server-Sent Events) számára is, ami kényelmessé teszi valós idejű alkalmazásokhoz. A Retrofit nem támogatja közvetlenül a WebSocketet — ehhez külön OkHttp WebSocket könyvtárra van szükség. A Ktor a pluginrendszerének köszönhetően is könnyebben konfigurálható különböző környezetekhez, ahol minden plugin egy funkcióért felelős.

Hitelesítés a Ktorban

Az Auth plugin a Ktorban támogatja az alapszintű hitelesítést, Bearer tokeneket, Digest és OAuth2-t. A hitelesítés konfigurálása deklaratív módon történik: a fejlesztő megadja a szolgáltatót, a token forrását és a hatókört. A Ktor automatikusan hozzáadja a hitelesítési fejléceket a kérésekhez, és lejáratkor frissíteni tudja a tokent.

Ha a projekt Kotlin Multiplatformot használ megosztott kóddal iOS és Android rendszeren, a Ktor az egyetlen lehetőség, amely további rétegek nélkül működik mindkét platformon. A Retrofit szorosan kötődik az OkHttp-hoz és a JVM-hez, ami alkalmassá teszi iOS rendszerhez.

Csak Android projektekhez a Retrofit érettebb API-t, több konvertert és OkHttp interceptort biztosít. A Ktor ebben a forgatókönyvben is működik, de plugin ökoszisztémája kevésbé kiterjedt. Mindkét könyvtár támogatja a korutinokat és összehasonlítható teljesítményt nyújt.