Skip to content
Server Plugin

リクエストのバリデーション

必要な依存関係: io.ktor:ktor-server-request-validation

コード例: request-validation

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

RequestValidation プラグインは、受信したリクエストのボディを検証(バリデーション)する機能を提供します。生のリクエストボディを検証することも、シリアライザーを備えた ContentNegotiation プラグインがインストールされている場合は、特定のリクエストオブジェクトのプロパティを検証することもできます。リクエストボディの検証に失敗すると、プラグインは RequestValidationException を発生させます。これは StatusPages プラグインを使用して処理できます。

依存関係の追加 ​

RequestValidation を使用するには、ビルドスクリプトに ktor-server-request-validation アーティファクトを追加します。

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

RequestValidation のインストール ​

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

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

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

RequestValidation プラグインは、特定のルートにインストールすることもできます。 これは、アプリケーションの異なるリソースに対して異なる RequestValidation 設定が必要な場合に便利です。

RequestValidation の設定 ​

RequestValidation の設定には、主に3つのステップが含まれます。

  1. ボディコンテンツの受信。
  2. 検証関数の設定。
  3. バリデーション例外の処理。

1. ボディの受信 ​

型パラメータを指定して receive 関数を呼び出すと、RequestValidation プラグインはリクエストのボディを検証します。たとえば、以下のコードスニペットはボディを String 値として受信する方法を示しています。

kotlin
routing {
    post("/text") {
        val body = call.receive<String>()
        call.respond(body)
    }
}

2. 検証関数の設定 ​

リクエストボディを検証するには、validate 関数を使用します。 この関数は、検証の成功または失敗の結果を表す ValidationResult オブジェクトを返します。 検証に失敗した場合は、RequestValidationException が発生します。

validate 関数には2つのオーバーロードがあり、2種類の方法でリクエストボディを検証できます。

  • 最初の validate オーバーロードでは、指定した型のオブジェクトとしてリクエストボディにアクセスできます。 以下の例は、String 値を表すリクエストボディを検証する方法を示しています。

    kotlin
    install(RequestValidation) {
        validate<String> { bodyText ->
            if (!bodyText.startsWith("Hello"))
                ValidationResult.Invalid("Body text should start with 'Hello'")
            else ValidationResult.Valid
        }
    }

    特定のシリアライザーを設定した ContentNegotiation プラグインがインストールされている場合は、オブジェクトのプロパティを検証できます。詳細については、例: オブジェクトプロパティの検証を参照してください。

  • 2番目の validate オーバーロードは ValidatorBuilder を受け取り、カスタム検証ルールを提供できるようにします。 詳細については、例: バイト配列の検証を参照してください。

3. バリデーション例外の処理 ​

リクエストの検証に失敗すると、RequestValidation は RequestValidationException を発生させます。 この例外を使用すると、リクエストボディにアクセスし、そのリクエストに対するすべての検証失敗の理由を取得できます。

RequestValidationException は、StatusPages プラグインを使用して次のように処理できます。

kotlin
install(StatusPages) {
    exception<RequestValidationException> { call, cause ->
        call.respond(HttpStatusCode.BadRequest, cause.reasons.joinToString())
    }
}

完全なコード例はこちらで確認できます: request-validation

例: オブジェクトプロパティの検証 ​

この例では、RequestValidation プラグインを使用してオブジェクトのプロパティを検証する方法を見ていきます。 サーバーが次の JSON データを含む POST リクエストを受信するとします。

HTTP
POST http://0.0.0.0:8080/json
Content-Type: application/json

{
  "id": -1,
  "firstName": "Jet",
  "lastName": "Brains"
}

id プロパティの検証を追加するには、次の手順を実行します。

  1. 上記の JSON オブジェクトを記述する Customer データクラスを作成します。

    kotlin
    @Serializable
    data class Customer(val id: Int, val firstName: String, val lastName: String)
  2. JSON シリアライザーを使用して ContentNegotiation プラグインをインストールします。

    kotlin
    install(ContentNegotiation) {
        json()
    }
  3. サーバー側で次のように Customer オブジェクトを受信します。

    kotlin
    post("/json") {
        val customer = call.receive<Customer>()
        call.respond(customer)
    }
  4. RequestValidation プラグインの設定で、id プロパティが指定した範囲内に収まっていることを確認するバリデーションを追加します。

    kotlin
    install(RequestValidation) {
        validate<Customer> { customer ->
            if (customer.id <= 0)
                ValidationResult.Invalid("A customer ID should be greater than 0")
            else ValidationResult.Valid
        }
    }

    この場合、id の値が 0 以下のとき、RequestValidation は RequestValidationException を発生させます。

例: バイト配列の検証 ​

この例では、バイト配列として受信したリクエストボディを検証する方法を見ていきます。 サーバーが次のテキストデータを含む POST リクエストを受信するとします。

HTTP
POST http://localhost:8080/array
Content-Type: text/plain

-1

データをバイト配列として受信して検証するには、次の手順を実行します。

  1. サーバー側で次のようにデータを受信します。
    kotlin
    post("/array") {
        val body = call.receive<ByteArray>()
        call.respond(String(body))
    }
  2. 受信したデータを検証するには、ValidatorBuilder を受け取りカスタム検証ルールを提供できる、2番目の validate 関数のオーバーロードを使用します。
    kotlin
    install(RequestValidation) {
        validate {
            filter { body ->
                body is ByteArray
            }
            validation { body ->
                check(body is ByteArray)
                val intValue = String(body).toInt()
                if (intValue <= 0)
                    ValidationResult.Invalid("A value should be greater than 0")
                else ValidationResult.Valid
            }
        }
    }