请求与响应

HTTP 请求的结构

每一个到达 Vapor 服务器的 HTTP 请求都被封装成 Request 对象。理解 Request 的内部结构，是编写正确处理逻辑的前提。

核心概念词典

请求体解码：DTO 模式

DTO（Data Transfer Object，数据传输对象）是服务端开发的重要设计模式：用单独的结构体表示 API 的输入输出格式，与数据库 Model 分离。这样可以避免 API 直接暴露数据库字段（如 passwordHash），也方便对输入做验证和转换。

// 输入 DTO：客户端发来的数据
struct CreateUserDTO: Content {
    let name:     String
    let email:    String
    let password: String

    // 自定义验证
    func validate() throws {
        guard email.contains("@") else {
            throw Abort(.badRequest, reason: "Invalid email format")
        }
        guard password.count >= 8 else {
            throw Abort(.badRequest, reason: "Password must be at least 8 characters")
        }
    }
}

// 输出 DTO：返回给客户端的数据（不含 passwordHash！）
struct UserResponse: Content {
    let id:        UUID
    let name:      String
    let email:     String
    let createdAt: Date?

    init(from user: User) {
        self.id        = user.id!
        self.name      = user.name
        self.email     = user.email
        self.createdAt = user.createdAt
    }
}

// 路由处理函数
app.post("users") { req async throws -> Response in
    // 1. 解码请求体（失败自动返回 400）
    let dto = try req.content.decode(CreateUserDTO.self)

    // 2. 业务验证
    try dto.validate()

    // 3. 检查邮箱是否已存在
    if try await User.query(on: req.db).filter(\.$email == dto.email).first() != nil {
        throw Abort(.conflict, reason: "Email already in use")
    }

    // 4. 创建 Model（密码哈希处理）
    let hash = try Bcrypt.hash(dto.password)
    let user = User(name: dto.name, email: dto.email, passwordHash: hash)
    try await user.save(on: req.db)

    // 5. 返回 201 Created + 资源 URL
    let response = UserResponse(from: user)
    return try req.response(.created, content: response)
}

统一错误响应

Vapor 的 ErrorMiddleware（默认已注册）会捕获所有从路由函数中抛出的错误，将其转换为统一的 JSON 错误响应。你也可以实现 AbortError 协议来定制错误格式：

// 自定义错误类型
enum AppError: AbortError {
    case userNotFound(UUID)
    case emailAlreadyExists(String)
    case insufficientPermissions

    var status: HTTPResponseStatus {
        switch self {
        case .userNotFound:          return .notFound
        case .emailAlreadyExists:    return .conflict
        case .insufficientPermissions: return .forbidden
        }
    }

    var reason: String {
        switch self {
        case .userNotFound(let id): return "User \(id) not found"
        case .emailAlreadyExists(let email): return "Email '\(email)' is already registered"
        case .insufficientPermissions: return "You don't have permission to perform this action"
        }
    }
}

// 使用自定义错误
app.get("users", ":id") { req async throws -> UserResponse in
    let id = try req.parameters.require("id", as: UUID.self)
    guard let user = try await User.find(id, on: req.db) else {
        throw AppError.userNotFound(id)
    }
    return UserResponse(from: user)
}

// 客户端收到的响应：
// HTTP/1.1 404 Not Found
// {"error": true, "reason": "User abc-123 not found"}

文件上传处理

文件上传使用 multipart/form-data 内容类型。Vapor 内置了 multipart 解析支持，通过 File 类型接收上传的文件数据：

struct UploadDTO: Content {
    var file:        File       // 文件字段
    var description: String?   // 额外文本字段
}

app.post("upload") { req async throws -> Response in
    // 限制上传大小（默认 16KB body size，需要调大）
    app.routes.defaultMaxBodySize = "10mb"

    let upload = try req.content.decode(UploadDTO.self)
    let file   = upload.file

    // 验证文件类型
    guard let ext = file.extension, ["jpg", "png", "gif"].contains(ext) else {
        throw Abort(.badRequest, reason: "Only image files are allowed")
    }

    // 保存文件到磁盘
    let filename   = "\(UUID()).\(ext)"
    let uploadPath = req.application.directory.publicDirectory + "uploads/" + filename
    try await req.fileio.writeFile(ByteBuffer(buffer: file.data), at: uploadPath)

    return Response(status: .created, headers: ["Location": "/uploads/\(filename)"])
}

Vapor Validation：内置验证框架

除了手动在 DTO 里写 validate() 方法，Vapor 提供了内置的 Validatable 协议，通过声明式方式定义验证规则，错误信息自动聚合：

import Vapor

struct CreateUserDTO: Content, Validatable {
    let name:     String
    let email:    String
    let password: String
    let age:      Int

    // 声明验证规则（Validatable 协议要求实现此静态方法）
    static func validations(_ validations: inout Validations) {
        validations.add("name",     as: String.self, is: .count(2...50))
        validations.add("email",    as: String.self, is: .email)
        validations.add("password", as: String.self, is: .count(8...) & .ascii)
        validations.add("age",      as: Int.self,    is: .range(18...))
    }
}

// 路由中调用 validate() — 失败自动抛出包含所有错误的 400 响应
app.post("users") { req async throws -> UserResponse in
    try CreateUserDTO.validate(content: req)  // 一行验证全部规则
    let dto = try req.content.decode(CreateUserDTO.self)
    // 验证通过后才会执行到这里
    ...
}

// 客户端收到的验证失败响应示例：
// HTTP/1.1 400 Bad Request
// {
//   "error": true,
//   "reason": "email is not a valid email address, password is less than minimum of 8 character(s)"
// }

分页响应模式

列表 API 通常需要分页。Vapor 内置了 Page 类型支持分页查询，与 Fluent 的 .paginate() 配合使用非常方便：

// GET /users?page=1&per=20
app.get("users") { req async throws -> Page<UserResponse> in
    // Fluent 自动从查询参数读取 page 和 per，生成 LIMIT/OFFSET SQL
    let page = try await User.query(on: req.db)
        .sort(\.$createdAt, .descending)
        .paginate(for: req)
    // 将 Page<User> 映射为 Page<UserResponse>
    return page.map { UserResponse(from: $0) }
}

// 客户端收到的响应结构：
// {
//   "items": [...],
//   "metadata": {
//     "page": 1,
//     "per": 20,
//     "total": 143
//   }
// }