Skip to content
Server Plugin

ステータスページ

必要な依存関係: io.ktor:ktor-server-status-pages

コード例: status-pages

ネイティブサーバーKtorはKotlin/Nativeをサポートしており、追加のランタイムや仮想マシンなしでサーバーを実行できます。のサポート: ✅

StatusPages プラグインを使用すると、Ktor アプリケーションはスローされた例外やステータスコードに基づいて、あらゆる障害状態に適切に応答できるようになります。

依存関係の追加 ​

StatusPages を使用するには、ビルドスクリプトに ktor-server-status-pages アーティファクトを追加します:

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

StatusPages のインストール ​

StatusPages プラグインをアプリケーションにインストールするには、指定されたモジュールモジュールを使用すると、ルートをグループ化してアプリケーションを構造化できます。内の install 関数に渡します。 以下の例は、StatusPages をインストールする方法を示しています:

  • embeddedServer() 関数呼び出し内。
  • Application クラスに明示的に定義された module() 拡張関数内。
kotlin
import io.ktor.server.engine.*
import io.ktor.server.netty.*
import io.ktor.server.application.*
import io.ktor.server.plugins.statuspages.*

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

StatusPages の設定 ​

StatusPages プラグインには、主に3つの設定オプションが用意されています:

  • exceptions: マッピングされた例外クラスに基づいてレスポンスを設定します
  • status: ステータスコードの値に対するレスポンスを設定します
  • statusFile: クラスパスからのファイルレスポンスを設定します

例外 ​

exception ハンドラーを使用すると、Throwable 例外が発生した呼び出しを処理できます。最も基本的なケースでは、任意の例外に対して 500 HTTP ステータスコードを設定できます:

kotlin
install(StatusPages) {
    exception<Throwable> { call, cause ->
        call.respondText(text = "500: $cause" , status = HttpStatusCode.InternalServerError)
    }
}

また、特定の例外をチェックして、必要なコンテンツで応答することもできます:

kotlin
install(StatusPages) {
    exception<Throwable> { call, cause ->
        if(cause is AuthorizationException) {
            call.respondText(text = "403: $cause" , status = HttpStatusCode.Forbidden)
        } else {
            call.respondText(text = "500: $cause" , status = HttpStatusCode.InternalServerError)
        }
    }
}

ステータス ​

status ハンドラーは、ステータスコードに基づいて特定のコンテンツで応答する機能を提供します。以下の例は、サーバー上にリソースが存在しない場合(ステータスコード 404)にリクエストへ応答する方法を示しています:

kotlin
install(StatusPages) {
    status(HttpStatusCode.NotFound) { call, status ->
        call.respondText(text = "404: Page Not Found", status = status)
    }
}

ステータスファイル ​

statusFile ハンドラーを使用すると、ステータスコードに基づいて HTML ページを返すことができます。プロジェクトの resources フォルダーに error401.html と error402.html という HTML ページが含まれているとします。この場合、次のように statusFile を使用して 401 および 402 ステータスコードを処理できます:

kotlin
install(StatusPages) {
    statusFile(HttpStatusCode.Unauthorized, HttpStatusCode.PaymentRequired, filePattern = "error#.html")
}

statusFile ハンドラーは、設定されたステータスのリスト内にあるステータスコードの値で、任意の # 文字を置き換えます。

完全な例はこちらで確認できます: status-pages。