Ktor — 主要概念、クライアントライブラリ、Kotlin Multiplatform

Ktorとは？

Ktorは、JetBrainsによって開発されたKotlinでHTTPクライアントとサーバーを作成するためのフレームワークです。従来のライブラリとは異なり、Ktorは当初からマルチプラットフォーム開発向けに設計されており、Kotlinがサポートするすべてのプラットフォームで動作します。

Ktorは、KodeinやExpress.jsのアーキテクチャに触発されたミドルウェアハンドラーアプローチを採用しています。各リクエストは、リクエストとレスポンスを変更できるハンドラー関数のパイプラインを通過します。これにより、アノテーションベースの堅固なアーキテクチャを持つライブラリでは実現できない柔軟性が得られます。

現在のバージョンKtor 3.0は、Kotlin 2.0、K2コンパイラ、およびパフォーマンスが向上した新しいCIO（Coroutine I/O）エンジンのサポートを含んでいます。このライブラリはApache 2.0ライセンスの下で配布されており、制限なく商用利用が可能です。

Ktorのクライアント側は完全にKotlinコルーチン上に構築されており、スレッドをブロックすることなく効率的な非同期リクエスト実行を実現します。サーバー側では、ルーティング、リクエスト処理、WebSocket接続を備えたHTTPサーバーを作成できます。

Ktorはプラグインアーキテクチャを採用しています。ロギング、シリアライゼーション、認証などのすべての追加機能はプラグインを介して接続されます。これによりライブラリがモジュール化され、必要なコンポーネントだけを接続できるため、最終的なアプリケーションのサイズが削減されます。

すべてのプラットフォームで統一されたAPIのおかげで、開発者はiOSとAndroidで異なるHTTPクライアントを学ぶ必要がありません。マルチプラットフォームプロジェクトでは、ネットワーク層のコードは完全に共有され、プラットフォーム固有の実装はHttpClientエンジンの背後に隠蔽されます。これにより開発時間が短縮され、プラットフォームの違いに関連するエラーの数が減少します。

Ktorの主な機能

Ktorは、モダンなKotlinプロジェクト、特にマルチプラットフォームプロジェクトにとって魅力的な選択肢となる一連の機能を提供します。

マルチプラットフォーム対応

KtorはJVM、Android、iOS、macOS、Windows、Linux、JavaScript、Wasmで動作します。同じHTTPクライアントコードが変更なしですべてのプラットフォームで実行されます。これはOkHttpやURLSessionに依存するライブラリに対する重要な利点です。

コルーチンによる非同期処理

Kotlinのコルーチンは、コールバックなしで自然な非同期処理を提供します。各リクエストはsuspend関数であり、任意のコルーチンから呼び出すことができます。KtorはFlowを介したレスポンスストリーミングをサポートしており、長時間の接続やWebSocketに便利です。

プラグインアーキテクチャ

Ktorのプラグインはinstallブロックを介して接続され、個別に設定されます。主要なプラグイン：シリアライゼーション用のContentNegotiation、ロギング用のLogging、認証用のAuth、双方向通信用のWebSockets。各プラグインは独立して有効または無効にできます。

エラーハンドリングとタイムアウト

Ktorのエラーハンドリングは例外に基づいています。ClientRequestExceptionは4xxコード、ServerResponseExceptionは5xx、IOExceptionはネットワーク障害時にスローされます。タイムアウトはHttpTimeoutプラグインを介して設定され、接続、読み取り、書き込みの待機時間を指定します。リトライには、試行回数と遅延の設定を持つRetryプラグインが使用されます。

Ktorの仕組み

Ktorはパイプラインアーキテクチャを採用しており、各リクエストはハンドラーのチェーンを通過します。クライアントはインストールされたプラグインを使用してHttpClient設定を作成し、getやpostの各呼び出しはプラグインを接続された順序で通過します。

HttpClientのアーキテクチャ

HttpClientオブジェクトは、プラットフォーム固有のエンジンで作成されます。JVMとAndroidにはCIO、iOSとmacOSにはDarwin、Android互換にはOkHttp、ブラウザにはJsです。エンジンは明示的に選択することも、自動選択に任せることもできます。各リクエストは、レスポンスボディ、ヘッダー、ステータスを含むHttpResponseを返します。

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

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

Ktorのインストールと設定

KtorのインストールはGradleまたはMavenを介して行います。マルチプラットフォームプロジェクトの場合、依存関係は各ターゲットのsourceSetsで指定します。KtorはMaven Centralを通じて配布されています。

Gradleを介した接続

build.gradle.ktsに、共通コード用のktor-client-core依存関係と、特定のプラットフォーム用のエンジンを追加します。Ktorのバージョンはgradle.propertiesの変数で設定します。Ktor 3.xにはKotlin 2.0+が必要で、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")
}

iOSの設定

iOSには、ネイティブのURLSessionをラップするDarwinエンジンを使用します。Kotlin Multiplatformでは、これにより最大のパフォーマンスとiOSシステムキャッシングメカニズムとの統合が実現します。エンジンはiOS sourceSetに個別の依存関係として追加されます。

Ktorの重要な機能は、ContentNegotiationを介したさまざまなシリアライゼーション形式のサポートです。JSONに加えて、プラグインはProtobuf、CBOR、XML、およびカスタム形式をサポートしています。シリアライゼーションにはkotlinx.serializationまたはJacksonライブラリが使用され、開発者はリクエストコードを変更せずにそれらを切り替えることができます。

Ktorの使用例

以下の例は、Ktorクライアントを使用した典型的なシナリオ（基本的なGETリクエスト、データ送信、マルチプラットフォームコードの操作）を示しています。

JSONデシリアライゼーションを使用したGETリクエスト

シンプルなGETリクエストで、レスポンスをデータクラスに自動的にデシリアライズします。Ktorはkotlinx.serializationを備えたContentNegotiationプラグインを使用してJSONをオブジェクトに変換します。コードは簡潔で型安全です。

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

JSONボディを使用したPOSTリクエスト

KtorのPOSTリクエストは、contentTypeとsetBodyを指定したpostメソッドを介してデータクラスをJSONボディとして送信します。ContentNegotiationプラグインは自動的にオブジェクトをJSON文字列にシリアライズします。レスポンスは同期的または非同期的に処理できます。

suspend fun createPost(): Post {
    val newPost = Post(
        id = 0,
        title = "新しい投稿",
        body = "投稿の内容"
    )
    val response = client.post("https://jsonplaceholder.typicode.com/posts") {
        contentType(ContentType.Application.Json)
        setBody(newPost)
    }
    return response.body()
}

Multipartによるファイルアップロード

KtorのsubmitFormWithBinaryDataメソッドを使用すると、multipart形式でファイルやフォームを送信できます。Ktorは自動的にデータを部分に分割し、ヘッダーを追加します。進行状況を追跡するにはonUploadを使用し、送信データのバイト数を受け取ります。

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 vs Retrofit：どちらを選ぶべきか

選択はプロジェクトのアーキテクチャとマルチプラットフォームの要件によって異なります。RetrofitはAndroid専用プロジェクトの標準であり続けていますが、KtorはKotlin Multiplatformに最適な選択肢です。

KtorはWebSocketおよびSSE（Server-Sent Events）の組み込みサポートも提供しており、リアルタイムアプリケーションに便利です。RetrofitはWebSocketを直接サポートしておらず、別途OkHttp WebSocketライブラリが必要です。Ktorはプラグインシステムにより、さまざまな環境向けの設定も容易で、各プラグインが1つの機能を担当します。

Ktorの認証

KtorのAuthプラグインは、基本認証、Bearerトークン、Digest、OAuth2をサポートしています。認証設定は宣言的に行われます。開発者はプロバイダー、トークンソース、スコープを指定します。Ktorは自動的にリクエストに認証ヘッダーを追加し、トークンの期限が切れたときに更新できます。

プロジェクトがiOSとAndroidで共有コードを使用するKotlin Multiplatformを採用している場合、Ktorは追加レイヤーなしで両方のプラットフォームで動作する唯一のオプションです。RetrofitはOkHttpとJVMに強く結びついており、iOSには不適切です。

Android専用プロジェクトの場合、Retrofitはより成熟したAPI、より多くのコンバーターとOkHttpインターセプターを提供します。Ktorもこのシナリオで動作しますが、プラグインエコシステムはあまり広範ではありません。どちらのライブラリもコルーチンをサポートし、同等のパフォーマンスを提供します。