サーバープラグイン

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

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

プラグインで機能を追加する

多くのアプリケーションでは、アプリケーションロジックの範囲外となる共通機能が必要です。これには、シリアライゼーション、コンテンツエンコーディング、圧縮、ヘッダー、Cookieのサポートなどが含まれます。これらすべては、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)
    // ...
}

リクエストとレスポンスをインターセプトするだけでなく、プラグインにはこのステップで設定されるオプションの構成セクションを持つことができます。

例えば、Cookieをインストールする際に、Cookieをどこに保存するか、その名前など、特定のパラメータを設定できます。

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で確認できます。

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