中间件

中间件的洋葱执行模型

中间件（Middleware）是一种在请求到达处理函数之前、响应返回客户端之前插入逻辑的机制。Vapor 的中间件采用洋葱模型：请求由外向内穿过每一层中间件，响应由内向外经过同样的层。

这种双向穿透的特性使得同一个中间件可以同时处理请求阶段（前置逻辑）和响应阶段（后置逻辑），非常适合实现日志记录（记录请求和响应）、计时（测量处理耗时）、错误处理（捕获异常包装成统一格式）等场景。

核心概念词典

自定义中间件：请求日志

一个完整的请求日志中间件需要记录：请求方法、路径、来源 IP、处理耗时、响应状态码。以下实现利用了洋葱模型的双向特性，在请求阶段记录开始时间，在响应阶段计算耗时：

// Sources/App/Middleware/RequestLogMiddleware.swift
import Vapor
import Foundation

struct RequestLogMiddleware: AsyncMiddleware {

    func respond(to request: Request,
                 chainingTo next: AsyncResponder) async throws -> Response {

        // ── 请求阶段（进入）────────────────────────
        let startTime = Date()
        let requestID = UUID().uuidString.prefix(8)
        let ip        = request.headers["X-Forwarded-For"].first
                        ?? request.remoteAddress?.hostname
                        ?? "unknown"

        request.logger.info("[\(requestID)] → \(request.method) \(request.url.path) from \(ip)")

        // 存入 Request.Storage 供下游使用
        request.storage[RequestIDKey.self] = String(requestID)

        do {
            // ── 传递给下一层 ──────────────────────────
            let response = try await next.respond(to: request)

            // ── 响应阶段（返回）────────────────────────
            let elapsed = Int(Date().timeIntervalSince(startTime) * 1000)
            request.logger.info("[\(requestID)] ← \(response.status.code) (\(elapsed)ms)")

            // 在响应头中附加 Request-ID
            response.headers.replaceOrAdd(name: "X-Request-ID", value: String(requestID))
            return response

        } catch {
            let elapsed = Int(Date().timeIntervalSince(startTime) * 1000)
            request.logger.error("[\(requestID)] ✗ Error: \(error) (\(elapsed)ms)")
            throw error  // 继续向外抛，让 ErrorMiddleware 处理
        }
    }
}

// Request.Storage Key
private enum RequestIDKey: StorageKey {
    typealias Value = String
}

// 扩展 Request，方便访问
extension Request {
    var requestID: String? {
        storage[RequestIDKey.self]
    }
}

CORS 配置

前后端分离项目中，浏览器的同源策略会阻止跨域请求。CORSMiddleware 负责处理浏览器发出的 OPTIONS preflight 请求，并在响应中附加允许跨域的头部：

// configure.swift — CORS 配置
let corsConfig = CORSMiddleware.Configuration(
    allowedOrigin:  .any([
        "https://myapp.com",
        "https://www.myapp.com",
        "http://localhost:3000"   // 开发环境
    ]),
    allowedMethods: [.GET, .POST, .PUT, .PATCH, .DELETE, .OPTIONS],
    allowedHeaders: [.accept, .authorization, .contentType, .origin],
    allowCredentials: true,
    cacheExpiration: 600   // preflight 缓存 600 秒
)

// 注册顺序很关键！CORS 必须在路由之前，ErrorMiddleware 之后
app.middleware.use(ErrorMiddleware.default(environment: app.environment))
app.middleware.use(CORSMiddleware(configuration: corsConfig))
app.middleware.use(RequestLogMiddleware())
app.middleware.use(RateLimitMiddleware(requestsPerMinute: 60))

限流中间件

限流（Rate Limiting）防止 API 被滥用或遭受暴力破解。以下是基于内存的简单令牌桶实现，生产环境建议使用 Redis 实现分布式限流：

actor RateLimiter {
    private var buckets: [String: (Int, Date)] = [:]
    private let limit:   Int
    private let window:  TimeInterval = 60  // 60 秒窗口

    init(requestsPerMinute: Int) { limit = requestsPerMinute }

    func check(ip: String) -> Bool {
        let now = Date()
        if let (count, windowStart) = buckets[ip],
           now.timeIntervalSince(windowStart) < window {
            if count >= limit { return false }
            buckets[ip] = (count + 1, windowStart)
        } else {
            buckets[ip] = (1, now)
        }
        return true
    }
}

struct RateLimitMiddleware: AsyncMiddleware {
    private let limiter: RateLimiter

    init(requestsPerMinute: Int) {
        limiter = RateLimiter(requestsPerMinute: requestsPerMinute)
    }

    func respond(to request: Request,
                 chainingTo next: AsyncResponder) async throws -> Response {
        let ip = request.remoteAddress?.hostname ?? "unknown"
        guard await limiter.check(ip: ip) else {
            throw Abort(.tooManyRequests, reason: "Rate limit exceeded")
        }
        return try await next.respond(to: request)
    }
}