Server Plugin

ステータスページ

必須の依存関係: io.ktor:ktor-server-status-pages

コード例: status-pages

ネイティブサーバー

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

のサポート: ✅

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

依存関係の追加

StatusPagesを使用するには、ktor-server-status-pagesアーティファクトをビルドスクリプトに含める必要があります。

Gradle (Kotlin)Gradle (Groovy)Maven

StatusPagesのインストール

アプリケーションにStatusPagesプラグインをインストールするには、 指定された

モジュール

モジュールを使用すると、ルートをグループ化してアプリケーションを構造化できます。

のinstall関数に渡します。 以下のコードスニペットは、StatusPagesをインストールする方法を示しています。

• embeddedServer関数呼び出しの内部。
• Applicationクラスの拡張関数である、明示的に定義されたmoduleの内部。

embeddedServermodule

StatusPagesの設定

StatusPagesプラグインには、主に3つの設定オプションがあります。

• 例外: マップされた例外クラスに基づいて応答を設定します
• ステータス: ステータスコード値に応答を設定します
• ステータスファイル: クラスパスからファイル応答を設定します

例外

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

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

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

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ステータスコード）のリクエストに応答する方法を示しています。

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ステータスコードを次のように処理できます。

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

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

完全な例はこちらにあります: status-pages。