Ktor — khái niệm chính, thư viện client và Kotlin Multiplatform

Ktor là gì?

Ktor là một framework để tạo HTTP client và máy chủ bằng Kotlin, được phát triển bởi JetBrains. Không giống như các thư viện truyền thống, Ktor được thiết kế ngay từ đầu cho phát triển đa nền tảng và hoạt động trên tất cả các nền tảng được Kotlin hỗ trợ.

Ktor sử dụng cách tiếp cận middleware, lấy cảm hứng từ kiến trúc của Kodein và Express.js. Mỗi yêu cầu đi qua một pipeline các hàm handler có thể sửa đổi yêu cầu và phản hồi. Điều này mang lại sự linh hoạt không có trong các thư viện có kiến trúc cứng nhắc dựa trên chú thích.

Phiên bản hiện tại Ktor 3.0 bao gồm hỗ trợ cho Kotlin 2.0, trình biên dịch K2 và engine CIO (Coroutine I/O) mới với hiệu suất được cải thiện. Thư viện được phân phối theo giấy phép Apache 2.0 và có sẵn cho mục đích thương mại mà không có hạn chế.

Phía client của Ktor được xây dựng hoàn toàn trên coroutines Kotlin, cung cấp khả năng thực thi yêu cầu bất đồng bộ hiệu quả mà không chặn luồng. Phía máy chủ cho phép tạo máy chủ HTTP với định tuyến, xử lý yêu cầu và kết nối WebSocket.

Ktor sử dụng kiến trúc plugin: tất cả các tính năng bổ sung — logging, serialization, xác thực — được kết nối thông qua plugin. Điều này làm cho thư viện trở nên mô-đun và cho phép chỉ kết nối các thành phần cần thiết, giảm kích thước ứng dụng cuối cùng.

Nhờ API thống nhất trên tất cả các nền tảng, nhà phát triển không cần học các HTTP client khác nhau cho iOS và Android. Trong dự án đa nền tảng, mã lớp mạng được chia sẻ hoàn toàn và triển khai dành riêng cho nền tảng được ẩn sau engine HttpClient. Điều này giảm thời gian phát triển và giảm số lượng lỗi liên quan đến sự khác biệt giữa các nền tảng.

Tính năng chính của Ktor

Ktor cung cấp một bộ tính năng khiến nó trở thành lựa chọn hấp dẫn cho các dự án Kotlin hiện đại, đặc biệt là các dự án đa nền tảng.

Hỗ trợ đa nền tảng

Ktor hoạt động trên JVM, Android, iOS, macOS, Windows, Linux, JavaScript và Wasm. Cùng một mã HTTP client chạy trên tất cả các nền tảng mà không cần thay đổi. Đây là lợi thế chính so với các thư viện phụ thuộc vào OkHttp hoặc URLSession.

Bất đồng bộ với coroutines

Coroutines trong Kotlin cung cấp khả năng bất đồng bộ tự nhiên không cần callback. Mỗi yêu cầu là một hàm suspend có thể được gọi từ bất kỳ coroutine nào. Ktor hỗ trợ streaming phản hồi qua Flow, thuận tiện cho các kết nối dài và WebSocket.

Kiến trúc plugin

Plugin Ktor được kết nối thông qua khối install và cấu hình riêng biệt. Các plugin chính: ContentNegotiation cho serialization, Logging cho ghi log, Auth cho xác thực và WebSockets cho giao tiếp hai chiều. Mỗi plugin có thể được bật hoặc tắt độc lập.

Xử lý lỗi và timeout

Xử lý lỗi trong Ktor dựa trên ngoại lệ. Lớp ClientRequestException được ném cho mã 4xx, ServerResponseException cho 5xx và IOException cho lỗi mạng. Timeout được cấu hình thông qua plugin HttpTimeout, đặt thời gian chờ cho kết nối, đọc và ghi. Để thử lại, plugin Retry được sử dụng với cài đặt số lần thử và độ trễ.

Ktor hoạt động như thế nào?

Ktor sử dụng kiến trúc pipeline, nơi mỗi yêu cầu đi qua một chuỗi handler. Client tạo cấu hình HttpClient với các plugin đã cài đặt và mỗi lần gọi get hoặc post đi qua các plugin theo thứ tự kết nối của chúng.

Kiến trúc HttpClient

Đối tượng HttpClient được tạo với engine dành riêng cho nền tảng: CIO cho JVM và Android, Darwin cho iOS và macOS, OkHttp cho tương thích Android, Js cho trình duyệt. Engine có thể được chọn rõ ràng hoặc để tự động chọn. Mỗi yêu cầu trả về HttpResponse chứa nội dung phản hồi, header và trạng thái.

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

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

Cài đặt và cấu hình Ktor

Cài đặt Ktor được thực hiện qua Gradle hoặc Maven. Đối với các dự án đa nền tảng, các phụ thuộc được chỉ định trong sourceSets cho mỗi mục tiêu. Ktor được phân phối qua Maven Central.

Kết nối qua Gradle

Trong build.gradle.kts, thêm phụ thuộc ktor-client-core cho mã chung và engine cho nền tảng cụ thể. Phiên bản Ktor được đặt thông qua biến trong gradle.properties. Ktor 3.x yêu cầu Kotlin 2.0+ và hỗ trợ trình biên dịch 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")
}

Cấu hình cho iOS

Đối với iOS, engine Darwin được sử dụng, bao bọc URLSession gốc. Trong Kotlin Multiplatform, điều này mang lại hiệu suất tối đa và tích hợp với cơ chế lưu cache hệ thống iOS. Engine được thêm như một phụ thuộc riêng biệt trong sourceSet iOS.

Một tính năng quan trọng của Ktor là hỗ trợ các định dạng serialization khác nhau thông qua ContentNegotiation. Ngoài JSON, plugin hỗ trợ Protobuf, CBOR, XML và các định dạng tùy chỉnh. Để serialization, các thư viện kotlinx.serialization hoặc Jackson được sử dụng và nhà phát triển có thể chuyển đổi giữa chúng mà không cần thay đổi mã yêu cầu.

Ví dụ sử dụng Ktor

Các ví dụ dưới đây minh họa các kịch bản điển hình khi làm việc với Ktor client: yêu cầu GET cơ bản, gửi dữ liệu và làm việc với mã đa nền tảng.

Yêu cầu GET với deserialization JSON

Một yêu cầu GET đơn giản với deserialization tự động phản hồi vào data class. Ktor sử dụng plugin ContentNegotiation với kotlinx.serialization để chuyển đổi JSON thành đối tượng. Mã nguồn ngắn gọn và an toàn về kiểu.

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

Yêu cầu POST với nội dung JSON

Yêu cầu POST trong Ktor gửi data class dưới dạng nội dung JSON qua phương thức post với contentType và setBody. Plugin ContentNegotiation tự động serializes đối tượng thành chuỗi JSON. Phản hồi có thể được xử lý đồng bộ hoặc bất đồng bộ.

suspend fun createPost(): Post {
    val newPost = Post(
        id = 0,
        title = "Bài viết mới",
        body = "Nội dung bài viết"
    )
    val response = client.post("https://jsonplaceholder.typicode.com/posts") {
        contentType(ContentType.Application.Json)
        setBody(newPost)
    }
    return response.body()
}

Tải tệp lên qua Multipart

Phương thức submitFormWithBinaryData trong Ktor cho phép gửi tệp và biểu mẫu ở định dạng multipart. Ktor tự động chia dữ liệu thành các phần và thêm header. Để theo dõi tiến trình, onUpload được sử dụng, nhận byte dữ liệu đã gửi.

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 hay Retrofit: nên chọn gì?

Lựa chọn giữa Ktor và Retrofit phụ thuộc vào kiến trúc dự án và yêu cầu đa nền tảng. Retrofit vẫn là tiêu chuẩn cho các dự án chỉ Android, trong khi Ktor là lựa chọn tốt nhất cho Kotlin Multiplatform.

Ktor cũng cung cấp hỗ trợ tích hợp cho WebSocket và SSE (Server-Sent Events), làm cho nó thuận tiện cho các ứng dụng thời gian thực. Retrofit không hỗ trợ WebSocket trực tiếp — cần thư viện OkHttp WebSocket riêng. Ktor cũng dễ cấu hình hơn cho các môi trường khác nhau nhờ hệ thống plugin, nơi mỗi plugin chịu trách nhiệm cho một chức năng.

Xác thực trong Ktor

Plugin Auth trong Ktor hỗ trợ xác thực cơ bản, token Bearer, Digest và OAuth2. Cấu hình xác thực được thực hiện khai báo: nhà phát triển chỉ định nhà cung cấp, nguồn token và phạm vi. Ktor tự động thêm header xác thực vào yêu cầu và có thể làm mới token khi hết hạn.

Nếu dự án sử dụng Kotlin Multiplatform với mã chia sẻ trên iOS và Android, Ktor là lựa chọn duy nhất hoạt động trên cả hai nền tảng mà không cần lớp bổ sung. Retrofit bị ràng buộc chặt chẽ với OkHttp và JVM, khiến nó không phù hợp cho iOS.

Đối với các dự án chỉ Android, Retrofit cung cấp API trưởng thành hơn, số lượng converter và interceptor OkHttp lớn hơn. Ktor cũng hoạt động trong kịch bản này, nhưng hệ sinh thái plugin của nó ít mở rộng hơn. Cả hai thư viện đều hỗ trợ coroutines và cung cấp hiệu suất tương đương.