Server Plugin

ステータスページ

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

コード例: status-pages

Native サーバー

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 つの設定オプションがあります。

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

例外 (Exceptions)

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)

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

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

ステータスファイル (Status file)

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

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

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

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