Ktor — кључни појмови, клијентска библиотека и Kotlin Multiplatform

Шта је Ktor?

Ktor — је оквир за креирање ХТТП клијената и сервера на језику Kotlin, развијен од стране компаније JetBrains. За разлику од традиционалних библиотека, Ktor је од почетка пројектован за мултиплатформски развој и ради на свим платформама које Kotlin подржава.

Ktor користи приступ посредничких обрађивача, инспирисан архитектуром Kodein и Express.js. Сваки захтев пролази кроз цевовод функција обрађивача које могу да модификују захтев и одговор. Ово обезбеђује флексибилност која није доступна у библиотекама са крутом архитектуром заснованом на анотацијама.

Тренутна верзија Ktor 3.0 укључује подршку за Kotlin 2.0, K2 компајлер и нови CIO (Coroutine I/O) погон са побољшаним перформансама. Библиотека се дистрибуира под Apache 2.0 лиценцом и доступна је за комерцијалну употребу без ограничења.

Клијентски део Ktor-а је у потпуности изграђен на корутинама Kotlin-а, што обезбеђује ефикасно асинхроно извршавање захтева без блокирања нити. Серверски део омогућава креирање ХТТП сервера са рутирањем, обрадом захтева и WebSocket везама.

Ktor користи архитектуру са додацима: све додатне функције — евидентирање, серијализација, аутентификација — повезују се преко додатака. Ово чини библиотеку модуларном и омогућава повезивање само потребних компоненти, смањујући величину коначне апликације.

Захваљујући јединственом API-ју на свим платформама, програмер не мора да учи различите ХТТП клијенте за iOS и Android. У мултиплатформском пројекту, кôд мрежног слоја је у потпуности заједнички, а имплементација специфична за платформу је скривена иза погона HttpClient. Ово скраћује време развоја и смањује број грешака повезаних са разликама платформи.

Кључне могућности Ktor-а

Ktor пружа скуп функција које га чине атрактивним избором за савремене Kotlin пројекте, посебно мултиплатформске.

Мултиплатформска подршка

Ktor ради на JVM, Android, iOS, macOS, Windows, Linux, JavaScript и Wasm. Исти кôд ХТТП клијента ради на свим платформама без измена. Ово је кључна предност у односу на библиотеке везане за OkHttp или URLSession.

Асинхроност на корутинама

Корутине Kotlin-а обезбеђују природну асинхроност без повратних позива. Сваки захтев је suspend-функција која се може позвати из било које корутине. Ktor подржава стримовање одговора путем Flow-а, што је погодно за дугачке везе и WebSocket.

Архитектура са додацима

Додаци Ktor-а се повезују преко install блока и конфигуришу се одвојено. Главни додаци: ContentNegotiation за серијализацију, Logging за евидентирање, Auth за аутентификацију и WebSockets за двосмерну комуникацију. Сваки додатак се може укључити или искључити независно.

Обрада грешака и временска ограничења

Обрада грешака у Ktor-у је заснована на изузецима. Класа ClientRequestException се баца при кодовима 4xx, ServerResponseException при 5xx, а IOException при мрежним грешкама. Временска ограничења се подешавају преко HttpTimeout додатка, који одређује време чекања за везу, читање и писање. За поновне покушаје користи се Retry додатак са подешавањима броја покушаја и кашњења.

Како ради Ktor?

Ktor користи цевоводну архитектуру, где сваки захтев пролази кроз ланац обрађивача. Клијент креира конфигурацију HttpClient са инсталираним додацима, и сваки позив методе get или post пролази кроз додатке редом којим су повезани.

Архитектура HttpClient

Објекат HttpClient се креира са погоном специфичним за платформу: CIO за JVM и Android, Darwin за iOS и macOS, OkHttp за Android компатибилност, Js за прегледач. Погон се може експлицитно изабрати или оставити аутоматски избор. Сваки захтев враћа HttpResponse, који садржи тело одговора, заглавља и статус.

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

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

Инсталација и подешавање Ktor-а

Инсталација Ktor-а се врши преко Gradle-а или Maven-а. У мултиплатформским пројектима, зависности се наводе у sourceSets за сваки циљ. Ktor се дистрибуира преко Maven Central-а.

Повезивање преко Gradle-а

У build.gradle.kts додајте зависност ktor-client-core за заједнички кôд и погон за конкретну платформу. Верзија Ktor-а се подешава преко променљиве у gradle.properties. Ktor 3.x захтева Kotlin 2.0+ и подржава 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")
}

Подешавање за iOS

За iOS се користи Darwin погон, који облаже изворни URLSession. У Kotlin Multiplatform, ово омогућава максималне перформансе и интеграцију са системским механизмима кеширања iOS-а. Погон се додаје као посебна зависност у iOS sourceSet.

Важна карактеристика Ktor-а — подршка за различите формате серијализације путем ContentNegotiation-а. Поред JSON-а, додатак подржава Protobuf, CBOR, XML и прилагођене формате. За серијализацију се користе библиотеке kotlinx.serialization или Jackson, а програмер може да прелази између њих без промене кôда захтева.

Примери коришћења Ktor-а

Примери испод приказују типичне сценарије рада са Ktor клијентом: основни GET захтев, слање података и рад са мултиплатформским кодом.

GET захтев са десеријализацијом JSON-а

Једноставан GET захтев са аутоматском десеријализацијом одговора у data-класу. Ktor користи ContentNegotiation додатак са kotlinx.serialization за конверзију JSON-а у објекте. Кôд је концизан и типно безбедан.

@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 захтев са JSON телом

POST захтев у Ktor-у шаље data-класу као JSON тело путем post методе са contentType и setBody. ContentNegotiation додатак аутоматски серијализује објекат у JSON стринг. Одговор се може обрадити синхроно или асинхроно.

suspend fun createPost(): Post {
    val newPost = Post(
        id = 0,
        title = "Нова објава",
        body = "Садржај објаве"
    )
    val response = client.post("https://jsonplaceholder.typicode.com/posts") {
        contentType(ContentType.Application.Json)
        setBody(newPost)
    }
    return response.body()
}

Отпремање датотеке путем Multipart-а

Метода submitFormWithBinaryData у Ktor-у омогућава слање датотека и форми у multipart формату. Ktor аутоматски раздваја податке на делове и додаје заглавља. За праћење напретка користи се onUpload, који прима бајтове послатих података.

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 или Retrofit: шта одабрати?

Избор између Ktor-а и Retrofit-а зависи од архитектуре пројекта и захтева за мултиплатформношћу. Retrofit остаје стандард за Android-only пројекте, док је Ktor бољи избор за Kotlin Multiplatform.

Ktor такође пружа уграђену подршку за WebSocket и SSE (Server-Sent Events), што га чини погодним за апликације у реалном времену. Retrofit не подржава WebSocket директно — за то је потребна посебна OkHttp WebSocket библиотека. Ktor се такође лакше конфигурише за различита окружења захваљујући систему додатака, где сваки додатак одговара за једну функцију.

Аутентификација у Ktor-у

Додатак Auth у Ktor-у подржава основну аутентификацију, Bearer токене, Digest и OAuth2. Подешавање аутентификације се врши декларативно: програмер наводи провајдера, извор токена и област деловања. Ktor аутоматски додаје заглавља аутентификације захтевима и може да освежи токен када истекне.

Ако пројекат користи Kotlin Multiplatform са заједничким кодом на iOS и Android-у, Ktor је једина опција која ради на обе платформе без додатних слојева. Retrofit је чврсто везан за OkHttp и JVM, што га чини непогодним за iOS.

За Android-only пројекте, Retrofit пружа зрелији API, већи број конвертера и OkHttp пресретача. Ktor у овом сценарију такође ради, али његов екосистем додатака је мање обиман. Обе библиотеке подржавају корутине и пружају упоредиве перформансе.