Skip to content

サーバープラグイン ​

Ktorにおける一般的なリクエスト/レスポンスパイプラインは次のようになります。

Request Response Pipeline

リクエストはサーバーによって受信され、リクエストパイプラインを通じて処理されます。Ktorはリクエストを適切なハンドラーにルーティングし、アプリケーションロジックがそれを処理します。その後、レスポンスはクライアントに送信される前にレスポンスパイプラインを通過します。

プラグインによる機能の追加 ​

多くのアプリケーションでは、アプリケーションロジックとは切り離された機能が必要になります。これには認証、シリアライゼーションやコンテンツエンコーディング、圧縮、ヘッダー、Cookieなどが含まれます。Ktorでは、このような機能は プラグイン によって提供されます。

プラグインは、リクエストおよびレスポンス処理のさまざまなステージをインターセプトできます。そのため、リクエスト/レスポンスパイプラインのさまざまなポイントに適用できます。

Plugin pipeline

プラグインが実行される正確なステージは、プラグイン自体、およびそれが使用するフックやパイプラインフェーズによって異なります。一般的に、リクエストは次のように処理されます。

  • ルーティング機構が、どのハンドラーがリクエストを処理すべきかを決定します。
  • ハンドラーに渡される前に、リクエストは1つ以上のプラグインによって処理されます。
  • ハンドラーはアプリケーションロジックを使用してレスポンスを生成します。
  • レスポンスがクライアントに送信される前に、1つ以上のプラグインによって処理されます。

ルーティングもプラグイン ​

プラグインは最大限の柔軟性を提供し、リクエスト/レスポンスパイプラインの任意のセグメントに存在できるように設計されています。Ktorでは、routing 自体もプラグインとして実装されています。

Routing as a Plugin

プラグインの依存関係を追加する ​

ほとんどのプラグインには個別の依存関係が必要です。たとえば、CORS プラグインを使用するには、ビルドスクリプトに ktor-server-cors アーティファクトが必要です。

kotlin
implementation(ktorLibs.server.cors)
上記のスニペットでは、Ktorの依存関係を指定するために Ktorバージョンカタログを使用しています。
groovy
implementation ktorLibs.server.cors
上記のスニペットでは、Ktorの依存関係を指定するために Ktorバージョンカタログを使用しています。
xml
<dependency>
    <groupId>io.ktor</groupId>
    <artifactId>ktor-server-cors-jvm</artifactId>
    <version>${ktor_version}</version>
</dependency>

利用可能なプラグインの完全なリストについては、Ktor Project Generatorを参照してください。特定のプラグインに必要な依存関係については、該当するプラグインのドキュメントを参照してください。

プラグインのインストール ​

プラグインは通常、サーバーの初期化フェーズで install() 関数を使用して設定されます。サーバーの作成方法に応じて、embeddedServer() 関数内またはアプリケーションモジュール内でプラグインをインストールできます。

kotlin
import io.ktor.server.application.*
import io.ktor.server.plugins.cors.*
import io.ktor.server.plugins.compression.*
// ...
fun main() {
    embeddedServer(Netty, port = 8080) {
        install(CORS)
        install(Compression)
        // ...
    }.start(wait = true)
}
kotlin
import io.ktor.server.application.*
import io.ktor.server.plugins.cors.*
import io.ktor.server.plugins.compression.*
// ...
fun Application.module() {
    install(CORS)
    install(Compression)
    // ...
}

install() 関数に設定ブロックを渡すことで、プラグインのインストール時に設定を行えます。

たとえば、Sessions プラグインをインストールする際、セッションタイプとCookie名を指定することでCookieベースのセッションを設定できます。

kotlin
install(Sessions) {
    cookie<MyCookie>("MY_COOKIE")
}

特定のルートにプラグインをインストールする ​

Ktorでは、プラグインをグローバルだけでなく特定のルートにインストールすることもできます。これは、リソースごとに異なるプラグイン設定が必要な場合に便利です。

たとえば、次のコードは /index ルートに CachingHeader プラグインをインストールし、キャッシュヘッダーを追加するように設定する例を示しています。

kotlin
route("/index") {
    install(CachingHeaders) {
        options { call, content -> CachingOptions(CacheControl.MaxAge(maxAgeSeconds = 1800)) }
    }
    get {
        call.respondText("Index page")
    }
}

同じプラグインが複数のレベルでインストールされている場合、Ktorは次のルールを適用します。

  • 特定のルートにインストールされたプラグインの設定は、対応するグローバルなプラグイン設定をオーバーライドします。
  • 同じルートが複数回定義され、同じプラグインのインストールが複数含まれている場合、ルーティングはそのルートに対するインストールをマージします。その際、最後のインストールが優先されます。

次の例では、/index/a と /index/b への呼び出しは両方とも、2番目の CachingHeaders インストールによってのみ処理されます。

kotlin
routing {
    route("index") {
        install(CachingHeaders) { /* First configuration */ }
        get("a") {
            // ...
        }
    }
    route("index") {
        install(CachingHeaders) { /* Second configuration */ }
        get("b") {
            // ...
        }
    }
}

デフォルト、利用可能、およびカスタムプラグイン ​

Ktorはデフォルトではアプリケーションプラグインをインストールしません。アプリケーションに必要な機能を提供するプラグインをインストールしてください。

Ktorは幅広いプラグインを提供しています。利用可能なプラグインの完全なリストは、Ktor Project Generatorで確認できます。

また、独自のカスタムプラグインを作成して、アプリケーション全体で再利用したり、他のアプリケーションと共有したりできる機能をカプセル化することもできます。