Ktor — konsep kunci, pustaka klien dan Kotlin Multiplatform

Apa itu Ktor?

Ktor — adalah kerangka kerja untuk membuat klien HTTP dan server dalam bahasa Kotlin, dikembangkan oleh perusahaan JetBrains. Tidak seperti pustaka tradisional, Ktor sejak awal dirancang untuk pengembangan multiplatform dan berfungsi di semua platform yang didukung oleh Kotlin.

Ktor menggunakan pendekatan penangan perantara, terinspirasi oleh arsitektur Kodein dan Express.js. Setiap permintaan melewati pipeline fungsi penangan yang dapat memodifikasi permintaan dan tanggapan. Ini memberikan fleksibilitas yang tidak tersedia di pustaka dengan arsitektur kaku berbasis anotasi.

Versi saat ini Ktor 3.0 mencakup dukungan untuk Kotlin 2.0, kompiler K2, dan mesin CIO (Coroutine I/O) baru dengan kinerja yang ditingkatkan. Pustaka ini didistribusikan di bawah lisensi Apache 2.0 dan tersedia untuk penggunaan komersial tanpa batasan.

Bagian klien Ktor sepenuhnya dibangun di atas korutin Kotlin, yang memastikan eksekusi permintaan asinkron yang efisien tanpa memblokir utas. Bagian server memungkinkan pembuatan server HTTP dengan routing, pemrosesan permintaan, dan koneksi WebSocket.

Ktor menggunakan arsitektur plugin: semua fungsi tambahan — logging, serialisasi, autentikasi — dihubungkan melalui plugin. Ini membuat pustaka menjadi modular dan memungkinkan menghubungkan hanya komponen yang diperlukan, mengurangi ukuran aplikasi akhir.

Berkat API yang seragam di semua platform, pengembang tidak perlu mempelajari klien HTTP yang berbeda untuk iOS dan Android. Dalam proyek multiplatform, kode lapisan jaringan sepenuhnya bersama, dan implementasi khusus platform disembunyikan di balik mesin HttpClient. Ini mempersingkat waktu pengembangan dan mengurangi jumlah kesalahan terkait perbedaan platform.

Fitur utama Ktor

Ktor menawarkan serangkaian fitur yang menjadikannya pilihan menarik untuk proyek Kotlin modern, terutama proyek multiplatform.

Dukungan multiplatform

Ktor berjalan di JVM, Android, iOS, macOS, Windows, Linux, JavaScript, dan Wasm. Kode klien HTTP yang sama berjalan di semua platform tanpa perubahan. Ini adalah keunggulan utama dibandingkan pustaka yang terikat pada OkHttp atau URLSession.

Asinkron pada korutin

Korutin Kotlin memberikan asinkronisitas alami tanpa callback. Setiap permintaan adalah fungsi suspend yang dapat dipanggil dari korutin mana pun. Ktor mendukung streaming tanggapan melalui Flow, yang nyaman untuk koneksi panjang dan WebSocket.

Arsitektur plugin

Plugin Ktor dihubungkan melalui blok install dan dikonfigurasi secara terpisah. Plugin utama: ContentNegotiation untuk serialisasi, Logging untuk logging, Auth untuk autentikasi, dan WebSockets untuk komunikasi dua arah. Setiap plugin dapat diaktifkan atau dinonaktifkan secara independen.

Penanganan kesalahan dan batas waktu

Penanganan kesalahan di Ktor didasarkan pada pengecualian. Kelas ClientRequestException dilemparkan pada kode 4xx, ServerResponseException pada 5xx, dan IOException pada kesalahan jaringan. Batas waktu dikonfigurasi melalui plugin HttpTimeout, yang menetapkan waktu tunggu untuk koneksi, pembacaan, dan penulisan. Untuk percobaan ulang digunakan plugin Retry dengan pengaturan jumlah percobaan dan penundaan.

Bagaimana cara kerja Ktor?

Ktor menggunakan arsitektur pipeline, di mana setiap permintaan melewati rantai penangan. Klien membuat konfigurasi HttpClient dengan plugin yang terpasang, dan setiap panggilan metode get atau post melewati plugin sesuai urutan pemasangannya.

Arsitektur HttpClient

Objek HttpClient dibuat dengan mesin khusus platform: CIO untuk JVM dan Android, Darwin untuk iOS dan macOS, OkHttp untuk kompatibilitas Android, Js untuk peramban. Mesin dapat dipilih secara eksplisit atau dibiarkan dengan pemilihan otomatis. Setiap permintaan mengembalikan HttpResponse yang berisi badan tanggapan, header, dan 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()
}

Instalasi dan konfigurasi Ktor

Instalasi Ktor dilakukan melalui Gradle atau Maven. Dalam proyek multiplatform, dependensi ditentukan dalam sourceSets untuk setiap target. Ktor didistribusikan melalui Maven Central.

Menghubungkan melalui Gradle

Di build.gradle.kts tambahkan dependensi ktor-client-core untuk kode bersama dan mesin untuk platform tertentu. Versi Ktor ditetapkan melalui variabel di gradle.properties. Ktor 3.x membutuhkan Kotlin 2.0+ dan mendukung kompiler 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")
}

Konfigurasi untuk iOS

Untuk iOS digunakan mesin Darwin, yang membungkus URLSession asli. Di Kotlin Multiplatform, ini memungkinkan kinerja maksimal dan integrasi dengan mekanisme caching sistem iOS. Mesin ditambahkan sebagai dependensi terpisah di sourceSet iOS.

Fitur penting Ktor — dukungan untuk berbagai format serialisasi melalui ContentNegotiation. Selain JSON, plugin mendukung Protobuf, CBOR, XML, dan format kustom. Untuk serialisasi digunakan pustaka kotlinx.serialization atau Jackson, dan pengembang dapat beralih di antara mereka tanpa mengubah kode permintaan.

Contoh penggunaan Ktor

Contoh di bawah menunjukkan skenario umum bekerja dengan klien Ktor: permintaan GET dasar, pengiriman data, dan bekerja dengan kode multiplatform.

Permintaan GET dengan deserialisasi JSON

Permintaan GET sederhana dengan deserialisasi otomatis tanggapan ke kelas data. Ktor menggunakan plugin ContentNegotiation dengan kotlinx.serialization untuk mengonversi JSON menjadi objek. Kode ringkas dan aman tipe.

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

Permintaan POST dengan badan JSON

Permintaan POST di Ktor mengirim kelas data sebagai badan JSON melalui metode post dengan contentType dan setBody. Plugin ContentNegotiation secara otomatis menyerialisasikan objek menjadi string JSON. Tanggapan dapat diproses secara sinkron atau asinkron.

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

Unggah file melalui Multipart

Metode submitFormWithBinaryData di Ktor memungkinkan pengiriman file dan formulir dalam format multipart. Ktor secara otomatis membagi data menjadi bagian-bagian dan menambahkan header. Untuk melacak kemajuan digunakan onUpload, yang menerima byte data yang dikirim.

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 atau Retrofit: mana yang harus dipilih?

Pilihan antara Ktor dan Retrofit tergantung pada arsitektur proyek dan kebutuhan multiplatform. Retrofit tetap menjadi standar untuk proyek khusus Android, sementara Ktor adalah pilihan yang lebih baik untuk Kotlin Multiplatform.

Ktor juga menyediakan dukungan bawaan untuk WebSocket dan SSE (Server-Sent Events), yang membuatnya nyaman untuk aplikasi waktu nyata. Retrofit tidak mendukung WebSocket secara langsung — untuk ini diperlukan pustaka OkHttp WebSocket terpisah. Ktor juga lebih mudah dikonfigurasi untuk lingkungan yang berbeda berkat sistem plugin, di mana setiap plugin bertanggung jawab atas satu fungsi.

Autentikasi di Ktor

Plugin Auth di Ktor mendukung autentikasi dasar, token Bearer, Digest, dan OAuth2. Konfigurasi autentikasi dilakukan secara deklaratif: pengembang menentukan penyedia, sumber token, dan ruang lingkup. Ktor secara otomatis menambahkan header autentikasi ke permintaan dan dapat memperbarui token saat kedaluwarsa.

Jika proyek menggunakan Kotlin Multiplatform dengan kode bersama di iOS dan Android, Ktor adalah satu-satunya opsi yang berfungsi di kedua platform tanpa lapisan tambahan. Retrofit terikat erat dengan OkHttp dan JVM, yang membuatnya tidak cocok untuk iOS.

Untuk proyek khusus Android, Retrofit menyediakan API yang lebih matang, lebih banyak konverter, dan interceptor OkHttp. Ktor juga berfungsi dalam skenario ini, tetapi ekosistem pluginnya kurang luas. Kedua pustaka mendukung korutin dan memberikan kinerja yang sebanding.