Vapor 框架学习记录（4）Sessions 和验证

在本篇中，我们将专注于构建基于session的 Web 身份验证层。 用户将能够使用表单登录，并且已经登录的用户将在session cookie 和使用 Fluent 的持久session存储的帮助下被检测到。 我们会使用自定义身份验证器中间件，通过session或credentials对用户进行身份验证。

User module

用户模块将负责用户管理和认证。 请创建一个新的用户模块目录结构，就像我们为博客模块所做的那样。 我们将需要一个 User 文件夹，一个包含 Migrations 和 Models 目录的 Database 文件夹。
首先我们需要一个模型来存储用户帐号数据，用户可以通过邮箱和密码进行登录。所以我们需要新建一个UserAccountModel

/// FILE: Sources/App/Modules/User/Database/Models/UserAccountModel.swift

import Vapor
import Fluent

final class UserAccountModel: DatabaseModelInterface {
    typealias Module = UserModule
    
    struct FieldKeys {
        struct v1 {
            static var email: FieldKey { "email" }
            static var password: FieldKey { "password" }
        }
    }
    
    @ID() var id: UUID?
    @Field(key: FieldKeys.v1.email) var email: String
    @Field(key: FieldKeys.v1.password) var password: String
    
    init() { }
    
    init(id: UUID? = nil, email: String, password: String) {
        self.id = id
        self.email = email
        self.password = password
    }
}

跟上一篇文章一样，我们还需要实现数据库迁移来初始化用户表和做数据填充。

/// FILE: Sources/App/Modules/User/Database/Migrations/UserMigrations.swift

import Vapor
import Fluent

enum UserMigrations {
    
    struct v1: AsyncMigration {
        
        func prepare(on database: Database) async throws {
            try await database.schema(UserAccountModel.schema)
                .id()
                .field(UserAccountModel.FieldKeys.v1.email, .string, .required)
                .field(UserAccountModel.FieldKeys.v1.password, .string, .required)
                .unique(on: UserAccountModel.FieldKeys.v1.email)
                .create()
        }
        
        func revert(on database: Database) async throws {
            try await database.schema(UserAccountModel.schema).delete()
        }
        
    }
    
    struct seed: AsyncMigration {
        
        func prepare(on database: Database) async throws {
            let email = "root@loacalhost.com"
            let password = "changeMe1"
            let user = UserAccountModel(email: email, password: try Bcrypt.hash(password))
            try await user.create(on: database)
        }
        
        func revert(on database: Database) async throws {
            try await UserAccountModel.query(on: database).delete()
        }   
    }
}

与之前不同的是，我们使用了unique去约束了 email字段的唯一性。同时数据填充时，我们将密码加密了，敏感信息不应该明文存储，我们需要时刻保持警觉。

最后创建我们的UserModule去使用数据迁移吧。

/// FILE: Sources/App/Modules/User/UserModule.swift
import Vapor

struct UserModule: ModuleInterface {
    func boot(_ app: Application) throws {
        app.migrations.add(UserMigrations.v1())
        app.migrations.add(UserMigrations.seed())
    }
}

不要忘记把 UserModule添加到配置文件了。

// configures your application
public func configure(_ app: Application) throws {
    // ...
 
    /// setup modules
    let modules: [ModuleInterface] = [
        WebModule(),
        BlogModule(),
        UserModule()
    ]
    for module in modules {
        try module.boot(app)
    }

    /// use automatic database migration
    try app.autoMigrate().wait()
}

现在，如果你运行该应用程序，新的用户表会创建，并且包含root 帐号

Sessions

首先，在配置文件，我们配置应用的Sessions

// configures your application
public func configure(_ app: Application) throws {
    // ...
    
    /// setup Sessions
    app.sessions.use(.fluent)
    app.migrations.add(SessionRecord.migration)
    app.middleware.use(app.sessions.middleware)

    //...
}

第一行代码表示我们使用的是Fluent Session进行存储，第二行是添加一个底层的 _fluent_sessions表。
最后一行代码我们很熟悉，是添加了 app.sessions.middleware中间件，这个中间件会尝试从客户端的的cookie中读取session。

登录页面

前面我们已经有了用户数据表存储我们的用户数据了，当然还需要一个登录表单页去输入验证。我们开始搭建这个页面吧。跟之前一样，我们需要一个模版和context

/// FILE: Sources/App/Modules/User/Templates/Contexts/UserLoginContext.swift
struct UserLoginContext {
    let icon: String
    let title: String
    let message: String
    let email: String?
    let password: String?
    let error: String?
    
    init(icon: String,
         title: String,
         message: String,
         email: String? = nil,
         password: String? = nil,
         error: String? = nil) {
        self.icon = icon
        self.title = title
        self.message = message
        self.email = email
        self.password = password
        self.error = error
    }
}

登录页面比较简单，会用到 Form元素去搭建表单。使用2个 input标签进行输入。

/// FILE: Sources/App/Modules/User/Templates/Html/UserLoginTemplate.swift

import Vapor
import SwiftHtml
import SwiftSgml

struct UserLoginTemplate: TemplateRepresentable {
    
    var context: UserLoginContext
    
    @TagBuilder
    func render(_ req: Request) -> Tag {
        WebIndexTemplate.init(.init(title: context.title)) {
            Div {
                Section {
                    P (context.icon)
                    H1(context.title)
                    P(context.message)
                }
                .class("lead")
                
                Form {
                    if let error = context.error {
                        Section {
                            Span(error)
                                .class(error)
                        }
                    }
                    Section {
                        Label("Email:")
                            .for("email")
                        Input()
                            .key("email")
                            .type(.email)
                            .value(context.email)
                            .class("field")
                    }
                    
                    Section {
                        Label("Password:")
                            .for("password")
                        Input()
                            .key("password")
                            .type(.password)
                            .value(context.password)
                            .class("field")
                    }
                    
                    Section {
                        Input()
                            .type(.submit)
                            .value("Sign in")
                            .class("submit")
                    }
                }
                .action("/sign-in/")
                .method(.post)
            }
            .id("user-login")
            .class("container")
        }
        .render(req)
    }
}

这是一个面向用户的前端登录表单，所以我们需要套用Index模板。

现在，如果我们渲染这个模板并按下提交按钮，浏览器将使用表单字段的 URLEncoded 内容向 /sign-in/ 端点执行 POST 请求。 所以我们需要两个端点来处理这些事情。 一个端点将负责表单呈现，另一个端点将通过 POST 请求处理表单提交。

/// FILE: Sources/App/Modules/User/Controllers/UserFrontendController.swift

import Vapor

struct UserFrontendController {
    
    func signInView(_ req: Request) async throws -> Response {
        let template = UserLoginTemplate(context: .init(icon: "⬇️", title: "Sign in", message: "Please log in with your existing account"))
        return req.templates.renderHtml(template)
    }
    
    func signInAction(_ req: Request) async throws -> Response {
        // @TODO: handle sign in action
        return try await signInView(req)
    }
    
}

再把这两个endpoints注册在UserRouter.swift

/// FILE: Sources/App/Modules/User/UserRouter.swift

import Vapor

struct UserRouter: RouteCollection {
    let frontendController = UserFrontendController()
    
    func boot(routes: RoutesBuilder) throws {
        routes.get("sign-in", use: frontendController.signInView)
        routes.post("sign-in", use: frontendController.signInAction)
    }
}

同样的，还需要在UserModule.swift调用 boot方法使这两个路由工作

/// FILE: Sources/App/Modules/User/UserModule.swift
import Vapor

struct UserModule: ModuleInterface {
    
    let router = UserRouter()
    
    func boot(_ app: Application) throws {
        app.migrations.add(UserMigrations.v1())
        app.migrations.add(UserMigrations.seed())
        
        try router.boot(routes: app.routes)
    }
}

现在，如果我们访问 /sign-in/ 端点，我们应该会看到一个简单的登录表单页，但因为我们没有正确处理登录操作，所以还不能进行登录， 下一步我们需要处理登录验证。

authenticator

authenticator是一个中间件，如果请求中存在登录必要的数据，它将尝试使用authenticatable对象登录。 身份验证数据存储在 req.auth 属性中。

应该注意 req.auth 变量不等同于 req.session 属性。 它们服务于不同的目的。 可以将 SessionAuthenticatable 对象存储在 req.session 变量中。 这些对象将被持久化，并在客户端使用Session cookie 来跟踪当前Session。 这允许我们在用户通过登录表单正确验证后保持登录状态。

/// FILE: Sources/App/Framework/AuthenticatedUser.swift
import Vapor

public struct AuthenticatedUser {
    public let id: UUID
    public let email: String
}

extension AuthenticatedUser: SessionAuthenticatable {
    public var sessionID: UUID { id }
}

基于凭据的身份验证是指用户必须提供正确的电子邮件和密码组合。 然后我们可以使用这些值在 accounts 表中进行查找，以检查它是否是现有记录，并查看字段是否匹配。 如果一切正确，我们可以对用户进行身份验证，这意味着登录尝试成功。 我们将实现一个可用于执行此操作的独立 UserCredentialsAuthenticator。

/// FILE: Sources/App/Modules/User/Authenticators/UserCredentialsAuthenticator.swift

import Vapor
import Fluent

struct UserCredentialsAuthenticator: AsyncCredentialsAuthenticator {
    struct Credentials: Content {
        let email: String
        let password: String
    }
    
    func authenticate(credentials: Credentials, for request: Request) async throws {
        guard let user = try await UserAccountModel
                .query(on: request.db)
                .filter(\.$email == credentials.email)
                .first()
        else { return }
        
        do {
            guard try Bcrypt.verify(credentials.password, created: user.password) else { return }
            request.auth.login(AuthenticatedUser(id: user.id!, email: user.email))
        }
        catch {
            // do nothing 
        }
    }
}

输入是一个 Content 对象，它是 Vapor 对可以从传入请求解码或编码为响应的内容的定义。 Vapor 有多种内容类型，既有 JSON 也有 URLEncoded 内容编码器和解码器。 当用户按下提交按钮时，HTML 表单正在发送一个 URLEncoded 数据。
验证函数接收凭据并尝试在数据库中查找具有有效密码的现有用户。 如果我们找到一条记录，我们可以使用之前创建的 AuthenticatedUser 对象调用 req.auth.login 方法。 这会将我们的用户信息保存到身份验证存储中，其余的请求处理程序可以检查是否存在现有的 AuthenticatedUser，这将指示是否有登录用户。
我们将在我们的 post /sign-in/ 路由中使用这个身份验证器

/// FILE: Sources/App/Modules/User/UserRouter.swift

import Vapor

struct UserRouter: RouteCollection {
    let frontendController = UserFrontendController()
    
    func boot(routes: RoutesBuilder) throws {
        routes.get("sign-in", use: frontendController.signInView)
        routes
            .grouped(UserCredentialsAuthenticator())
            .post("sign-in", use: frontendController.signInAction)
    }
}

我们还应该更新用户前端控制器以实际实现我们的 signInAction 方法。

/// FILE: Sources/App/Modules/User/Controllers/UserFrontendController.swift

import Vapor

struct UserFrontendController {
    
    struct Input: Decodable {
        let email: String?
        let password: String?
    }
    
    func renderSignInView(_ req: Request, _ input: Input? = nil, _ error: String? = nil) -> Response {
        let template = UserLoginTemplate(context: .init(icon: "⬇️",
                                                        title: "Sign in",
                                                        message: "Please log in with your existing account",
                                                        email: input?.email,
                                                        password: input?.password,
                                                        error: error))
        
        return req.templates.renderHtml(template)
    }
    
    func signInView(_ req: Request) async throws -> Response {
        return renderSignInView(req)
    }
    
    func signInAction(_ req: Request) async throws -> Response {
        /// the user is authenticated, we can store the user data inside the session too
        if let user = req.auth.get(AuthenticatedUser.self) {
            req.session.authenticate(user)
            return req.redirect(to: "/")
        }
        
        /// if the user credentials were wrong we render the form again with an error message
        let input = try req.content.decode(Input.self)
        return renderSignInView(req, input, "Invalid email or password.")
    }
    
}

了解action 方法内部的调用顺序非常重要。首先，UserCredentialsAuthenticator将完成其工作，如果输入正常，它将验证用户。到登录处理程序将被调用时， req.auth 属性应该包含一个 AuthenticatedUser 对象。我们可以通过调用 req.auth.get(AuthenticatedUser.self) 方法来检查它。这将返回一个可选的用户对象。
如果没有经过身份验证的用户，我们应该解码提交的值并使用登录表单响应错误消息，该错误消息将指示登录尝试不成功。如果用户存在，我们可以将用户保存到当前session storage中。这可以通过 req.session.authenticate 函数来完成。在此之后，我们可以将浏览器重定向到主屏幕，我们可以开始查看经过身份验证的用户的session对象。

现在我们可以通过登录表单对用户进行身份验证并将其保存到session storage中，我们需要一种从session storage中检索相同用户的方法。通过这种方式，我们将能确定用户之前是否已登录，并且我们可以在 Web 前端显示一些与用户相关的数据。
SessionAuthenticator 可以检查session cookie 的值并根据该标识符对用户进行身份验证。 Cookie 在 HTTP headers 中，authenticator 协议会自动解析请求中的session identifier。
UserSessionAuthenticator 应该检查数据库是否存在与给定 SessionID 关联的有效用户，如果存在则登录返回的用户。

/// FILE: Sources/App/Modules/User/Authenticators/UserSessionAuthenticator.swift
import Vapor
import Fluent

struct UserSessionAuthenticator: AsyncSessionAuthenticator {
    typealias User = AuthenticatedUser
    
    func authenticate(sessionID: User.SessionID, for request: Request) async throws {
        guard let user = try await UserAccountModel.find(sessionID, on: request.db) else {
            return
        }
        
        request.auth.login(AuthenticatedUser(id: user.id!, email: user.email))
    }
}

现在我们有了UserSessionAuthenticator，我们将把它添加为一个全局中间件，所以它会在我们注册的每个路由处理程序之前被调用。

/// FILE: Sources/App/Modules/User/UserModule.swift
import Vapor

struct UserModule: ModuleInterface {
    
    let router = UserRouter()
    
    func boot(_ app: Application) throws {
        app.migrations.add(UserMigrations.v1())
        app.migrations.add(UserMigrations.seed())
        
        app.middleware.use(UserSessionAuthenticator())
        
        try router.boot(routes: app.routes)
    }
}

我们应该更新index模板并检查是否有登录用和支持登录操作， 这可以通过 req.auth 属性来完成。

//...
Div {
    A("Home")
        .href("/")
        .class("selected", req.url.path == "/")
    A("Blog")
        .href("/blog/")
        .class("selected", req.url.path == "/blog/")
    A("About")
        .href("#")
        .onClick("javascript:about();")
    if req.auth.has(AuthenticatedUser.self) {
        A("Sign Out")
            .href("/sign-out/")
    } else {
        A("Sign In")
            .href("/sign-in/")
    }
}
.class("menu-items")
//...

实现登出端点很简单，我们只需要注销 AuthenticatedUser 并从Session storage存储中取消身份验证。 最后，我们可以在成功注销操作后简单地重定向回主页。

struct UserFrontendController {
    
    //...
    
    func signOut(req: Request) throws -> Response {
        req.auth.logout(AuthenticatedUser.self)
        req.session.unauthenticate(AuthenticatedUser.self)
        return req.redirect(to: "/")
    }
}

最后回到 UserRouter注册signOut 端点。

/// FILE: Sources/App/Modules/User/UserRouter.swift

import Vapor

struct UserRouter: RouteCollection {
    let frontendController = UserFrontendController()
    
    func boot(routes: RoutesBuilder) throws {
        routes.get("sign-in", use: frontendController.signInView)
        routes
            .grouped(UserCredentialsAuthenticator())
            .post("sign-in", use: frontendController.signInAction)
        
        routes.get("sign-out", use: frontendController.signOut)
    }
}

现在可以启动服务器并尝试使用预先创建的用户帐户登录。

登录.png

总结

在本篇文章中，我们搭建了新的用户模块，运用了身体验证的中间件，完成了一套帐号登录的流程。