リクエストのバリデーション
必要な依存関係: io.ktor:ktor-server-request-validation
コード例: request-validation
Native サーバーKtorはKotlin/Nativeをサポートしており、追加のランタイムや仮想マシンなしでサーバーを実行できます。のサポート: ✅
RequestValidation プラグインは、受信したリクエストのボディを検証(バリデーション)する機能を提供します。生のリクエストボディを検証することも、シリアライザーを備えた ContentNegotiation プラグインがインストールされている場合は、特定のリクエストオブジェクトのプロパティを検証することもできます。リクエストボディの検証に失敗すると、プラグインは RequestValidationException を発生させます。これは StatusPages プラグインを使用して処理できます。
依存関係の追加
RequestValidation を使用するには、ビルドスクリプトに ktor-server-request-validation アーティファクトを追加します。
implementation(ktorLibs.server.requestValidation)implementation ktorLibs.server.requestValidation<dependency>
<groupId>io.ktor</groupId>
<artifactId>ktor-server-request-validation-jvm</artifactId>
<version>${ktor_version}</version>
</dependency>RequestValidation のインストール
RequestValidation プラグインをアプリケーションにインストールするには、 指定したモジュールモジュールを使用すると、ルートをグループ化してアプリケーションを構造化できます。内の install 関数に渡します。 以下の例は、RequestValidation をインストールする方法を示しています。
embeddedServer()関数の呼び出し内。Applicationクラスに明示的に定義されたmodule()拡張関数内。
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)
}import io.ktor.server.application.*
import io.ktor.server.plugins.requestvalidation.*
// ...
fun Application.module() {
install(RequestValidation)
// ...
}RequestValidation プラグインは、特定のルートにインストールすることもできます。 これは、アプリケーションの異なるリソースに対して異なる RequestValidation 設定が必要な場合に便利です。
RequestValidation の設定
RequestValidation の設定には、主に3つのステップが含まれます。
1. ボディの受信
型パラメータを指定して receive 関数を呼び出すと、RequestValidation プラグインはリクエストのボディを検証します。たとえば、以下のコードスニペットはボディを String 値として受信する方法を示しています。
routing {
post("/text") {
val body = call.receive<String>()
call.respond(body)
}
}2. 検証関数の設定
リクエストボディを検証するには、validate 関数を使用します。 この関数は、検証の成功または失敗の結果を表す ValidationResult オブジェクトを返します。 検証に失敗した場合は、RequestValidationException が発生します。
validate 関数には2つのオーバーロードがあり、2種類の方法でリクエストボディを検証できます。
最初の
validateオーバーロードでは、指定した型のオブジェクトとしてリクエストボディにアクセスできます。 以下の例は、String値を表すリクエストボディを検証する方法を示しています。kotlininstall(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 プロパティの検証を追加するには、次の手順を実行します。
上記の JSON オブジェクトを記述する
Customerデータクラスを作成します。kotlin@Serializable data class Customer(val id: Int, val firstName: String, val lastName: String)JSON シリアライザーを使用して
ContentNegotiationプラグインをインストールします。kotlininstall(ContentNegotiation) { json() }サーバー側で次のように
Customerオブジェクトを受信します。kotlinpost("/json") { val customer = call.receive<Customer>() call.respond(customer) }RequestValidationプラグインの設定で、idプロパティが指定した範囲内に収まっていることを確認するバリデーションを追加します。kotlininstall(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データをバイト配列として受信して検証するには、次の手順を実行します。
- サーバー側で次のようにデータを受信します。kotlin
post("/array") { val body = call.receive<ByteArray>() call.respond(String(body)) } - 受信したデータを検証するには、
ValidatorBuilderを受け取りカスタム検証ルールを提供できる、2番目のvalidate関数のオーバーロードを使用します。kotlininstall(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 } } }
