KtorとKotlinでREST APIを構築する:コルーチンで始める非同期処理の基礎

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

クイックスタート:5分でKtorを動かす

Spring Bootの自動設定に手こずったことがある方、あるいはアプリケーションコンテキストの読み込み中にIDEが15秒間クルクルするのを見守ったことがある方には、Ktorは新鮮な空気のように感じられるでしょう。Ktorは裏側で余計なことをしません。

start.ktor.ioにアクセスして新しいプロジェクトを生成しましょう。以下のプラグインを選択してください:

  • Routing
  • Content Negotiation
  • kotlinx.serialization
  • Netty(エンジンとして)

build.gradle.ktsは次のようになります:

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

次に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", "1.0.0"))
        }
    }
}

./gradlew runで実行してhttp://localhost:8080にアクセスすると、次のレスポンスが返ってきます:

{"name":"私のKtor API","version":"1.0.0"}

XMLもなし。クラスパス全体のアノテーションスキャンもなし。魔法もなし。先頭から末尾まで読める、シンプルなコードだけです。

Ktorの内部:コルーチン、ルーティング、Content Negotiation

コルーチンが実際に並行処理をどう扱うか

従来のサーブレットベースのフレームワークは、リクエストごとに1スレッドを割り当てます。高負荷になるとスレッドが積み上がり、メモリが急増し、レイテンシが上昇します。Spring WebFluxはリアクティブストリームでこの問題に取り組みましたが、そのプログラミングモデル — flatMap、switchIfEmpty、バックプレッシャー管理などのオペレーター — は急峻な学習曲線を持ち、多くのチームの開発速度を低下させます。

Ktorは別のアプローチを取ります。すべてのハンドラーはsuspend関数です。データベースクエリやHTTPコールを待つ際、コルーチンはサスペンドし、背後のスレッドは他の処理に解放されます。結果が返ってくると、コルーチンは中断した箇所から正確に再開します。コードは順次処理のロジックとして読めます — コールバックチェーンもなく、デバッグすべきリアクティブオペレーターもありません。

routing {
    get("/users/{id}") {
        val id = call.parameters["id"]?.toIntOrNull()
            ?: return@get call.respond(HttpStatusCode.BadRequest, "IDが無効です")

        // スレッドをブロックせずにコルーチンをサスペンドする
        val user = userRepository.findById(id)
            ?: return@get call.respond(HttpStatusCode.NotFound, "ユーザーが見つかりません")

        call.respond(user)
    }
}

何千ものスレッドを立ち上げることなく何千もの同時リクエストを処理するのは、JVMで実際に試してみるまでは簡単そうに聞こえるものの一つです。Ktorはコルーチンベースの並行処理を初日からデフォルトにしています — オプトインする必要もなく、別途配線する必要もありません。それがフレームワークの動作方法です。

Content Negotiationの実際

ContentNegotiationプラグインは受信リクエストのAcceptヘッダーとレスポンスのContent-Typeを読み取り、適切なシリアライザーを選択します。一度設定すれば、以降のcall.respond()の呼び出しは自動的に変換を処理します。

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

POSTボディの解析も同様にシンプルです:

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

kotlinx.serializationの@Serializableアノテーションはコンパイル時にシリアライゼーションコードを生成します — ランタイムリフレクションなし、Jacksonマジックなし、高速な起動。

実際のアプリケーション向けルート構造

デモなら全てを1つのroutingブロックに入れても問題ありません。しかしエンドポイントが10個になると、すぐに把握しにくくなります。KtorのルーティングDSLはRouteの拡張関数を中心に構築されているため、各機能を独自のファイルに自己完結させておけます:

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

fun Route.userRoutes() {
    route("/users") {
        get { /* ユーザー一覧 */ }
        post { /* ユーザー作成 */ }
        route("/{id}") {
            get { /* ユーザー取得 */ }
            put { /* ユーザー更新 */ }
            delete { /* ユーザー削除 */ }
        }
    }
}

各機能は独自のファイルと拡張関数に収まります。新しいモジュールを追加する際に更新すべき中央コントローラーレジストリはありません。

高度な使い方:プラグイン、認証、エラーハンドリング

StatusPagesで一貫したエラーレスポンスを実現する

デフォルトでは、キャッチされない例外は呼び出し元にむき出しの500を返します — エラーメッセージなし、JSONボディなし。StatusPagesプラグインはアプリケーション全体で例外の種類を構造化されたレスポンスにマッピングすることでこれを解決します:

// 依存関係を追加:ktor-server-status-pages-jvm
install(StatusPages) {
    exception<IllegalArgumentException> { call, cause ->
        call.respond(
            HttpStatusCode.BadRequest,
            mapOf("error" to (cause.message ?: "不正なリクエスト"))
        )
    }
    exception<NotFoundException> { call, cause ->
        call.respond(
            HttpStatusCode.NotFound,
            mapOf("error" to (cause.message ?: "リソースが見つかりません"))
        )
    }
}

JWT認証

ビルドファイルに認証の依存関係を追加してください:

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

次にmodule()関数で設定します:

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

// 保護されたルートをラップする:
authenticate("auth-jwt") {
    get("/me") {
        val principal = call.principal<JWTPrincipal>()
        call.respond(mapOf("userId" to principal?.payload?.subject))
    }
}

コルーチンに適したデータベースアクセス

JDBCドライバーは設計上ブロッキングです。Ktorのコルーチン内で直接実行すると、共有スレッドプールがブロックされます。解決策はwithContext(Dispatchers.IO)で、これによりブロッキング処理をKtorがルーティングに使用するコルーチンディスパッチャーをブロックせず、専用のIOスレッドプールに移行できます:

suspend fun findUserById(id: Int): User? = withContext(Dispatchers.IO) {
    // ブロッキングJDBC呼び出しはここでIOディスパッチャー上で実行される
    transaction {
        Users.select { Users.id eq id }
            .map { User(it[Users.id].value, it[Users.username]) }
            .singleOrNull()
    }
}

// 呼び出し元のコードはシンプルに保たれる:
routing {
    get("/users/{id}") {
        val id = call.parameters["id"]!!.toInt()
        val user = findUserById(id) ?: return@get call.respond(HttpStatusCode.NotFound)
        call.respond(user)
    }
}

リリース前に押さえておくべき実践的なヒント

実サーバーを起動せずにテストする

KtorのtestApplicationはフルアプリケーションをインメモリで実行します — ポートなし、オープンソケットなし、テストセットアップは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)
    }
}

HOCONで設定を管理する

シークレット情報をコードから切り離しましょう。Ktorはsrc/main/resources/application.confを通じてHOCONコンフィグファイルをネイティブにサポートしています:

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

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

モジュール内でアクセスするには:

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

本番環境へのデプロイ

自己完結したfat JARをビルドして、Javaが動く場所ならどこでも実行できます:

# ビルド
./gradlew buildFatJar

# 直接実行
java -jar build/libs/my-api-all.jar

# またはコンテナ化する
docker build -t my-ktor-api .
docker run -p 8080:8080 -e JWT_SECRET=supersecret my-ktor-api

生成されるJARは15〜25MBの間です。標準的なVPSでのコールドスタートは約1〜2秒 — 同じハードウェアでの典型的なSpring Bootアプリケーションの5〜12秒と比較してみてください。

KtorはSpringの代替品ではありません。そのエコシステムに長年投資してきた大規模なエンタープライズコードベースには、移行コストは見合いません。しかし新しいサービスやマイクロサービスに対しては — 特に各ステップで何が起きているかを正確に理解したい場合 — KotlinコルーチンとKtorは真にクリーンな選択肢です。コードは順次処理のように読め、実際の負荷を処理し、ミリ秒単位でテストできます。JVMでこの組み合わせが実現できることは、本来あるべきよりも稀なことです。

Share: