mirror of https://github.com/vapor/docs.git
297 lines
9.6 KiB
Markdown
297 lines
9.6 KiB
Markdown
# Validation API
|
||
|
||
Vapor 的 **Validation API** 可帮助你在使用 [Content](content.zh.md) API 解码数据之前，对传入的请求进行验证。
|
||
|
||
## 介绍
|
||
|
||
Vapor 对 Swift 的类型安全的`可编码`协议进行了深度集成，这意味着与动态类型的语言相比，你无需担心数据验证。但是，出于某些原因，你可能想选择使用 **Validation API** 进行显式验证。
|
||
|
||
|
||
### 语义可读错误
|
||
|
||
如果取得的数据无效，使用 [Content](content.zh.md) API 对其解码将产生错误。但是，这些错误消息有时可能缺乏可读性。例如，采用以下字符串支持的枚举：
|
||
|
||
```swift
|
||
enum Color: String, Codable {
|
||
case red, blue, green
|
||
}
|
||
```
|
||
|
||
如果用户尝试将字符串 `”purple”` 传递给 `“Color”` 类型的属性，则将收到类似于以下内容的错误：
|
||
|
||
```
|
||
Cannot initialize Color from invalid String value purple for key favoriteColor
|
||
```
|
||
|
||
尽管此错误在技术上是正确的，并且可以成功地保护端点免受无效值的影响，但它可以更好地通知用户该错误以及可用的选项。通过使用 **Validation API**，你可以生成类似以下的错误：
|
||
|
||
```
|
||
favoriteColor is not red, blue, or green
|
||
```
|
||
|
||
此外，一旦遇到第一个错误，`Codable` 将停止尝试解码。这意味着即使请求中有许多无效属性，用户也只会看到第一个错误。 **Validation API** 将在单个请求中抛出所有的验证失败信息。
|
||
|
||
### 特殊验证
|
||
|
||
`Codable` 可以很好地处理类型验证，但是有时候你还想要更多的验证方式。例如，验证字符串的内容或验证整数的大小。**Validation API** 具有此类验证器，可帮助验证电子邮件、字符集、整数范围等数据。
|
||
|
||
## 验证
|
||
|
||
为了验证请求，你需要生成一个 `Validations` 集合。最常见的做法是使现有类型继承 **Validatable**。
|
||
|
||
让我们看一下如何向这个简单的 `POST/users` 请求添加验证。本指南假定你已经熟悉 [Content](content.md) API。
|
||
|
||
|
||
```swift
|
||
enum Color: String, Codable {
|
||
case red, blue, green
|
||
}
|
||
|
||
struct CreateUser: Content {
|
||
var name: String
|
||
var username: String
|
||
var age: Int
|
||
var email: String
|
||
var favoriteColor: Color?
|
||
}
|
||
|
||
app.post("users") { req -> CreateUser in
|
||
let user = try req.content.decode(CreateUser.self)
|
||
// Do something with user.
|
||
return user
|
||
}
|
||
```
|
||
|
||
### 添加验证
|
||
|
||
第一步是在你要解码的类型（在本例中为 `CreateUser`）遵循 `Validatable` 协议并实现 `validations` 静态方法，可在 `extension` 中完成。
|
||
|
||
```swift
|
||
extension CreateUser: Validatable {
|
||
static func validations(_ validations: inout Validations) {
|
||
// Validations go here.
|
||
}
|
||
}
|
||
```
|
||
|
||
验证 `CreateUser` 后，将调用静态方法 `validations（_ :)`。你要执行的所有验证都应添加到 **Validations** 集合中。让我们添加一个简单的验证，以验证用户的电子邮件是否有效。
|
||
|
||
```swift
|
||
validations.add("email", as: String.self, is: .email)
|
||
```
|
||
|
||
第一个参数是参数值的预期键，在本例中为 `email`。这应与正在验证的类型上的属性名称匹配。第二个参数 `as` 是预期的类型，在这种情况下为 `String`。该类型通常与属性的类型匹配。最后，可以在第三个参数 `is` 之后添加一个或多个验证器。在这种情况下，我们添加一个验证器，以检查该值是否为电子邮件地址。
|
||
|
||
|
||
### 验证请求的 `Content`
|
||
|
||
当你的数据类型继承了 `Validatable`，就可以使用 `validate(content:)` 静态方法来验证请求的 `content`。在路由处理程序中 `req.content.decode(CreateUser.self)` 之前添加以下行：
|
||
|
||
```swift
|
||
try CreateUser.validate(content: req)
|
||
```
|
||
|
||
现在，尝试发送以下包含无效电子邮件的请求：
|
||
|
||
```http
|
||
POST /users HTTP/1.1
|
||
Content-Length: 67
|
||
Content-Type: application/json
|
||
|
||
```
|
||
|
||
你应该能看到返回以下错误：
|
||
|
||
```
|
||
email is not a valid email address
|
||
```
|
||
|
||
### 验证请求的 `Query`
|
||
|
||
当你的数据类型继承了 `Validatable`，就可以使用 `validate(query:)` 静态方法来验证请求的 `query`。在路由处理程序中添加以下行：
|
||
|
||
```swift
|
||
try CreateUser.validate(query: req)
|
||
req.query.decode(CreateUser.self)
|
||
```
|
||
|
||
现在，尝试发送以下请求，该请求在查询字符串中包含无效的电子邮件。
|
||
|
||
```http
|
||
GET /users?age=4&email=foo&favoriteColor=green&name=Foo&username=foo HTTP/1.1
|
||
|
||
```
|
||
|
||
你将会看到下面的错误：
|
||
|
||
```
|
||
email is not a valid email address
|
||
```
|
||
### 整数验证
|
||
|
||
现在让我们尝试添加一个针对整数年龄的验证：
|
||
|
||
```swift
|
||
validations.add("age", as: Int.self, is: .range(13...))
|
||
```
|
||
|
||
年龄验证要求年龄大于或等于`13`。如果你尝试发送一个和上面相同的请求，现在应该会看到一个新错误：
|
||
|
||
```
|
||
age is less than minimum of 13, email is not a valid email address
|
||
```
|
||
|
||
### 字符串验证
|
||
|
||
接下来，让我们添加对 `name` 和 `username` 的验证。
|
||
|
||
```swift
|
||
validations.add("name", as: String.self, is: !.empty)
|
||
validations.add("username", as: String.self, is: .count(3...) && .alphanumeric)
|
||
```
|
||
|
||
|
||
名称验证使用 `!` 运算符将 `.empty` 验证反转。这要求该字符串不为空。
|
||
|
||
用户名验证使用`&&`组合了两个验证器。这将要求该字符串的长度至少为3个字符，并且仅包含字母数字字符。
|
||
|
||
### 枚举验证
|
||
|
||
最后，让我们看一下更高级的验证，以检查提供的 `favoriteColor` 是否有效：
|
||
|
||
```swift
|
||
validations.add(
|
||
"favoriteColor", as: String.self,
|
||
is: .in("red", "blue","green"),
|
||
required: false
|
||
)
|
||
```
|
||
|
||
由于无法从无效值中解码 `Color`，因此此验证将 `String` 用作基本类型。它使用 `.in` 验证器来验证该值是有效的选项：红色、蓝色或绿色。由于该值是可选的，因此将 `required` 设置为 false 表示如果请求数据中缺少此字段，则验证不会失败。
|
||
|
||
请注意，如果缺少此字段，则收藏夹颜色验证将通过，但如果提供 `null`，则不会通过。 如果要支持 `null`，请将验证类型更改为 `String?`，并使用 `.nil ||`。
|
||
|
||
```swift
|
||
validations.add(
|
||
"favoriteColor", as: String?.self,
|
||
is: .nil || .in("red", "blue", "green"),
|
||
required: false
|
||
)
|
||
```
|
||
|
||
### 自定义错误
|
||
|
||
你可能希望将自定义的可读错误添加到你的 `Validations` 或者 `Validator`。为此，只需添加 `customFailureDescription` 参数，该参数将覆盖默认错误信息。
|
||
|
||
```swift
|
||
validations.add(
|
||
"name",
|
||
as: String.self,
|
||
is: !.empty,
|
||
customFailureDescription: "Provided name is empty!"
|
||
)
|
||
validations.add(
|
||
"username",
|
||
as: String.self,
|
||
is: .count(3...) && .alphanumeric,
|
||
customFailureDescription: "Provided username is invalid!"
|
||
)
|
||
```
|
||
|
||
## 验证器
|
||
|
||
以下是当前支持的验证器的列表，并简要说明了它们的作用：
|
||
|
||
|验证方式|描述|
|
||
|:--|:--|
|
||
|`.ascii`|仅包含ASCII字符|
|
||
|`.alphanumeric`|仅包含字母数字字符|
|
||
|`.characterSet(_:)`|仅包含提供的 `CharacterSet` 中的字符|
|
||
|`.count(_:)`|在提供范围内的集合计数|
|
||
|`.email`|包含有效的电子邮件|
|
||
|`.empty`|集合为空|
|
||
|`.in(_:)`|值在提供的“集合”中|
|
||
|`.nil`|值为`null`|
|
||
|`.range(_:)`|值在提供的范围内|
|
||
|`.url`|包含有效的URL|
|
||
|
||
验证器也可以使用运算符组合起来以构建复杂的验证：
|
||
|
||
|操作符|位置|描述|
|
||
|:--|:--|:--|
|
||
|`!`|前面|反转验证器，要求相反|
|
||
|`&&`|中间|组合两个验证器，需要同时满足|
|
||
|`||`|中间|组合两个验证器，至少满足一个|
|
||
|
||
## 自定义验证器
|
||
|
||
创建一个自定义的验证器用于验证邮政编码，允许你通过扩展验证器框架的功能来实现。本节中，我们将引导你完成创建用于验证邮政编码的自定义验证器的步骤。
|
||
|
||
首先，创建一个新类型用于表示 `ZipCode` 的验证结果。这个结构体负责报告给定的字符串是否是有效的邮政编码。
|
||
|
||
|
||
```swift
|
||
extension ValidatorResults {
|
||
/// 表示验证器的结果，该验证器检查一个字符串是否为有效的邮政编码。
|
||
public struct ZipCode {
|
||
/// 指示输入是否为有效的邮政编码。
|
||
public let isValidZipCode: Bool
|
||
}
|
||
}
|
||
```
|
||
|
||
接下来，使新类型遵循 `ValidatorResult` 协议，该接口定义了自定义验证器所期望的行为。
|
||
|
||
|
||
```swift
|
||
extension ValidatorResults.ZipCode: ValidatorResult {
|
||
public var isFailure: Bool {
|
||
!self.isValidZipCode
|
||
}
|
||
|
||
public var successDescription: String? {
|
||
"is a valid zip code"
|
||
}
|
||
|
||
public var failureDescription: String? {
|
||
"is not a valid zip code"
|
||
}
|
||
}
|
||
```
|
||
|
||
最后，实现邮政编码的验证逻辑。使用正则表达式检查输入字符串是否与美国邮政编码的格式匹配。
|
||
|
||
|
||
```swift
|
||
private let zipCodeRegex: String = "^\\d{5}(?:[-\\s]\\d{4})?$"
|
||
|
||
extension Validator where T == String {
|
||
/// 验证一个 `String` 是否是有效的邮政编码。
|
||
public static var zipCode: Validator<T> {
|
||
.init { input in
|
||
guard let range = input.range(of: zipCodeRegex, options: [.regularExpression]),
|
||
range.lowerBound == input.startIndex && range.upperBound == input.endIndex
|
||
else {
|
||
return ValidatorResults.ZipCode(isValidZipCode: false)
|
||
}
|
||
return ValidatorResults.ZipCode(isValidZipCode: true)
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
现在你已经定义了自定义的 `zipCode` 验证器，你可以在应用程序中使用它来验证邮政编码。只需将以下行添加到你的验证代码中：
|
||
|
||
|
||
```swift
|
||
validations.add("zipCode", as: String.self, is: .zipCode)
|
||
```
|
||
|