Xây dựng REST API với Ktor và Kotlin: Bất đồng bộ từ nền tảng với Coroutines

Programming tutorial - IT technology blog
Programming tutorial - IT technology blog

Khởi động nhanh: Ktor chạy trong 5 phút

Nếu bạn đã từng vật lộn với auto-configuration của Spring Boot — hoặc chỉ nhìn IDE xoay vòng 15 giây trong khi application context đang tải — thì Ktor sẽ là luồng gió mới mẻ. Nó không làm gì phía sau lưng bạn.

Truy cập start.ktor.io và tạo project mới. Chọn các plugin sau:

  • Routing
  • Content Negotiation
  • kotlinx.serialization
  • Netty (làm engine)

File build.gradle.kts của bạn sẽ trông như thế này:

plugins {
    kotlin("jvm") version "1.9.22"
    kotlin("plugin.serialization") version "1.9.22"
    id("io.ktor.plugin") version "2.3.9"
    application
}

dependencies {
    implementation("io.ktor:ktor-server-core-jvm:2.3.9")
    implementation("io.ktor:ktor-server-netty-jvm:2.3.9")
    implementation("io.ktor:ktor-server-content-negotiation-jvm:2.3.9")
    implementation("io.ktor:ktor-serialization-kotlinx-json-jvm:2.3.9")
    implementation("ch.qos.logback:logback-classic:1.4.14")
    testImplementation("io.ktor:ktor-server-test-host-jvm:2.3.9")
    testImplementation("org.jetbrains.kotlin:kotlin-test-junit:1.9.22")
}

application {
    mainClass.set("com.example.ApplicationKt")
}

Bây giờ tạo file src/main/kotlin/com/example/Application.kt:

package com.example

import io.ktor.server.application.*
import io.ktor.server.engine.*
import io.ktor.server.netty.*
import io.ktor.server.plugins.contentnegotiation.*
import io.ktor.serialization.kotlinx.json.*
import io.ktor.server.routing.*
import io.ktor.server.response.*
import kotlinx.serialization.Serializable

@Serializable
data class ServerInfo(val name: String, val version: String)

fun main() {
    embeddedServer(Netty, port = 8080, module = Application::module).start(wait = true)
}

fun Application.module() {
    install(ContentNegotiation) {
        json()
    }
    routing {
        get("/") {
            call.respond(ServerInfo("Ktor API của tôi", "1.0.0"))
        }
    }
}

Chạy với ./gradlew run và truy cập http://localhost:8080. Bạn sẽ nhận được:

{"name":"Ktor API của tôi","version":"1.0.0"}

Không có XML. Không có annotation quét toàn bộ classpath. Không có magic. Chỉ là code bạn có thể đọc từ đầu đến cuối.

Bên trong Ktor: Coroutines, Routing và Content Negotiation

Coroutines thực sự xử lý concurrency như thế nào

Các framework dựa trên servlet truyền thống cấp phát một thread cho mỗi request. Dưới tải nặng, thread tích lũy, bộ nhớ tăng vọt và độ trễ leo thang. Spring WebFlux giải quyết vấn đề này bằng reactive streams, nhưng mô hình lập trình — các operator như flatMap, switchIfEmpty, quản lý backpressure — mang lại một đường cong học tập dốc làm chậm hầu hết các nhóm.

Ktor đi theo một con đường khác. Mọi handler đều là hàm suspend. Khi nó chờ một truy vấn database hoặc một lời gọi HTTP, coroutine tạm dừng và thread bên dưới được giải phóng cho công việc khác. Khi kết quả trả về, coroutine tiếp tục chính xác từ nơi nó dừng lại. Code đọc như logic tuần tự — không có callback chains, không có reactive operators để debug.

routing {
    get("/users/{id}") {
        val id = call.parameters["id"]?.toIntOrNull()
            ?: return@get call.respond(HttpStatusCode.BadRequest, "ID không hợp lệ")

        // Lệnh này tạm dừng coroutine mà không chặn bất kỳ thread nào
        val user = userRepository.findById(id)
            ?: return@get call.respond(HttpStatusCode.NotFound, "Không tìm thấy người dùng")

        call.respond(user)
    }
}

Xử lý hàng nghìn request đồng thời mà không cần tạo ra hàng nghìn thread là một trong những thứ nghe có vẻ đơn giản cho đến khi bạn thực sự thử trên JVM. Ktor biến concurrency dựa trên coroutine thành mặc định ngay từ ngày đầu tiên — bạn không cần bật nó lên, không cần cấu hình riêng. Đó đơn giản là cách framework hoạt động.

Content Negotiation trong thực tế

Plugin ContentNegotiation đọc header Accept trên các request đến và Content-Type trên response, sau đó chọn serializer phù hợp. Cấu hình một lần — mọi lời gọi call.respond() sẽ tự động xử lý chuyển đổi từ điểm đó.

install(ContentNegotiation) {
    json(Json {
        prettyPrint = false
        ignoreUnknownKeys = true
        isLenient = true
    })
}

Phân tích cú pháp POST body cũng gọn gàng không kém:

@Serializable
data class CreateUserRequest(val username: String, val email: String)

@Serializable
data class UserResponse(val id: Int, val username: String, val email: String)

routing {
    post("/users") {
        val request = call.receive<CreateUserRequest>()
        val created = userRepository.create(request.username, request.email)
        call.respond(HttpStatusCode.Created, UserResponse(created.id, created.username, created.email))
    }
}

Annotation @Serializable từ kotlinx.serialization tạo code serialization tại compile time — không có runtime reflection, không có Jackson magic, khởi động nhanh hơn.

Cấu trúc routes cho ứng dụng thực tế

Đặt tất cả vào một routing block là ổn với demo. Thêm mười endpoint và nó nhanh chóng trở nên khó điều hướng. DSL routing của Ktor được xây dựng xung quanh extension function trên Route, vì vậy mỗi tính năng tự độc lập trong file riêng của nó:

fun Application.configureRouting() {
    routing {
        route("/api/v1") {
            userRoutes()
            articleRoutes()
        }
    }
}

fun Route.userRoutes() {
    route("/users") {
        get { /* liệt kê người dùng */ }
        post { /* tạo người dùng */ }
        route("/{id}") {
            get { /* lấy người dùng */ }
            put { /* cập nhật người dùng */ }
            delete { /* xóa người dùng */ }
        }
    }
}

Mỗi tính năng nằm trong file và extension function riêng của nó. Không có registry controller trung tâm nào cần cập nhật khi bạn thêm một module mới.

Sử dụng nâng cao: Plugins, Auth và xử lý lỗi

Phản hồi lỗi nhất quán với StatusPages

Theo mặc định, một exception không được bắt sẽ trả cho caller một mã 500 trần trụi — không có thông báo lỗi, không có JSON body. Plugin StatusPages khắc phục điều đó bằng cách ánh xạ các loại exception thành response có cấu trúc trên toàn ứng dụng:

// Thêm dependency: ktor-server-status-pages-jvm
install(StatusPages) {
    exception<IllegalArgumentException> { call, cause ->
        call.respond(
            HttpStatusCode.BadRequest,
            mapOf("error" to (cause.message ?: "Yêu cầu không hợp lệ"))
        )
    }
    exception<NotFoundException> { call, cause ->
        call.respond(
            HttpStatusCode.NotFound,
            mapOf("error" to (cause.message ?: "Không tìm thấy tài nguyên"))
        )
    }
}

Xác thực JWT

Thêm các dependency auth vào build file của bạn:

implementation("io.ktor:ktor-server-auth-jvm:2.3.9")
implementation("io.ktor:ktor-server-auth-jwt-jvm:2.3.9")
implementation("com.auth0:java-jwt:4.4.0")

Sau đó cấu hình nó trong hàm module() của bạn:

install(Authentication) {
    jwt("auth-jwt") {
        realm = "my-api"
        verifier(
            JWT.require(Algorithm.HMAC256(jwtSecret))
                .withAudience(jwtAudience)
                .withIssuer(jwtIssuer)
                .build()
        )
        validate { credential ->
            if (credential.payload.audience.contains(jwtAudience))
                JWTPrincipal(credential.payload)
            else null
        }
    }
}

// Bọc các route được bảo vệ:
authenticate("auth-jwt") {
    get("/me") {
        val principal = call.principal<JWTPrincipal>()
        call.respond(mapOf("userId" to principal?.payload?.subject))
    }
}

Truy cập database thân thiện với coroutine

Driver JDBC bị blocking theo thiết kế. Chạy chúng trực tiếp trong một coroutine Ktor sẽ chặn thread pool dùng chung. Giải pháp là withContext(Dispatchers.IO), di chuyển công việc blocking sang một IO thread pool riêng mà không chặn coroutine dispatcher Ktor sử dụng cho routing:

suspend fun findUserById(id: Int): User? = withContext(Dispatchers.IO) {
    // Lời gọi JDBC blocking chạy ở đây trên IO dispatcher
    transaction {
        Users.select { Users.id eq id }
            .map { User(it[Users.id].value, it[Users.username]) }
            .singleOrNull()
    }
}

// Code của người gọi trông gọn gàng:
routing {
    get("/users/{id}") {
        val id = call.parameters["id"]!!.toInt()
        val user = findUserById(id) ?: return@get call.respond(HttpStatusCode.NotFound)
        call.respond(user)
    }
}

Mẹo thực tế trước khi triển khai

Kiểm thử mà không cần khởi động server thực

Hàm testApplication của Ktor chạy toàn bộ ứng dụng của bạn trong bộ nhớ — không có port, không có socket mở, thiết lập test dưới 100ms:

class ApplicationTest {
    @Test
    fun testRoot() = testApplication {
        application { module() }
        val response = client.get("/")
        assertEquals(HttpStatusCode.OK, response.status)
    }

    @Test
    fun testCreateUser() = testApplication {
        application { module() }
        val response = client.post("/users") {
            contentType(ContentType.Application.Json)
            setBody("""{"username":"alice","email":"[email protected]"}""")
        }
        assertEquals(HttpStatusCode.Created, response.status)
    }
}

Quản lý cấu hình với HOCON

Giữ các secret ra khỏi code. Ktor hỗ trợ file cấu hình HOCON nguyên bản thông qua src/main/resources/application.conf:

ktor {
    deployment {
        port = 8080
        port = ${?PORT}
    }
}

jwt {
    secret = ${?JWT_SECRET}
    issuer = "https://api.example.com"
    audience = "api-users"
}

Truy cập nó bên trong module của bạn:

val jwtSecret = environment.config.property("jwt.secret").getString()

Triển khai lên production

Xây dựng một fat JAR tự chứa và triển khai nó bất kỳ đâu Java chạy được:

# Xây dựng
./gradlew buildFatJar

# Chạy trực tiếp
java -jar build/libs/my-api-all.jar

# Hoặc container hóa nó
docker build -t my-ktor-api .
docker run -p 8080:8080 -e JWT_SECRET=supersecret my-ktor-api

File JAR kết quả có kích thước từ 15–25 MB. Khởi động lạnh trên một VPS vừa phải khoảng 1–2 giây — so sánh với 5–12 giây cho một ứng dụng Spring Boot thông thường trên cùng phần cứng.

Ktor không phải là sự thay thế cho Spring. Đối với các codebase doanh nghiệp lớn với nhiều năm đầu tư vào hệ sinh thái đó, chi phí chuyển đổi không hề hợp lý. Nhưng đối với một service mới hoặc microservice — đặc biệt nếu bạn muốn hiểu chính xác điều gì xảy ra ở từng bước — Ktor với Kotlin coroutines là một lựa chọn thực sự sạch sẽ. Code trông tuần tự, xử lý tải thực tế, và kiểm thử chỉ trong mili giây. Sự kết hợp đó hiếm hơn trên JVM so với mức lẽ ra phải có.

Share: