Server Plugin

請求驗證

所需依賴項：io.ktor:ktor-server-request-validation

程式碼範例： request-validation

原生伺服器

Ktor 支援 Kotlin/Native，讓您無需額外的執行時或虛擬機器即可運行伺服器。

支援：✅

RequestValidation 外掛程式提供了驗證傳入請求主體的能力。如果安裝了包含序列化器的 ContentNegotiation 外掛程式，您可以驗證原始請求主體或指定的請求物件屬性。如果請求主體驗證失敗，此外掛程式將引發 RequestValidationException 請求驗證例外，該例外可使用 StatusPages 狀態頁面外掛程式處理。

新增依賴項

若要使用 RequestValidation，您需要在建置腳本中包含 ktor-server-request-validation 構件：

Gradle (Kotlin)Gradle (Groovy)Maven

安裝 RequestValidation

若要將 RequestValidation 外掛程式安裝至應用程式， 請將其傳遞給指定

模組

模組允許您透過分組路由來組織應用程式。

中的 install 函數。 以下程式碼片段顯示如何安裝 RequestValidation ...

• ... 在 embeddedServer 函數呼叫內部。
• ... 在明確定義的 module 內部，它是 Application 類別的擴充函數。

embeddedServermodule

RequestValidation 外掛程式也可以安裝到特定的路由。 如果您需要針對不同的應用程式資源使用不同的 RequestValidation 配置，這將會很有用。

配置 RequestValidation

配置 RequestValidation 涉及三個主要步驟：

1. 接收主體內容。
2. 配置驗證函數。
3. 處理驗證例外。

1. 接收主體

如果您呼叫帶有型別參數的 receive 函數，RequestValidation 外掛程式將驗證請求的主體。例如，下面的程式碼片段顯示如何將主體接收為 String 值：

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

2. 配置驗證函數

若要驗證請求主體，請使用 validate 函數。 此函數回傳一個 ValidationResult 物件，代表成功或不成功的驗證結果。 對於不成功的結果，將引發 RequestValidationException 請求驗證例外。

validate 函數有兩個重載，允許您透過兩種方式驗證請求主體：

• 第一個 validate 重載允許您將請求主體作為指定型別的物件來存取。 下面的範例展示了如何驗證代表 String 值的請求主體：

  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：

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 驗證器建構器並允許您提供自訂驗證規則的第二個 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
           }
       }
   }