Ktor: ano ito, mga tampok ng asynchronous HTTP client

Ano ang Ktor?

Ktor ay isang framework para sa pagbuo ng asynchronous server at client application sa Kotlin, na nilikha ng JetBrains. Ang Ktor Client — ang client na bahagi ng framework, na nagbibigay ng HTTP client na may buong suporta para sa Kotlin coroutine, multi-platform (JVM, Native, JS) at modular architecture na nakabatay sa plugin.

Lumitaw ang Ktor noong 2018 bilang alternatibo sa Retrofit at OkHttp para sa mga Kotlin-first project. Hindi tulad ng Retrofit na nag-port ng Java approach na may annotation, ang Ktor Client ay gumagamit ng Kotlin DSL para sa configuration ng request — walang annotation at reflection. Ginagawa nitong mas nababasa at type-safe ang code para sa mga Kotlin developer.

Ayon sa survey ng Kotlin Multiplatform 2024, ang Ktor Client ay ginagamit sa 35% ng mga Kotlin Multiplatform Mobile (KMM) project, na ginagawa itong pangalawang pinakasikat na HTTP client pagkatapos ng OkHttp sa Kotlin community. Mas pinipili ang Ktor sa mga project kung saan mahalaga ang multi-platform at native na integrasyon sa Kotlin ecosystem.

Paano Gumagana ang Ktor Client

Ang arkitektura ng Ktor Client ay batay sa pipeline ng mga plugin. Ang bawat request ay dumadaan sa sequence ng mga naka-install na plugin, na maaaring magbago ng request, response, o magsagawa ng mga side action — logging, compression, serialization, authentication.

Sa paggawa ng HTTP client sa pamamagitan ng HttpClient { } DSL block, tinutukoy mo ang engine (OkHttp, Android, CIO, Darwin) at nag-i-install ng mga plugin. Bawat engine ay nag-i-implement ng low-level na pagpapadala ng request para sa partikular na platform: sa Android ginagamit ang OkHttp engine, sa iOS — Darwin (URLSession), sa Desktop — CIO (Coroutine-based I/O). Ang HttpClient ay awtomatikong pumipili ng optimal engine para sa kasalukuyang platform.

Ang request sa Ktor Client ay ini-execute sa pamamagitan ng suspend function, na nangangahulugang buong integrasyon sa coroutine. Walang Callback, RxJava o LiveData — tanging sequential code na may suspend na gumagana nang asynchronous nang hindi binablock ang thread.

Pipeline ng pagproseso ng request

Ang Ktor pipeline ay binubuo ng mga phase: una ang request ay dumadaan sa mga naka-install na plugin (hal. ContentNegotiation para sa JSON, Logging para sa logs), pagkatapos ay ini-execute ng engine ang HTTP request, at ang response ay dumadaan muli sa mga plugin para sa deserialization. Bawat plugin ay isang suspend function na ini-execute sa coroutine ng pipeline.

Isang mahalagang bentahe ng Ktor pipeline ay ang posibilidad ng conditional processing. Maaaring suriin ng plugin ang URL o headers ng request at laktawan ang processing kung hindi natugunan ang kondisyon. Halimbawa, ang ContentEncoding na may gzip ay inaaplay lamang sa mga response na naglalaman ng header na Content-Encoding: gzip, at ang Auth ay gumagana lamang para sa mga protektadong endpoint nang hindi naaapektuhan ang mga public API.

Ang pipeline approach na ito ay nagbibigay-daan sa flexible na kombinasyon ng mga plugin: maaari kang mag-install ng ContentNegotiation na may JSON, magdagdag ng Auth na may Bearer token, i-enable ang ContentEncoding compression at HttpTimeout — at lahat sila ay magtutulungan sa tamang pagkakasunod-sunod. Mahalaga ang pagkakasunod-sunod ng pag-install ng plugin: ang unang naka-install ay magpoproseso ng request nang mas maaga kaysa sa iba.

Mga Plugin ng Ktor Client

Mga Plugin — ang modular extension system ng Ktor, na pumapalit sa Retrofit annotation at OkHttp interceptor. Bawat plugin ay lumulutas ng partikular na gawain at ini-install sa pamamagitan ng install() function sa HttpClient block. Nagbibigay ang Ktor ng mga built-in na plugin, at pinapayagan din ang paggawa ng custom na plugin.

Custom na plugin

Para sa specific na gawain, gumagawa ng custom na plugin sa pamamagitan ng createClientPlugin. Maaaring i-intercept ng plugin ang request (onRequest), response (onResponse) o mag-handle ng error (onError). Ganap nitong pinapalitan ang Interceptor mula sa OkHttp, ngunit may naka-type na Kotlin-API at suporta para sa suspend functions.

Ang custom na plugin ay kapaki-pakinabang para sa pagdagdag ng metrics, automatic retry logic, pagsubaybay ng request, o A/B testing ng endpoints. Hindi tulad ng OkHttp interceptor, ang Ktor plugin ay nakasulat sa Kotlin at gumagana sa konteksto ng coroutine, na nagpapadali sa pag-handle ng error at timeout.

Para sa debugging ng request, ginagamit ang Logging plugin na may level na ALL, HEADERS o BODY. Ipinapakita ng Logging ang method, URL, status, headers at body ng request at response. Hindi tulad ng HttpLoggingInterceptor mula sa OkHttp, ang Ktor Logging ay gumagana nang asynchronous at maaaring i-configure para sa filtering ayon sa log level (ERROR, WARN, INFO, DEBUG) nang hindi humihinto ang application para sa pagbabago ng configuration.

Mga Halimbawa ng Code ng Ktor Client sa Kotlin

Tingnan natin ang basic GET request sa pamamagitan ng Ktor Client. Gumagawa ng HttpClient na may naka-install na ContentNegotiation plugin para sa JSON. Ang request ay ini-execute sa pamamagitan ng suspend function na get(), ang resulta ay awtomatikong dineserialized sa 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()
}

Para sa POST request na may body ginagamit ang function na post() na may contentType() at body(). Awtomatikong sineserialize ng Ktor ang object sa JSON sa pamamagitan ng naka-install na ContentNegotiation. Ang DSL style ay gumagawa ng code na sequential at nababasa.

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

Configuration ng timeout at headers

HttpTimeout at DefaultRequest — dalawang key plugin para sa configuration. Ang HttpTimeout ay nagtatakda ng time limits, at ang DefaultRequest ay tumutukoy ng headers at URL parameters para sa lahat ng request, inaalis ang code duplication sa bawat tawag.

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

Multi-platform Support ng Ktor

Multi-platform — ang pangunahing bentahe ng Ktor kumpara sa OkHttp at Retrofit. Ang Ktor Client ay gumagana sa JVM (Android, Server), Native (iOS, macOS, Windows, Linux) at JS (Browser). Ang parehong HTTP client code ay tumatakbo sa lahat ng platform nang walang pagbabago, na lalong mahalaga para sa Kotlin Multiplatform project.

Para sa bawat platform, ang Ktor ay gumagamit ng sarili nitong engine. Sa Android, bilang default ay inaaplay ang OkHttp engine, na nagbibigay ng buong compatibility sa OkHttp ecosystem. Sa iOS ginagamit ang DarwinEngine na nakabatay sa URLSession. Para sa Server — CIOEngine (Coroutine I/O). Maaaring tukuyin ang engine nang hayagan: HttpClient(OkHttp) { } o HttpClient(Darwin) { }.

Sa pagpili ng engine, isaalang-alang ang mga kakayahan nito: ang OkHttp engine ay sumusuporta sa HTTP/2 at connection pool, ang DarwinEngine — native na integrasyon sa iOS network at URLSession background session, ang CIOEngine — purong coroutine implementation nang walang external dependencies. Para sa Web targets ginagamit ang JsEngine o BrowserEngine na gumagana sa pamamagitan ng fetch API.

Dahil sa pare-parehong API sa lahat ng platform, ang code para sa pag-load ng data ay pareho sa Android, iOS at Desktop. Binabawasan nito ang code duplication ng 60–80% sa KMM project kumpara sa hiwalay na implementasyon sa Retrofit (Android) at URLSession (iOS). Gumagana rin ang mga plugin sa lahat ng platform nang walang pagbabago.

Mga Karaniwang Pagkakamali sa Paggamit ng Ktor

Pagbalewala sa pagsasara ng HttpClient — karaniwang pagkakamali sa Ktor. Ang HttpClient ay nag-i-implement ng Closeable at dapat isara kapag natapos na ang application sa pamamagitan ng client.close(). Sa Android, ito ay ginagawa sa onDestroy() ng Activity o ViewModel.onCleared(). Ang hindi nakasara na client ay nagdudulot ng pagtagas ng coroutine at engine thread.

Maling pagkakasunod-sunod ng plugin ay maaaring makasira ng pagproseso ng request. Halimbawa, ang ContentNegotiation ay dapat na naka-install bago ang DefaultRequest upang mailapat nang tama ang content type. Ang Logging ay inirerekomenda na i-install bilang huli upang ma-log ang final version ng request pagkatapos ng lahat ng pagbabago. Mag-eksperimento sa pagkakasunod-sunod kung ang plugin ay kumikilos nang hindi inaasahan.

Kawalan ng pag-handle ng exception sa suspend functions. Ang Ktor ay nagtatapon ng IOException sa network error at ClientRequestException sa HTTP status 4xx. Ang try-catch block ay mandatory para sa bawat tawag ng get(), post() at iba pang method. Gamitin ang HttpResponseValidator sa HttpClient block para sa global error handling nang hindi inuulit ang try-catch sa bawat method.