請求驗證
必要的相依性: io.ktor:ktor-server-request-validation
程式碼範例: request-validation
原生伺服器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 包含三個主要步驟:
1. 接收本文
如果您呼叫帶有型別參數的 receive 函式,RequestValidation 外掛程式會驗證請求本文。例如,以下程式碼片段展示如何將本文接收為 String 值:
routing {
post("/text") {
val body = call.receive<String>()
call.respond(body)
}
}2. 設定驗證函式
若要驗證請求本文,請使用 validate 函式。 此函式會傳回代表驗證成功或失敗結果的 ValidationResult 物件。 對於失敗的結果,將會引發 RequestValidationException。
validate 函式具有兩個多載,可讓您透過兩種方式驗證請求本文:
第一個
validate多載可讓您將請求本文作為指定型別的物件進行存取。 以下範例展示如何驗證代表String值的請求本文:kotlininstall(RequestValidation) { validate<String> { bodyText -> if (!bodyText.startsWith("Hello")) ValidationResult.Invalid("Body text should start with 'Hello'") else ValidationResult.Valid } }如果您已安裝並設定了包含特定序列化程式的
ContentNegotiation外掛程式,則可以驗證物件屬性。若要了解更多,請參閱範例:驗證物件屬性。第二個
validate多載接受ValidatorBuilder,並允許您提供自訂驗證規則。 您可以從範例:驗證位元組陣列了解更多。
3. 處理驗證例外狀況
如果請求驗證失敗,RequestValidation 會引發 RequestValidationException。 此例外狀況可讓您存取請求本文,並取得該請求所有驗證失敗的原因。
您可以依照下列方式使用 StatusPages 外掛程式來處理 RequestValidationException:
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)) } - 若要驗證接收到的資料,我們將使用第二個
validate函式多載,該多載接受ValidatorBuilder並允許您提供自訂驗證規則: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 } } }
