Ktor — mga pangunahing konsepto, aklatan ng kliyente at Kotlin Multiplatform

Ano ang Ktor?

Ktor — ay isang framework para sa paggawa ng mga HTTP client at server sa wikang Kotlin, na binuo ng kumpanyang JetBrains. Hindi tulad ng mga tradisyonal na aklatan, ang Ktor ay idinisenyo mula sa simula para sa multiplatform development at gumagana sa lahat ng platform na sinusuportahan ng Kotlin.

Ginagamit ng Ktor ang diskarte ng mga intermediate handler, na inspirasyon ng arkitektura ng Kodein at Express.js. Ang bawat kahilingan ay dumadaan sa isang pipeline ng mga handler function na maaaring magbago ng kahilingan at tugon. Nagbibigay ito ng flexibility na hindi magagamit sa mga aklatan na may matibay na arkitektura batay sa mga anotasyon.

Ang kasalukuyang bersyon na Ktor 3.0 ay may kasamang suporta para sa Kotlin 2.0, K2 compiler, at bagong CIO (Coroutine I/O) engine na may pinahusay na pagganap. Ang aklatan ay ipinamamahagi sa ilalim ng lisensyang Apache 2.0 at magagamit para sa komersyal na paggamit nang walang mga paghihigpit.

Ang bahagi ng kliyente ng Ktor ay ganap na binuo sa mga coroutine ng Kotlin, na tinitiyak ang mahusay na asynchronous na pagpapatupad ng mga kahilingan nang hindi hinaharangan ang mga thread. Ang bahagi ng server ay nagpapahintulot sa paggawa ng mga HTTP server na may routing, pagproseso ng kahilingan, at mga koneksyong WebSocket.

Gumagamit ang Ktor ng arkitekturang plugin: lahat ng karagdagang function — pag-log, serialization, authentication — ay ikinokonekta sa pamamagitan ng mga plugin. Ginagawa nitong modular ang aklatan at pinapayagan na ikonekta lamang ang mga kinakailangang bahagi, na binabawasan ang laki ng huling aplikasyon.

Salamat sa pare-parehong API sa lahat ng platform, hindi kailangang matutunan ng developer ang iba't ibang HTTP client para sa iOS at Android. Sa isang multiplatform na proyekto, ang code ng layer ng network ay ganap na ibinabahagi, at ang implementasyong tukoy sa platform ay nakatago sa likod ng engine ng HttpClient. Pinapaikli nito ang oras ng pag-develop at binabawasan ang bilang ng mga error na nauugnay sa mga pagkakaiba ng platform.

Mga pangunahing tampok ng Ktor

Ktor ay nag-aalok ng isang hanay ng mga tampok na ginagawa itong isang kaakit-akit na pagpipilian para sa mga modernong proyekto ng Kotlin, lalo na sa mga multiplatform.

Suporta sa multiplatform

Ktor ay gumagana sa JVM, Android, iOS, macOS, Windows, Linux, JavaScript at Wasm. Ang parehong HTTP client code ay tumatakbo sa lahat ng platform nang walang mga pagbabago. Ito ay isang pangunahing bentahe kumpara sa mga aklatan na nakatali sa OkHttp o URLSession.

Asynchrony sa mga coroutine

Coroutine ng Kotlin ay nagbibigay ng natural na asynchrony nang walang callback. Ang bawat kahilingan ay isang suspend-function na maaaring tawagin mula sa anumang coroutine. Sinusuportahan ng Ktor ang streaming ng mga tugon sa pamamagitan ng Flow, na maginhawa para sa mahabang koneksyon at WebSocket.

Arkitekturang plugin

Mga plugin ng Ktor ay ikinokonekta sa pamamagitan ng install block at naka-configure nang hiwalay. Mga pangunahing plugin: ContentNegotiation para sa serialization, Logging para sa pag-log, Auth para sa authentication, at WebSockets para sa two-way na komunikasyon. Ang bawat plugin ay maaaring i-activate o i-deactivate nang nakapag-iisa.

Pangangasiwa ng error at timeout

Pangangasiwa ng error sa Ktor ay batay sa mga exception. Ang klase na ClientRequestException ay itinapon sa mga code na 4xx, ServerResponseException sa 5xx, at IOException sa mga error sa network. Ang mga timeout ay naka-configure sa pamamagitan ng HttpTimeout plugin, na nagtatakda ng oras ng paghihintay para sa koneksyon, pagbasa, at pagsulat. Para sa mga pagsubok muli, ginagamit ang Retry plugin na may mga setting ng bilang ng pagsubok at pagkaantala.

Paano gumagana ang Ktor?

Ktor ay gumagamit ng pipeline architecture, kung saan ang bawat kahilingan ay dumadaan sa isang chain ng mga handler. Gumagawa ang client ng konfigurasyon ng HttpClient na may mga naka-install na plugin, at ang bawat tawag sa get o post method ay dumadaan sa mga plugin sa pagkakasunud-sunod ng pagkakakonekta ng mga ito.

Arkitektura ng HttpClient

Ang object ng HttpClient ay ginawa gamit ang engine na tukoy sa platform: CIO para sa JVM at Android, Darwin para sa iOS at macOS, OkHttp para sa compatibility ng Android, Js para sa browser. Ang engine ay maaaring piliin nang tahasan o iwanan ang awtomatikong pagpili. Ang bawat kahilingan ay nagbabalik ng HttpResponse na naglalaman ng body ng tugon, mga header, at 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()
}

Pag-install at pagsasaayos ng Ktor

Pag-install ng Ktor ay ginagawa sa pamamagitan ng Gradle o Maven. Sa mga multiplatform na proyekto, ang mga dependency ay tinutukoy sa sourceSets para sa bawat target. Ang Ktor ay ipinamamahagi sa pamamagitan ng Maven Central.

Pagkonekta sa pamamagitan ng Gradle

Sa build.gradle.kts idagdag ang dependency na ktor-client-core para sa shared code at engine para sa partikular na platform. Ang bersyon ng Ktor ay itinakda sa pamamagitan ng variable sa gradle.properties. Ang Ktor 3.x ay nangangailangan ng Kotlin 2.0+ at sinusuportahan ang K2 compiler.

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

Pagsasaayos para sa iOS

Para sa iOS ginagamit ang Darwin engine, na bumabalot sa native URLSession. Sa Kotlin Multiplatform, pinapayagan nito ang maximum na pagganap at integrasyon sa mga mekanismo ng system caching ng iOS. Ang engine ay idinagdag bilang isang hiwalay na dependency sa iOS sourceSet.

Isang mahalagang tampok ng Ktor — suporta para sa iba't ibang format ng serialization sa pamamagitan ng ContentNegotiation. Bukod sa JSON, sinusuportahan ng plugin ang Protobuf, CBOR, XML at mga custom na format. Para sa serialization, ginagamit ang mga aklatan na kotlinx.serialization o Jackson, at ang developer ay maaaring lumipat sa pagitan ng mga ito nang hindi binabago ang code ng mga kahilingan.

Mga halimbawa ng paggamit ng Ktor

Mga halimbawa sa ibaba ay nagpapakita ng mga tipikal na sitwasyon ng pagtatrabaho sa Ktor client: pangunahing GET request, pagpapadala ng data, at pagtatrabaho sa multiplatform code.

GET request na may JSON deserialization

Isang simpleng GET request na may awtomatikong deserialization ng tugon sa isang data-class. Ginagamit ng Ktor ang ContentNegotiation plugin na may kotlinx.serialization para sa pag-convert ng JSON sa mga object. Ang code ay maikli at type-safe.

@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 request na may JSON body

Ang POST request sa Ktor ay nagpapadala ng data-class bilang JSON body sa pamamagitan ng post method na may contentType at setBody. Ang ContentNegotiation plugin ay awtomatikong nagsa-serialize ng object sa JSON string. Ang tugon ay maaaring iproseso nang sabay-sabay o asynchronous.

suspend fun createPost(): Post {
    val newPost = Post(
        id = 0,
        title = "Bagong post",
        body = "Nilalaman ng post"
    )
    val response = client.post("https://jsonplaceholder.typicode.com/posts") {
        contentType(ContentType.Application.Json)
        setBody(newPost)
    }
    return response.body()
}

Pag-upload ng file sa pamamagitan ng Multipart

Ang method na submitFormWithBinaryData sa Ktor ay nagpapahintulot sa pagpapadala ng mga file at form sa multipart format. Awtomatikong hinahati ng Ktor ang data sa mga bahagi at nagdaragdag ng mga header. Para sa pagsubaybay sa progreso, ginagamit ang onUpload na tumatanggap ng mga byte ng ipinadalang 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 o Retrofit: alin ang pipiliin?

Pagpili sa pagitan ng Ktor at Retrofit ay depende sa arkitektura ng proyekto at mga kinakailangan para sa multiplatform. Ang Retrofit ay nananatiling pamantayan para sa Android-only na mga proyekto, habang ang Ktor ay ang mas mahusay na pagpipilian para sa Kotlin Multiplatform.

Nagbibigay din ang Ktor ng built-in na suporta para sa WebSocket at SSE (Server-Sent Events), na ginagawang maginhawa para sa mga real-time na aplikasyon. Hindi direktang sinusuportahan ng Retrofit ang WebSocket — para dito kinakailangan ang isang hiwalay na OkHttp WebSocket library. Ang Ktor ay mas madali ring i-configure para sa iba't ibang kapaligiran dahil sa sistema ng plugin, kung saan ang bawat plugin ay may pananagutan para sa isang function.

Authentication sa Ktor

Ang Auth plugin sa Ktor ay sumusuporta sa basic authentication, Bearer token, Digest at OAuth2. Ang pagsasaayos ng authentication ay ginagawa nang deklaratibo: tinutukoy ng developer ang provider, source ng token, at saklaw ng aksyon. Awtomatikong nagdaragdag ang Ktor ng mga authentication header sa mga kahilingan at maaaring mag-refresh ng token kapag nag-expire ito.

Kung ang proyekto ay gumagamit ng Kotlin Multiplatform na may shared code sa iOS at Android, ang Ktor ay ang tanging opsyon na gumagana sa parehong platform nang walang karagdagang mga layer. Ang Retrofit ay mahigpit na nakatali sa OkHttp at JVM, na ginagawa itong hindi angkop para sa iOS.

Para sa mga proyektong Android-only, ang Retrofit ay nagbibigay ng mas mature na API, mas maraming converter, at OkHttp interceptor. Gumagana rin ang Ktor sa sitwasyong ito, ngunit ang ecosystem ng plugin nito ay hindi gaanong malawak. Ang parehong mga aklatan ay sumusuporta sa coroutine at nagbibigay ng maihahambing na pagganap.