Server Plugin

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

必須の依存関係: io.ktor:ktor-server-request-validation

コード例: request-validation

ネイティブサーバー

Ktor supports Kotlin/Native and allows you to run a server without an additional runtime or virtual machine.

のサポート: ✅

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

依存関係の追加

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

Gradle (Kotlin)Gradle (Groovy)Maven

RequestValidationのインストール

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

モジュール

Modules allow you to structure your application by grouping routes.

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

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

embeddedServermodule

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

RequestValidationの設定

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

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

1. ボディの受信

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

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

2. バリデーション関数の設定

リクエストボディをバリデートするには、validate関数を使用します。 この関数は、成功または失敗したバリデーション結果を表すValidationResultオブジェクトを返します。 失敗した結果の場合、RequestValidationExceptionがスローされます。

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

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

  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プラグインを使用して次のように処理できます:

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

完全な例はこちらから確認できます: request-validation。

例：オブジェクトプロパティのバリデーション

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

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

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

idプロパティのバリデーションを追加するには、以下の手順に従ってください:

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

   @Serializable
   data class Customer(val id: Int, val firstName: String, val lastName: String)

2. JSONシリアライザーを使用してContentNegotiationプラグインをインストールします:

   install(ContentNegotiation) {
       json()
   }

3. サーバー側でCustomerオブジェクトを次のように受信します:

   post("/json") {
       val customer = call.receive<Customer>()
       call.respond(customer)
   }

4. RequestValidationプラグインの設定で、idプロパティが指定された範囲内にあることを確認するためのバリデーションを追加します:

   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リクエストを受信すると仮定します:

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

-1

バイト配列としてデータを受信し、バリデートするには、以下の手順を実行します:

1. サーバー側でデータを次のように受信します:

   post("/array") {
       val body = call.receive<ByteArray>()
       call.respond(String(body))
   }

2. 受信したデータをバリデートするには、ValidatorBuilderを受け入れ、カスタムバリデーションルールを提供できる、2番目のvalidate関数オーバーロードを使用します:

   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
           }
       }
   }