Content
Vapor3 中所有的 content 类型（JSON、protobuf、FormURLEncoded、Multipart等等）都是被同等对待的。你只需要解析和序列化 content 即可，该 content 必须是一个实现了Codable的类或结构体
为了方便介绍，我们将以 JSON为例。但是注意这个 API 对任何支持 content 类型的都是一样的。
Request
如何解析下面的这个 HTTP request。
POST /login HTTP/1.1
Content-Type: application/json
{
"email": "user@vapor.codes",
"password": "don't look!"
}
一、创建一个结构体或类,用来表示你期望的数据
import Vapor
struct LoginRequest: Content {
var email: String
var password: String
}
二、让该结构体或类实现Content,可以开始decode 这个HTTP request了
router.post("login") { req -> Future<HTTPStatus> in
return req.content.decode(LoginRequest.self).map(to: HTTPStatus.self) { loginRequest in
print(loginRequest.email) // user@vapor.codes
print(loginRequest.password) // don't look!
return .ok
}
}
这里我们使用.map(to:) 来返回一个 future 。
提示: 从请求解码这个过程是异步的，因为HTTP允许使用分块传输编码方式将主体分为多个部分
Router
为了使传入请求的内容解码更加容易，Vapor在 Router 中提供了一些自动完成此功能的扩展。
router.post(LoginRequest.self, at: "login") { req, loginRequest in
print(loginRequest.email) // user@vapor.codes
print(loginRequest.password) // don't look!
return HTTPStatus.ok
}
Detect Type (检测类型)
由于本例中的HTTP请求中我们将JSON声明为其内容类型，因此Vapor会自动使用JSON解码器。 对于以下请求，同样的方法也可以正常工作
POST /login HTTP/1.1
Content-Type: application/x-www-form-urlencoded
email=user@vapor.codes&don't+look!
所有HTTP请求都必须包含一个内容类型才能生效。 因此，如果遇到未知类型，Vapor将自动选择适当的解码器或者抛出错误。
提示: > 你可以 配置 Vapor使用的默认编码器和解码器
Custom
如果需要你可以重写Vapor的编解码器，并传入
let user = try req.content.decode(User.self, using: JSONDecoder())
print(user) // Future<User>
Response
如何创建 HTTP response
HTTP/1.1 200 OK
Content-Type: application/json
{
"name": "Vapor User",
"email": "user@vapor.codes"
}
一、 decoding 一样，首先创建一个结构体或类，用来表示你期望的数据
import Vapor
struct User: Content {
var name: String
var email: String
}
二、让结构体或类实现Content,可以开始 encode 这个 HTTP response了
router.get("user") { req -> User in
return User(
name: "Vapor User",
email: "user@vapor.codes"
)
}
这会创建一个默认的 带有200 OK 状态码和最小标题的 Response 。你可以通过便利方法encode(...) 来自定义响应体
router.get("user") { req -> Future<Response> in
return User(name: "Vapor User", email: "user@vapor.codes")
.encode(status: .created)
}
Override Type
Response的内容默认会编码成JSON，你可以通过 as: 并传入参数来改变编码方式
try res.content.encode(user, as: .urlEncodedForm)
你也可以修改类或者结构体使用的媒体类型
struct User: Content {
/// See `Content`.
static let defaultContentType: MediaType = .urlEncodedForm
...
}
Client
编码一个有Client 发送的请求内容和编码服务器HTTP响应的方式类似
Request
我们来看看如何编码下面请求
POST /login HTTP/1.1
Host: api.vapor.codes
Content-Type: application/json
{
"email": "user@vapor.codes",
"password": "don't look!"
}
Encode
一、首先创建一个结构体或者类来实现你期望的数据类型
import Vapor
struct LoginRequest: Content {
var email: String
var password: String
}
二、现在我们已经准备好发起我们的请求了，假设我们在一个路由闭包内发起这个请求，我们将使用传入的请求作为一个容器
let loginRequest = LoginRequest(email: "user@vapor.codes", password: "don't look!")
let res = try req.client().post("https://api.vapor.codes/login") { loginReq in
// encode the loginRequest before sending
try loginReq.content.encode(loginRequest)
}
print(res) // Future<Response>
Response
继续我们在 encode 部分的例子，让我们看看如何解码来自client的Response
HTTP/1.1 200 OK
Content-Type: application/json
{
"name": "Vapor User",
"email": "user@vapor.codes"
}
一、首先要创建一个结构体或类来表示期望的数据类型
import Vapor
struct User: Content {
var name: String
var email: String
}
二、Decode
现在我们准备好解码 Client 响应了
let res: Future<Response> // from the Client
let user = res.flatMap { try $0.content.decode(User.self) }
print(user) // Future<User>
Example
现在让我们看看完整的 Client 请求，它们都会对内容进行编解码
// 创建 LoginRequest 数据
let loginRequest = LoginRequest(email: "user@vapor.codes", password: "don't look!")
// POST /login
let user = try req.client().post("https://api.vapor.codes/login") { loginReq in
// 请求发送前编码
return try loginReq.content.encode(loginRequest)
}.flatMap { loginRes in
// 接收到响应后解码
return try loginRes.content.decode(User.self)
}
print(user) // Future<User>
Query String
URL-Encode的表单数据也可以像Content那样通过HTTP请求的URI query string来编解码. 所有你需要做的就是创建一个类或者结构体并且遵守 Content 协议。在这个例子里我们将使用下面的结构体
struct Flags: Content {
var search: String?
var isAdmin: Bool?
}
Decode
所有的 Request 都有一个 QueryContainer 你可以解码 query string
let flags = try req.query.decode(Flags.self)
print(flags) // Flags
Encode
你也可以编码内容。这在使用 Client 来编码查询字符串时很有用
let flags: Flags ...
try req.query.encode(flags)
Dynamic Properties
关于Content的最多的问题是：
如何添加属性到单独的一个Response
Vapor3处理 Content 的方式完全基于 Codable。在任何时候(可公开访问的)，你的数据都应该在一个类似 [String:Any]的数据结构中，你可以按你期望的方式修改它。因此，你的App接收和返回的数据结构都必须是静态定义的。
让我们来看看一个常见的场景，以便更好的理解这一点。通常你创建一个用户时，需要几种不同的数据格式:
- create: 提供两次密码以便检查是否匹配
- internal: 你应该存储一个散列函数而不是明文密码
- public: 列出用户时不应该包含密码的哈希值
为了实现这个，你需要创建三种类型的数据.
// Data required to create a user
struct UserCreate: Content {
var email: String
var password: String
var passwordCheck: String
}
// Our internal User representation
struct User: Model {
var id: Int?
var email: String
var passwordHash: Data
}
// Public user representation
struct PublicUser: Content {
var id: Int
var email: String
}
// Create a router for POST /users
router.post(UserCreate.self, at: "users") { req, userCreate -> PublicUser in
guard userCreate.password == passwordCheck else { /* some error */ }
let hasher = try req.make(/* some hasher */)
let user = try User(
email: userCreate.email,
passwordHash: hasher.hash(userCreate.password)
)
// save user
return try PublicUser(id: user.requireID(), email: user.email)
}
对于其它方法，例如 PATCH 和 PUT ，你或许需要创建更多的类型来支持唯一语义
好处 Benefits
与动态解决方案相比，这种方法看起来可能有点冗余，但它拥有很多关键优势:
- 静态类型 : 基于Swift和Codable，
- 可读性 : 使用Swift类型时，无需使用字符串和可选链
- 可维护性 : 在大型项目中，信息的分离使项目非常干净
- 可共享 ： 定义路由所接受，返回的类型，可用于OpenAPI规范，甚至可以直接和客户端共享
- 性能 : 使用Swift的类型，比使用[Sting:Any]字典性能更好
JSON
JSON是一种非常流行的API编码格式，日期，数据，浮点型等编码方式是非标准的。 正因为如此，使用自定义的JSONDecoder可以让Vapor在与其他API进行交互时更很容易。
// Conforms to Encodable
let user: User ...
// Encode JSON using custom date encoding strategy
try req.content.encode(json: user, using: .custom(dates: .millisecondsSince1970))
也可以用下面方法解码
// Decode JSON using custom date encoding strategy
let user = try req.content.decode(json: User.self, using: .custom(dates: .millisecondsSince1970))
如果你想在全局使用自定义JSON编解码器，你可以在 configuration 中进行
Configure
使用 ContentConfig 来注册应用程序的编解码器,这些编解码器将用于任何您使用 content.encode/content.decode 的地方
/// Create default content config
var contentConfig = ContentConfig.default()
/// Create custom JSON encoder
var jsonEncoder = JSONEncoder()
jsonEncoder.dateEncodingStrategy = .millisecondsSince1970
/// Register JSON encoder and content config
contentConfig.use(encoder: jsonEncoder, for: .json)
services.register(contentConfig)
