Skip to content
Server Plugin

請求驗證

必要的相依性: io.ktor:ktor-server-request-validation

程式碼範例: request-validation

原生伺服器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 包含三個主要步驟:

  1. 接收本文內容。
  2. 設定驗證函式。
  3. 處理驗證例外狀況。

1. 接收本文 ​

如果您呼叫帶有型別參數的 receive 函式,RequestValidation 外掛程式會驗證請求本文。例如,以下程式碼片段展示如何將本文接收為 String 值:

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

2. 設定驗證函式 ​

若要驗證請求本文,請使用 validate 函式。 此函式會傳回代表驗證成功或失敗結果的 ValidationResult 物件。 對於失敗的結果,將會引發 RequestValidationException。

validate 函式具有兩個多載,可讓您透過兩種方式驗證請求本文:

  • 第一個 validate 多載可讓您將請求本文作為指定型別的物件進行存取。 以下範例展示如何驗證代表 String 值的請求本文:

    kotlin
    install(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:

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. 若要驗證接收到的資料,我們將使用第二個 validate 函式多載,該多載接受 ValidatorBuilder 並允許您提供自訂驗證規則:
    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
            }
        }
    }