サーバープラグイン

Ktorにおける典型的なリクエスト/レスポンスパイプラインは以下のようになります：

これはリクエストから始まり、特定のハンドラーにルーティングされ、アプリケーションロジックによって処理され、最終的にレスポンスが返されます。

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

多くのアプリケーションでは、アプリケーションロジックの範囲外にある共通の機能を必要とします。これには、シリアライズやコンテンツエンコーディング、圧縮、ヘッダー、クッキーのサポートなどが含まれます。これらすべては、Ktorではプラグイン (Plugins)と呼ばれるものによって提供されます。

先ほどのパイプライン図を見ると、プラグインはリクエスト/レスポンスとアプリケーションロジックの間に位置しています：

リクエストが入ってくると：

• ルーティングメカニズムを介して正しいハンドラーにルーティングされます
• ハンドラーに渡される前に、1つ以上のプラグインを通過します
• ハンドラー（アプリケーションロジック）がリクエストを処理します
• レスポンスがクライアントに送信される前に、1つ以上のプラグインを通過します

ルーティングはプラグインの一種です

プラグインは最大限の柔軟性を提供するように設計されており、リクエスト/レスポンスパイプラインの任意のセグメントに存在させることができます。 実際、これまで私たちがroutingと呼んできたものは、プラグインに他なりません。

プラグインの依存関係の追加

ほとんどのプラグインは、特定の依存関係を必要とします。例えば、CORSプラグインを使用するには、ビルドスクリプトにktor-server-corsアーティファクトを追加する必要があります。

Gradle (Kotlin)Gradle (Groovy)Maven

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

プラグインは通常、サーバーの初期化フェーズにおいて、プラグインをパラメータとして受け取るinstall関数を使用して設定されます。サーバーの作成と設定方法に応じて、embeddedServer呼び出し内でプラグインをインストールするか...

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

... または、指定されたモジュール内でインストールできます：

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<MyCookie>("MY_COOKIE")
}

特定のルートへのプラグインのインストール

Ktorでは、プラグインをグローバルだけでなく、特定のルートにインストールすることもできます。これは、アプリケーションのリソースごとに異なるプラグイン設定が必要な場合に便利です。例えば、以下の例は、/indexルートに対して指定されたキャッシュヘッダーを追加する方法を示しています。

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

同じプラグインを複数回インストールする場合、以下のルールが適用されることに注意してください。

• 特定のルートにインストールされたプラグインの設定は、そのグローバル設定を上書きします。

• ルーティングは同じルートに対するインストールをマージし、最後のインストールが優先されます。例えば、以下のようなアプリケーションの場合...

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

"}

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

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

デフォルトでは、Ktorはいかなるプラグインも有効にしません。そのため、アプリケーションが必要とする機能に合わせてプラグインをインストールするのは開発者次第です。

ただし、Ktorは標準で提供される多様なプラグインを備えています。これらの完全なリストは、Ktor Plugin Registryで確認できます。

さらに、独自のカスタムプラグインを作成することもできます。