Ktor: とは何か、非同期HTTPクライアントの特徴

Ktorとは？

Ktorは、JetBrainsが作成したKotlinで非同期サーバーおよびクライアントアプリケーションを構築するためのフレームワークです。Ktor Clientはフレームワークのクライアント側部分であり、Kotlinコルーチン、マルチプラットフォーム（JVM、Native、JS）、およびモジュラープラグインベースのアーキテクチャを完全にサポートするHTTPクライアントを提供します。

Ktorは2018年に、Kotlinファーストのプロジェクト向けのRetrofitおよびOkHttpの代替として登場しました。アノテーションを使用したJavaアプローチを移植したRetrofitとは異なり、Ktor Clientはリクエスト設定にKotlin DSLを使用します。アノテーションやリフレクションは不要です。これにより、Kotlin開発者にとってコードの可読性と型安全性が向上します。

2024年のKotlin Multiplatform調査によると、Ktor ClientはKotlin Multiplatform Mobile（KMM）プロジェクトの35%で使用されており、KotlinコミュニティでOkHttpに次いで2番目に人気のあるHTTPクライアントとなっています。Ktorはマルチプラットフォーム対応とKotlinエコシステムとのネイティブ統合が重要なプロジェクトで好まれています。

Ktor Clientの仕組み

Ktor Clientのアーキテクチャはプラグインのパイプラインに基づいています。各リクエストは、リクエストやレスポンスを変更したり、ロギング、圧縮、シリアライゼーション、認証などの副作用を実行できるインストール済みプラグインのシーケンスを通過します。

HttpClient { } DSLブロックを介してHTTPクライアントを作成する際、エンジン（OkHttp、Android、CIO、Darwin）を指定し、プラグインをインストールします。各エンジンは特定のプラットフォーム向けの低レベルリクエスト送信を実装します：AndroidではOkHttpエンジン、iOSではDarwin（URLSession）、DesktopではCIO（Coroutine I/O）が使用されます。HttpClientは現在のプラットフォームに最適なエンジンを自動的に選択します。

Ktor Clientでのリクエストはsuspend関数を介して実行され、コルーチンとの完全な統合を意味します。コールバック、RxJava、LiveDataは不要で、スレッドをブロックせずに非同期で動作するsuspendを使用したシーケンシャルコードのみです。

リクエスト処理パイプライン

Ktorパイプラインはフェーズで構成されています：まずリクエストはインストールされたプラグイン（JSON用のContentNegotiation、ログ用のLoggingなど）を通過し、次にエンジンがHTTPリクエストを実行し、レスポンスはデシリアライゼーションのために再びプラグインを通過します。各プラグインはパイプラインコルーチン内で実行されるsuspend関数です。

Ktorパイプラインの重要な利点は、条件付き処理を実行できることです。プラグインはURLまたはリクエストヘッダーをチェックし、条件が満たされない場合は処理をスキップできます。たとえば、gzipを使用したContentEncodingは、Content-Encoding: gzipヘッダーを含むレスポンスにのみ適用され、Authは保護されたエンドポイントに対してのみトリガーされ、パブリックAPIには影響しません。

このパイプラインアプローチにより、プラグインを柔軟に組み合わせることができます：JSONを使用したContentNegotiationをインストールし、Bearerトークンを使用したAuthを追加し、ContentEncoding圧縮とHttpTimeoutを有効にすることができ、これらすべてが正しい順序で連携して動作します。プラグインのインストール順序は重要です：最初にインストールされたプラグインが他のプラグインよりも先にリクエストを処理します。

Ktor Clientプラグイン

プラグインはKtorのモジュラー拡張システムであり、RetrofitのアノテーションとOkHttpのインターセプターを置き換えます。各プラグインは特定のタスクを解決し、HttpClientブロック内のinstall()関数を介してインストールされます。Ktorは組み込みプラグインを提供し、カスタムプラグインの作成も許可します。

カスタムプラグイン

特定のタスクのために、createClientPluginを介してカスタムプラグインが作成されます。プラグインはリクエスト（onRequest）、レスポンス（onResponse）をインターセプトしたり、エラー（onError）を処理したりできます。これはOkHttpのInterceptorを完全に置き換えますが、型付けされたKotlin APIとsuspend関数のサポートを備えています。

カスタムプラグインは、メトリクスの追加、自動リトライロジック、リクエストトレーシング、またはエンドポイントのA/Bテストに便利です。OkHttpインターセプターとは異なり、KtorプラグインはKotlinで記述され、コルーチンコンテキストで実行されるため、エラーとタイムアウトの処理が簡素化されます。

リクエストのデバッグには、LoggingプラグインがALL、HEADERS、またはBODYレベルで使用されます。Loggingはメソッド、URL、ステータス、ヘッダー、リクエストとレスポンスのボディを出力します。OkHttpのHttpLoggingInterceptorとは異なり、Ktor Loggingは非同期で動作し、設定を変更するためにアプリケーションを停止することなく、ログレベル（ERROR、WARN、INFO、DEBUG）でフィルタリングするように設定できます。

KotlinでのKtor Clientコード例

Ktor Clientを使用した基本的なGETリクエストを見てみましょう。JSON用にContentNegotiationプラグインをインストールしてHttpClientを作成します。リクエストはsuspend関数get()を介して実行され、結果は自動的にデータクラスにデシリアライズされます。

data class User(
    val login: String,
    val id: Int,
    val avatarUrl: String
)

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

suspend fun getUser(): User {
    return client.get("https://api.github.com/users/octocat").body()
}

ボディ付きPOSTリクエストには、contentType()とbody()を指定してpost()関数を使用します。KtorはインストールされたContentNegotiationを介してオブジェクトを自動的にJSONにシリアライズします。DSLスタイルによりコードはシーケンシャルで読みやすくなります。

data class CreateRepo(
    val name: String,
    val description: String,
    val private: Boolean
)

suspend fun createRepo(): Unit {
    val repo = CreateRepo(
        name = "my-project",
        description = "Sample project",
        private = false
    )
    client.post("https://api.github.com/user/repos") {
        contentType(ContentType.Application.Json)
        setBody(repo)
    }
}

タイムアウトとヘッダーの設定

HttpTimeoutとDefaultRequestは設定のための2つの主要なプラグインです。HttpTimeoutは時間制限を設定し、DefaultRequestはすべてのリクエストのヘッダーとURLパラメーターを指定して、各呼び出しでのコード重複を排除します。

val client = HttpClient {
    install(HttpTimeout) {
        connectTimeoutMillis = 15000
        requestTimeoutMillis = 30000
    }
    install(DefaultRequest) {
        url("https://api.github.com/")
        header("Accept", "application/json")
    }
}

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

マルチプラットフォームは、OkHttpやRetrofitに対するKtorの主な利点です。Ktor ClientはJVM（Android、Server）、Native（iOS、macOS、Windows、Linux）、JS（Browser）で動作します。同じHTTPクライアントコードが変更なしですべてのプラットフォームで実行され、これはKotlin Multiplatformプロジェクトにとって特に価値があります。

各プラットフォームに対して、Ktorは独自のエンジンを使用します。AndroidではデフォルトでOkHttpエンジンが使用され、OkHttpエコシステムとの完全な互換性を提供します。iOSではURLSessionベースのDarwinEngineが使用されます。サーバーにはCIOEngine（Coroutine I/O）が使用されます。エンジンは明示的に指定することもできます：HttpClient(OkHttp) { } または HttpClient(Darwin) { }。

エンジンを選択する際は、その機能を考慮してください：OkHttpエンジンはHTTP/2とコネクションプーリングをサポートし、DarwinEngineはネイティブiOSネットワーク統合とバックグラウンドURLSessionセッションを提供し、CIOEngineは外部依存関係のない純粋なコルーチン実装です。Webターゲットには、fetch APIを介して動作するJsEngineまたはBrowserEngineが使用されます。

すべてのプラットフォームで統一されたAPIのおかげで、データをロードするコードはAndroid、iOS、Desktopで同じように見えます。これにより、Retrofit（Android）とURLSession（iOS）での個別の実装と比較して、KMMプロジェクトでのコード重複が60～80%削減されます。プラグインも変更なしですべてのプラットフォームで動作します。

Ktor使用時のよくある間違い

HttpClientのクローズの無視はKtorでのよくある間違いです。HttpClientはCloseableを実装しており、アプリケーション終了時にclient.close()を介してクローズする必要があります。Androidでは、ActivityのonDestroy()またはViewModel.onCleared()でこれを行います。クローズされていないクライアントは、コルーチンとエンジンスレッドのリークにつながります。

プラグインの順序の誤りはリクエスト処理を壊す可能性があります。たとえば、ContentNegotiationはDefaultRequestの前にインストールして、コンテンツタイプが正しく適用されるようにする必要があります。Loggingは、すべての変更後のリクエストの最終バージョンをログに記録するために、最後にインストールすることをお勧めします。プラグインが予期しない動作をする場合は、順序を試してみてください。

suspend関数での例外処理の欠如。Ktorはネットワークエラーに対してIOExceptionを、HTTP 4xxステータスに対してClientRequestExceptionをスローします。get()、post()、およびその他のメソッドの呼び出しごとにtry-catchブロックが必須です。各メソッドでtry-catchを重複させずにグローバルエラー処理を行うには、HttpClientブロックでHttpResponseValidatorを使用してください。