Ktor: apa itu, fitur klien HTTP asinkron

Apa itu Ktor?

Ktor adalah framework untuk membangun aplikasi asinkron sisi server dan klien di Kotlin, dibuat oleh JetBrains. Ktor Client — bagian klien dari framework, yang menyediakan klien HTTP dengan dukungan penuh untuk coroutine Kotlin, multi-platform (JVM, Native, JS) dan arsitektur modular berbasis plugin.

Ktor muncul pada tahun 2018 sebagai alternatif untuk Retrofit dan OkHttp untuk proyek Kotlin-first. Tidak seperti Retrofit yang menggunakan pendekatan Java dengan anotasi, Ktor Client menggunakan Kotlin DSL untuk konfigurasi permintaan — tanpa anotasi dan refleksi. Ini membuat kode lebih mudah dibaca dan type-safe bagi pengembang Kotlin.

Menurut survei Kotlin Multiplatform 2024, Ktor Client digunakan di 35% proyek Kotlin Multiplatform Mobile (KMM), menjadikannya klien HTTP terpopuler kedua setelah OkHttp di komunitas Kotlin. Ktor lebih disukai dalam proyek di mana multi-platform dan integrasi asli dengan ekosistem Kotlin penting.

Bagaimana Ktor Client Bekerja

Arsitektur Ktor Client didasarkan pada pipeline plugin. Setiap permintaan melewati urutan plugin yang terinstal, yang dapat memodifikasi permintaan, respons, atau melakukan tindakan sampingan — logging, kompresi, serialisasi, autentikasi.

Saat membuat klien HTTP melalui blok HttpClient { } DSL, Anda menentukan engine (OkHttp, Android, CIO, Darwin) dan menginstal plugin. Setiap engine mengimplementasikan pengiriman permintaan tingkat rendah untuk platform tertentu: di Android menggunakan engine OkHttp, di iOS — Darwin (URLSession), di Desktop — CIO (Coroutine-based I/O). HttpClient secara otomatis memilih engine optimal untuk platform saat ini.

Permintaan di Ktor Client dieksekusi melalui fungsi suspend, yang berarti integrasi penuh dengan coroutine. Tidak ada Callback, RxJava, atau LiveData — hanya kode sekuensial dengan suspend yang bekerja asinkron tanpa memblokir thread.

Pipeline pemrosesan permintaan

Pipeline Ktor terdiri dari fase: pertama permintaan melewati plugin yang terinstal (misalnya, ContentNegotiation untuk JSON, Logging untuk log), kemudian engine mengeksekusi permintaan HTTP, dan respons kembali melewati plugin untuk deserialisasi. Setiap plugin adalah fungsi suspend yang dieksekusi dalam coroutine pipeline.

Keuntungan penting dari pipeline Ktor adalah kemungkinan pemrosesan bersyarat. Plugin dapat memeriksa URL atau header permintaan dan melewati pemrosesan jika kondisi tidak terpenuhi. Misalnya, ContentEncoding dengan gzip hanya diterapkan pada respons yang mengandung header Content-Encoding: gzip, dan Auth hanya berfungsi untuk endpoint yang dilindungi tanpa memengaruhi API publik.

Pendekatan pipeline ini memungkinkan kombinasi plugin yang fleksibel: Anda dapat menginstal ContentNegotiation dengan JSON, menambahkan Auth dengan token Bearer, mengaktifkan kompresi ContentEncoding dan HttpTimeout — dan semuanya akan bekerja bersama dalam urutan yang benar. Urutan instalasi plugin penting: yang pertama diinstal akan memproses permintaan lebih awal dari yang lain.

Plugin Ktor Client

Plugin — sistem ekstensi modular Ktor, yang menggantikan anotasi Retrofit dan interceptor OkHttp. Setiap plugin menyelesaikan tugas tertentu dan diinstal melalui fungsi install() di blok HttpClient. Ktor menyediakan plugin bawaan, dan juga memungkinkan pembuatan plugin kustom.

Plugin kustom

Untuk tugas spesifik, dibuat plugin kustom melalui createClientPlugin. Plugin dapat mengintersep permintaan (onRequest), respons (onResponse), atau menangani kesalahan (onError). Ini sepenuhnya menggantikan Interceptor dari OkHttp, tetapi dengan API Kotlin yang diketik dan dukungan fungsi suspend.

Plugin kustom berguna untuk menambahkan metrik, logika pengulangan otomatis, pelacakan permintaan, atau pengujian A/B endpoint. Tidak seperti interceptor OkHttp, plugin Ktor ditulis dalam Kotlin dan bekerja dalam konteks coroutine, yang menyederhanakan penanganan kesalahan dan batas waktu.

Untuk debugging permintaan, digunakan plugin Logging dengan level ALL, HEADERS, atau BODY. Logging menampilkan metode, URL, status, header, dan body permintaan serta respons. Tidak seperti HttpLoggingInterceptor dari OkHttp, Ktor Logging bekerja asinkron dan dapat dikonfigurasi untuk memfilter berdasarkan level log (ERROR, WARN, INFO, DEBUG) tanpa menghentikan aplikasi untuk mengubah konfigurasi.

Contoh Kode Ktor Client di Kotlin

Mari kita lihat permintaan GET dasar melalui Ktor Client. HttpClient dibuat dengan plugin ContentNegotiation terinstal untuk JSON. Permintaan dieksekusi melalui fungsi suspend get(), hasilnya secara otomatis dideserialisasi menjadi 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()
}

Untuk permintaan POST dengan body digunakan fungsi post() dengan contentType() dan body(). Ktor secara otomatis menserialisasi objek ke JSON melalui ContentNegotiation yang terinstal. Gaya DSL membuat kode sekuensial dan mudah dibaca.

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

Konfigurasi batas waktu dan header

HttpTimeout dan DefaultRequest — dua plugin kunci untuk konfigurasi. HttpTimeout menetapkan batas waktu, dan DefaultRequest menentukan header dan parameter URL untuk semua permintaan, menghilangkan duplikasi kode di setiap panggilan.

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

Dukungan Multi-platform Ktor

Multi-platform — keunggulan utama Ktor dibandingkan OkHttp dan Retrofit. Ktor Client bekerja di JVM (Android, Server), Native (iOS, macOS, Windows, Linux) dan JS (Browser). Kode klien HTTP yang sama berjalan di semua platform tanpa perubahan, yang sangat berharga untuk proyek Kotlin Multiplatform.

Untuk setiap platform, Ktor menggunakan engine-nya sendiri. Di Android, secara default diterapkan engine OkHttp, yang memberikan kompatibilitas penuh dengan ekosistem OkHttp. Di iOS menggunakan DarwinEngine berbasis URLSession. Untuk Server — CIOEngine (Coroutine I/O). Engine dapat ditentukan secara eksplisit: HttpClient(OkHttp) { } atau HttpClient(Darwin) { }.

Saat memilih engine, pertimbangkan kemampuannya: engine OkHttp mendukung HTTP/2 dan kumpulan koneksi, DarwinEngine — integrasi asli dengan jaringan iOS dan sesi latar belakang URLSession, CIOEngine — implementasi coroutine murni tanpa dependensi eksternal. Untuk target Web digunakan JsEngine atau BrowserEngine yang bekerja melalui fetch API.

Berkat API yang seragam di semua platform, kode untuk memuat data terlihat sama di Android, iOS, dan Desktop. Ini mengurangi duplikasi kode sebesar 60–80% di proyek KMM dibandingkan dengan implementasi terpisah di Retrofit (Android) dan URLSession (iOS). Plugin juga bekerja di semua platform tanpa perubahan.

Kesalahan Umum saat Bekerja dengan Ktor

Mengabaikan penutupan HttpClient — kesalahan umum di Ktor. HttpClient mengimplementasikan Closeable dan harus ditutup saat aplikasi berakhir melalui client.close(). Di Android, ini dilakukan di onDestroy() Activity atau ViewModel.onCleared(). Klien yang tidak ditutup menyebabkan kebocoran coroutine dan thread engine.

Urutan plugin yang salah dapat merusak pemrosesan permintaan. Misalnya, ContentNegotiation harus diinstal sebelum DefaultRequest agar tipe konten diterapkan dengan benar. Logging disarankan diinstal terakhir untuk mencatat versi final permintaan setelah semua modifikasi. Eksperimen dengan urutan jika plugin berperilaku tidak terduga.

Tidak adanya penanganan pengecualian dalam fungsi suspend. Ktor melempar IOException pada kesalahan jaringan dan ClientRequestException pada status HTTP 4xx. Blok try-catch wajib untuk setiap panggilan get(), post(), dan metode lainnya. Gunakan HttpResponseValidator di blok HttpClient untuk penanganan kesalahan global tanpa duplikasi try-catch di setiap metode.