mirror of https://github.com/vapor/docs.git
158 lines
5.7 KiB
Markdown
158 lines
5.7 KiB
Markdown
# Middleware
|
||
|
||
Middleware 是 client 和路由处理程序间的一个逻辑链。它允许你在传入请求到达路由处理程序之前对传入请求执行操作，并且在输出响应到达 client 之前对传出响应执行操作。
|
||
|
||
## Configuration
|
||
|
||
可以使用 `app.middleware` 在 `configure(_:)` 中全局（针对每条路由）注册 Middleware。
|
||
|
||
```swift
|
||
app.middleware.use(MyMiddleware())
|
||
```
|
||
|
||
你也可以通过路由组的方式给单个路由添加 Middleware。
|
||
|
||
```swift
|
||
let group = app.grouped(MyMiddleware())
|
||
group.get("foo") { req in
|
||
// 该请求通过 MyMiddleware 传递。
|
||
}
|
||
```
|
||
|
||
### Order
|
||
|
||
Middleware 的添加顺序非常重要。进入应用程序的请求将按照在 middleware 添加的顺序依次执行。
|
||
离开应用程序的响应将以相反的顺序通过 Middleware 返回。特定的路由 Middleware 始终在应用程序 Middleware 之后运行。请看以下示例：
|
||
|
||
```swift
|
||
app.middleware.use(MiddlewareA())
|
||
app.middleware.use(MiddlewareB())
|
||
|
||
app.group(MiddlewareC()) {
|
||
$0.get("hello") { req in
|
||
"Hello, middleware."
|
||
}
|
||
}
|
||
```
|
||
|
||
`GET /hello` 这个请求将按照以下顺序访问 Middleware：
|
||
|
||
```
|
||
Request → A → B → C → Handler → C → B → A → Response
|
||
```
|
||
|
||
中间件也可以 _预先_ 添加，当你想在 vapor 自动添加的默认中间件 _之前_ 添加一个中间件时，这很有用:
|
||
|
||
```swift
|
||
app.middleware.use(someMiddleware, at: .beginning)
|
||
```
|
||
|
||
## 创建一个中间件
|
||
|
||
Vapor 附带了一些有用的中间件，但你可以根据需要创建自己的中间件。例如，你可以创建一个中间件来阻止任何非管理员用户访问一组路由。
|
||
|
||
> 我们建议在 `Sources/App` 目录中创建一个 `Middleware` 文件夹，来组织你的代码。
|
||
|
||
中间件类型遵循 `Middleware` 协议或 `AsyncMiddleware` 协议。它们被插入到响应链中，可以在请求到达路由处理之前访问和操作请求，也可以在返回响应之前访问和操作响应。
|
||
|
||
使用上面提到的例子，创建一个中间件来阻止非管理员用户的访问:
|
||
|
||
```swift
|
||
import Vapor
|
||
|
||
struct EnsureAdminUserMiddleware: Middleware {
|
||
func respond(to request: Request, chainingTo next: Responder) -> EventLoopFuture<Response> {
|
||
guard let user = request.auth.get(User.self), user.role == .admin else {
|
||
return request.eventLoop.future(error: Abort(.unauthorized))
|
||
}
|
||
return next.respond(to: request)
|
||
}
|
||
}
|
||
```
|
||
|
||
或者使用 `async`/`await` 你可以这样写：
|
||
|
||
```swift
|
||
import Vapor
|
||
|
||
struct EnsureAdminUserMiddleware: AsyncMiddleware {
|
||
func respond(to request: Request, chainingTo next: AsyncResponder) async throws -> Response {
|
||
guard let user = request.auth.get(User.self), user.role == .admin else {
|
||
throw Abort(.unauthorized)
|
||
}
|
||
return try await next.respond(to: request)
|
||
}
|
||
}
|
||
```
|
||
|
||
如果你想修改响应，例如添加一个自定义 header，你也可以为此使用一个中间件。中间件可以等待，直到从响应链接收到响应，然后对响应进行操作：
|
||
|
||
```swift
|
||
import Vapor
|
||
|
||
struct AddVersionHeaderMiddleware: Middleware {
|
||
func respond(to request: Request, chainingTo next: Responder) -> EventLoopFuture<Response> {
|
||
next.respond(to: request).map { response in
|
||
response.headers.add(name: "My-App-Version", value: "v2.5.9")
|
||
return response
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
或者使用 `async`/`await` 你可以这么写：
|
||
|
||
```swift
|
||
import Vapor
|
||
|
||
struct AddVersionHeaderMiddleware: AsyncMiddleware {
|
||
func respond(to request: Request, chainingTo next: AsyncResponder) async throws -> Response {
|
||
let response = try await next.respond(to: request)
|
||
response.headers.add(name: "My-App-Version", value: "v2.5.9")
|
||
return response
|
||
}
|
||
}
|
||
```
|
||
|
||
## File Middleware
|
||
|
||
`FileMiddleware` 允许从项目的 Public 文件夹向 client 提供资源。你可以在这里存放 css 或者位图图片等静态文件。
|
||
|
||
```swift
|
||
let file = FileMiddleware(publicDirectory: app.directory.publicDirectory)
|
||
app.middleware.use(file)
|
||
```
|
||
|
||
一旦注册 `FileMiddleware`，比如 `Public/images/logo.png` 的文件可以在 Leaf 模板通过 `<img src="/images/logo.png"/>` 方式引用。
|
||
|
||
如果你的服务器包含在一个 Xcode 项目中，比如一个 iOS 应用，可以使用以下代码代替：
|
||
|
||
```swift
|
||
let file = try FileMiddleware(bundle: .main, publicDirectory: "Public")
|
||
```
|
||
|
||
同时，请确保在 Xcode 中使用文件夹引用（Folder References）而不是 Xcode 中的组（Groups）来保持资源文件夹结构在构建应用程序后不变。
|
||
|
||
|
||
## CORS Middleware
|
||
|
||
跨域资源共享（Cross-origin resource sharing，缩写：CORS），用于让网页的受限资源能够被其他域名的页面访问的一种机制。通过该机制，页面能够自由地使用不同源（英語：cross-origin）的图片、样式、脚本、iframes 以及视频。Vapor 内置的 REST API 需要 CORS 策略，以便将请求安全地返回到 Web 浏览器。
|
||
|
||
配置示例如下所示：
|
||
|
||
```swift
|
||
let corsConfiguration = CORSMiddleware.Configuration(
|
||
allowedOrigin: .all,
|
||
allowedMethods: [.GET, .POST, .PUT, .OPTIONS, .DELETE, .PATCH],
|
||
allowedHeaders: [.accept, .authorization, .contentType, .origin, .xRequestedWith, .userAgent, .accessControlAllowOrigin]
|
||
)
|
||
let cors = CORSMiddleware(configuration: corsConfiguration)
|
||
let error = ErrorMiddleware.default(environment: app.environment)
|
||
// 清除现有的 middleware。
|
||
app.middleware = .init()
|
||
app.middleware.use(cors)
|
||
app.middleware.use(error)
|
||
```
|
||
|
||
由于抛出的错误会立即返回给客户端，因此必须在 `ErrorMiddleware` 之前注册 `CORSMiddleware`。否则，将返回不带 CORS 标头的 HTTP 错误响应，且浏览器无法读取该错误响应。
|