Vapor 框架学习记录（7）表单框架扩展

本篇将全部继续高级表单字段构建， 我们将创建一组常用的新字段类型。我们将学习如何基于抽象表单域类构建自定义表单域，我们会使用一个名为 Liquid 的全新 Swift package ，它是为 Vapor 制作的文件存储驱动程序库。 通过使用这个库，我们将能够创建一个用于上传图像的表单字段

隐藏表单

隐藏表单对用户来说是不可见的，但我们仍然可以使用它通过表单提交数据。 这是一个非常简单的字段类型，需要 HiddenFieldContext 对象中的key和可选的value

// FILE: Sources/App/Framework/Form/Fields/HiddenFieldContext.swift

public struct HiddenFieldContext {
    
    public let key: String
    public var value: String?
    
    public init(key: String, value: String? = nil) {
        self.key = key
        self.value = value
    }
}

对应的 HiddenFieldTemplate 也非常简单，只需要设置Input 的类型为** .hidden** 和使用context的值

///FILE: Sources/App/Framework/Form/Fields/HiddenFieldTemplate.swift


import Vapor
import SwiftHtml

public struct HiddenFieldTemplate: TemplateRepresentable {
    
    var context: HiddenFieldContext
    
    public init(_ context: HiddenFieldContext) {
        self.context = context
    }
    
    @TagBuilder
    public func render(_ req: Request) -> Tag {
        Input()
            .type(.hidden)
            .name(context.key)
            .value(context.value)
    }
}

第三个组件是实际的 HiddenField 类，我们会把接受字符串作为输入， HiddenFieldTemplate 作为输出的类型。 在 process 方法中，我们将输出的context设置为已处理的输入值

/// FILE: Sources/App/Framework/Form/Fields/HiddenField.swift


import Vapor

public final class HiddenField: AbstractFormField<String, HiddenFieldTemplate> {
    
    public convenience init(_ key: String) {
        self.init(key: key, input: "", output: .init(.init(key: key)))
    }
    
    public override func process(req: Request) async throws {
        try await super.process(req: req)
        output.context.value = input
    }
}

就是这样，我们已经准备好使用这个全新的input field， 这是一个很简单但可能以后很常用的工具。

文字表单

TextareaField 一般作为文本的输入表单，我们也将遵循相同的模式去搭建。 首先，我们应该为 TextareaFieldContext 对象创建一个结构体

/// FILE: Sources/App/Framework/Form/Fields/TextareaFieldContext.swift

public struct TextareaFieldContext {
    public let key: String
    public var label: LabelContext
    public var placeholder: String?
    public var value: String?
    public var error: String?
    
    public init(key: String,
                label: LabelContext? = nil,
                placeholder: String? = nil,
                value: String? = nil,
                error: String? = nil) {
        self.key = key
        self.label = label ?? .init(key: key)
        self.placeholder = placeholder
        self.value = value
        self.error = error
    }
}

textarea context与input context非常相似，但这里我们可以不需要 type 参数，因为 textarea 没有类型。 除了这个不同之外，其他一切都是一样的。
现在我们还应该为 textarea field 创建一个模板文件。

import Vapor
import SwiftHtml

public struct TextareaFieldTemplate: TemplateRepresentable {
    
    public var context: TextareaFieldContext
    
    public init(_ context: TextareaFieldContext) {
        self.context = context
    }
    
    @TagBuilder
    public func render(_ req: Request) -> Tag {
        LabelTemplate(context.label).render(req)
        
        Textarea(context.value)
            .placeholder(context.placeholder)
            .name(context.key)
        
        if let error = context.error {
            Span(error)
                .class("error")
        }
        
    }
    
}

就像在 InputFieldTemplate 中我们可以重用常见的 LabelTemplate 来呈现标签的详细信息，我们可以使用 Textarea 标签来配置我们的视图。 最后，如果有任何错误，我们会使用带有错误的Span 标签来显示它。
最后，我们还需要创建一个 TextareaField

//FILE: Sources/App/Framework/Form/Fields/TextareaField.swift

import Vapor

public final class TextareaField: AbstractFormField<String, TextareaFieldTemplate> {
    
    
    public convenience init(_ key: String) {
        self.init(key: key, input: "", output: .init(.init(key: key)))
    }
    
    public override func process(req: Request) async throws {
        try await super.process(req: req)
        output.context.value = input
    }
    
    public override func render(req: Request) -> TemplateRepresentable {
        output.context.error = error
        return super.render(req: req)
    }
    
}

处理完输入值后，我们可以用它更新output context，在渲染模板之前，我们也应该将当前错误值分配给output context。

选择表单

选择表单字段会有点复杂。这个字段使用具有多个可用选项。 每个选项都应该有一个key和一个label，因为这是一个经常重用的组件，我们将创建一个独立的 OptionContext 来表示它。

// FILE: Sources/App/Framework/Form/Templates/Contexts/OptionContext.swift

public struct OptionContext {
    
    public var key: String
    public var label: String
    
    public init(key: String, label: String) {
        self.key = key
        self.label = label
    }
}

这个OptionContext结构的好处是你可以定义额外的帮助方法来涵盖常见情况或选项值，例如是/否选择或一组数字。

public extension OptionContext {
    
    static func yesNo() -> [OptionContext] {
        ["yes", "no"].map { .init(key: $0, label: $0.capitalized) }
    }
    
    static func trueFalse() -> [OptionContext] {
        [true, false].map { .init(key: String($0), label: String($0).capitalized) }
    }
    
    static func numbers(_ numbers: [Int]) -> [OptionContext] {
        numbers.map { .init(key: String($0), label: String($0)) }
    }
}

SelectFieldContext 将包含一组选项和一个可能的值，如果选项键和值匹配，则可用于将选项标记为选中。 除了这两个属性之外，Context还将具有其他常规值，例如标签和错误。

// FILE: Sources/App/Framework/Form/Fields/SelectFieldContext.swift

public struct SelectFieldContext {

    public let key: String
    public var label: LabelContext
    public var options: [OptionContext]
    public var value: String?
    public var error: String?
    
    public init(key: String,
                label: LabelContext? = nil,
                options: [OptionContext] = [],
                value: String? = nil,
                error: String? = nil){
        self.key = key
        self.label = label ?? .init(key: key)
        self.options = options
        self.value = value
        self.error = error
    }
    
}

在 SelectFieldTemplate 中，我们需要遍历选项并将它们映射到选项标签中。 我们可以简单地将Option的value设置为item的key并使用Label作为Option的命名。 如果context value与item的key匹配，就设置为已选择状态。

//FILE: Sources/App/Framework/Form/Fields/SelectFieldTemplate.swift

import Vapor
import SwiftHtml

public struct SelectFieldTemplate: TemplateRepresentable {
    
    public var context: SelectFieldContext
    
    public init(_ context: SelectFieldContext) {
        self.context = context
    }
    
    @TagBuilder
    public func render(_ req: Request) -> Tag {
        
        LabelTemplate(context.label).render(req)
        
        Select {
            for item in context.options {
                Option(item.label)
                    .value(item.key)
                    .selected(context.value == item.key)
            }
        }
        .name(context.key)
            
        if let error = context.error {
            Span(error)
                .class("error")
        }
        
    }
    
}

最后一步是创建常规表单字段类，这个流程应该很熟悉。

// FILE: Sources/App/Framework/Form/Fields/SelectField.swift

import Vapor

public final class SelectField: AbstractFormField<String, SelectFieldTemplate> {
    
    public convenience init(_ key: String) {
        self.init(key: key, input: "", output: .init(.init(key: key)))
    }
    
    public override func process(req: Request) async throws {
        try await super.process(req: req)
        output.context.value = input
    }
    
    
    public override func render(req: Request) -> TemplateRepresentable {
        output.context.error = error
        return super.render(req: req)
    }
}

如你所见，创建新的表单字段是一个非常简单的过程。 每次你需要一个context、一个template和一个表单对象来连接context和template。

图片&文件上传

现在我们将处理一些更高级的表单字段， 我们将构建一个图像上传表单，但是为了将文件上传到服务器，我们需要一些额外的处理。 可以使用 Vapor 将文件从客户端移动到服务器，但有一种更好的方法来处理文件上传。

有一个名为Liquid 的文件存储组件，它可以使资源管理变得更加容易。 你可以把它想象成 Fluent，它是一个支持多个存储驱动程序的抽象。 你可以使用本地驱动程序将文件直接上传到您的服务器，但也可以使用 S3-driver将文件存储在 AWS S3 bucket中

Liquid 的文件通过一个唯一的密钥保存在存储中， 密钥通常是包含文件夹结构的相对文件路径，例如 foo/bar/baz.jpg。 这样，无论存储驱动程序如何，系统都可以解析文件的完整位置。

为了使用 Liquid，我们首先需要添加相关的Swift Package 依赖。

let package = Package(
    name: "a-Vapor-Blog",
    platforms: [
       .macOS(.v12)
    ],
    dependencies: [
        // 💧 A server-side Swift web framework.
        .package(url: "https://github.com/vapor/vapor.git", from: "4.0.0"),
        .package(url: "https://github.com/vapor/fluent.git", from: "4.0.0"),
        .package(url: "https://github.com/vapor/fluent-sqlite-driver", from: "4.1.0"),
        .package(url: "https://github.com/vapor/leaf.git", from: "4.0.0"),
        .package(url: "https://github.com/binarybirds/liquid", from: "1.3.0"),
        .package(url: "https://github.com/binarybirds/liquid-local-driver", from:
        "1.3.0"),
        .package(url: "https://github.com/binarybirds/swift-html", from: "1.2.0")
    ],
    targets: [
        .target(
            name: "App",
            dependencies: [
                .product(name: "Vapor", package: "vapor"),
                .product(name: "Fluent", package: "fluent"),
                .product(name: "FluentSQLiteDriver", package: "fluent-sqlite-driver"),
                .product(name: "Leaf", package: "leaf"),
                .product(name: "Liquid", package: "liquid"),
                .product(name: "LiquidLocalDriver", package: "liquid-local-driver"),
                .product(name: "SwiftHtml", package: "swift-html"),
                .product(name: "SwiftSvg", package: "swift-html")
            ],
            swiftSettings: [
                // Enable better optimizations when building in Release configuration. Despite the use of
                // the `.unsafeFlags` construct required by SwiftPM, this flag is recommended for Release
                // builds. See <https://github.com/swift-server/guides/blob/main/docs/building.md#building-for-production> for details.
                .unsafeFlags(["-cross-module-optimization"], .when(configuration: .release))
            ]
        ),
        .executableTarget(name: "Run", dependencies: [.target(name: "App")]),
        .testTarget(name: "AppTests", dependencies: [
            .target(name: "App"),
            .product(name: "XCTVapor", package: "vapor"),
        ])
    ]
)

这里我们添加好了Liquid，为了简单起见，我们将使用本地驱动程序。 publicUrl 参数是你的公开文件的base URL。 它将用于解析文件密钥。 publicPath 是公用文件夹的位置，workDirectory 将用作公用文件夹下的根目录来存储文件。

/// FILE: Sources/App/configure.swift

import Vapor
import Fluent
import FluentSQLiteDriver
import Liquid
import LiquidLocalDriver

// configures your application
public func configure(_ app: Application) throws {
    // uncomment to serve files from /Public folder
    app.middleware.use(FileMiddleware(publicDirectory: app.directory.publicDirectory))
    
    /// extend paths to always contain a trailing slash
    app.middleware.use(ExtendPathMiddleware())
    
    /// setup Fluent with a SQLite database under the Resources directory
    let dbPath = app.directory.resourcesDirectory + "db.sqlite"
    app.databases.use(.sqlite(.file(dbPath)), as: .sqlite)
    
    /// setup Liquid using the local file storage driver
    app.fileStorages.use(.local(publicUrl: "http://localhost:8080",
                                publicPath: app.directory.publicDirectory,
                                workDirectory: "assets"), as: .local)
    
    /// set the max file upload limit
    app.routes.defaultMaxBodySize = "10mb"
    
    /// setup Sessions
    app.sessions.use(.fluent)
    app.migrations.add(SessionRecord.migration)
    app.middleware.use(app.sessions.middleware)
    
    /// setup modules
    let modules: [ModuleInterface] = [
        WebModule(),
        BlogModule(),
        UserModule()
    ]
    for module in modules {
        try module.boot(app)
    }

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

为了能够收集上传的数据，我们还必须在App.Routes属性上设置DefaultMaxBodysize值。 目前来说，“ 10MB”的上限是足够的。 请注意，DefaultMaxBodysize是对全局的修改，实际上针对特别的路由对对应的限制才是合适的做法，这里我们为了方便就使用全局的属性修改。

在我们开始 InputField 开发之前，我们还有一些准备工作。 有时 Vapor 有一些奇怪的命名约定，文件类型的data value实际上代表一个ByteBuffer 对象，所以让我们快速为该属性创建一个别名方便理解。

/// FILE: Sources/App/Framework/Extensions/File+ByteBuffer.swift

import Vapor

public extension File {
    var byteBuffer: ByteBuffer { data }
}

为 ByteBuffer 类型创建一个可选的数据扩展也会让我们的使用更方便，这样我们就可以返回buffer包含的全部数据。

/// FILE: Sources/App/Framework/Extensions/ByteBuffer+Data.swift

import Vapor

public extension ByteBuffer {
    var data: Data? { getData(at: 0, length: readableBytes) }
}

那么，当我们尝试上传图片时，我们需要什么样的数据呢？

渲染表单的时候我们需要有原图，所以我们需要一些东西来表示原图的key。 我们为了确定能够上传文件，需要一个临时文件存储，我们可以在其中存储新的key和名称值。 有时我们不需要对应图像，为此我们可以引入一个简单的 Bool 标志来标记移除。

让我们创建一个表示此结构的新 FormImageData 类型，我们应该使其符合 Codable 协议，因为我们想要对其进行编码或解码

/// FILE: Sources/App/Framework/Form/FormImageData.swift

import Foundation

public struct FormImageData: Codable {
    
    public struct TemporaryFile: Codable {
        public let key: String
        public let name: String
        
        public init(key: String, name: String) {
            self.key = key
            self.name = name
        }
        
    }
    
    public var originalKey: String?
    public var temporaryFile: TemporaryFile?
    public var shouldRemove: Bool
    
    public init(originalKey: String? = nil,
                temporaryFile: TemporaryFile? = nil,
                shouldRemove: Bool = false) {
        
        self.originalKey = originalKey
        self.temporaryFile = temporaryFile
        self.shouldRemove = shouldRemove
    }
}

除了常规的key、label和error之外，我们将使用这个 FormImageData 作为 ImageFieldContext 结构中的数据对象。 我们还将使用 previewUrl 和 accept 属性来设置模板。

/// FILE: Sources/App/Framework/Form/Fields/ImageFieldContext.swift

public struct ImageFieldContext {
    
    public let key: String
    public var label: LabelContext
    public var data: FormImageData
    public var previewUrl: String?
    public var accept: String?
    public var error: String?
    
    public init(key: String,
                label: LabelContext? = nil,
                data: FormImageData = .init(),
                previewUrl: String? = nil,
                accept: String? = nil,
                error: String? = nil) {
        
        self.key = key
        self.label = label ?? .init(key: key)
        self.data = data
        self.previewUrl = previewUrl
        self.accept = accept
        self.error = error
        
    }
}

ImageFieldTemplate 会比之前的模块更复杂。在渲染模板的第一部分，如果有 previewUrl 值，我们将尝试将 previewUrl 显示为图像。

接下来我们像往常一样显示label，并使用context中的key和accept value添加一个文件类型的input field。使用 accept 值可以限制用户在上传过程中可以选择的文件类型，该值应该是有效的媒体类型，例如 image/png

当提交过程中表单出现错误时，我们需要临时文件。如果在验证过程中出现问题，如果我们不重新提交文件key和name作为输入值，我们可能会丢失上传的图片。这样即使其他字段不正确，我们也不会丢失上传的图像文件，我们只需将临时文件移动到其最终位置。这与我们可能会提交原始密钥（如果有的话）的原因相同。

最后一个输入字段指示用户是否要删除上传的图像。

/// FILE: Sources/App/Framework/Form/Fields/ImageFieldTemplate.swift


import Vapor
import SwiftHtml

public struct ImageFieldTemplate: TemplateRepresentable {
 
    
    public var context: ImageFieldContext
    
    
    public init(_ context: ImageFieldContext) {
        self.context = context
    }
    
    @TagBuilder
    public func render(_ req: Request) -> Tag {
        
        if let url = context.previewUrl {
            Img(src: url, alt: context.key)
        }
        
        LabelTemplate(context.label).render(req)
        
        Input()
            .type(.file)
            .key(context.key)
            .class("field")
            .accept(context.accept)
        
        if let temporaryFile = context.data.temporaryFile {
            
            Input()
                .key(context.key + "TemporaryFileKey")
                .value(temporaryFile.key)
                .type(.hidden)
            
            Input()
                .key(context.key + "TemporaryFileName")
                .value(temporaryFile.name)
                .type(.hidden)
        }
        
        if let key = context.data.originalKey {
            Input()
                .key(context.key + "OriginalKey")
                .value(key)
                .type(.hidden)
        }
        
        if !context.label.required {
            Input()
                .key(context.key + "ShouldRemove")
                .value(String(true))
                .type(.checkbox)
                .checked(context.data.shouldRemove)
            
            Label("Remove")
                .for(context.key + "Remove")
        }
        
        if let error = context.error {
            
            Span(error)
                .class("error")
            
        }
        
    }
}

现在我们可以渲染image field，我们仍然需要表单字段子类来处理它并将文件上传到服务器。 在我们进入该部分之前，我们将再定义一个辅助对象，它将作为抽象表单字段的输入类型。

FormImageInput 结构将有一个key、一个file value，它将表示上传的文件数据和一个FormImageData 类型的数据对象。

/// FILE: Sources/App/Framework/Form/FormImageInput.swift

import Vapor

public struct FormImageInput: Codable {
    
    public var key: String
    public var file: File?
    public var data: FormImageData
    
    public init(key: String, file: File? = nil, data: FormImageData? = nil) {
        self.key = key
        self.file = file
        self.data = data ?? .init()
    }
}

现在我们可以在创建 ImageField 时使用 FormImageInput 作为输入值，使用 ImageFieldTemplate 作为输出类型。 我们将使用一个公共 imageKey 变量来存储当前密钥，并使其也可供其他人访问。 path 变量将是图像键的前缀，它只是我们保存上传文件的目录路径。

process函数将比以前用于其他字段更有趣。 首先，我们尝试根据我们在template文件中使用的key对Input进行解码。 在我们拥有完整的输入数据后，我们检查是否应该删除文件，并根据其他输入值执行相应的操作。

如果文件应该被删除并且有一个原始密钥，这意味着我们必须使用 req.fs.delete(key:) 方法删除原始文件。

如果有用户提交的某种图片数据，我们首先要检查临时文件，然后根据key删除，因为我们要先将新数据上传到服务器，并作为临时文件存储。

您可以通过调用 try await req.fs.upload(key: key, data: data) 方法使用 Liquid 上传文件。 默认情况下，它会返回上传文件的完整 URL，但我们现在不关心这个。

作为最后一步，我们可以使用当前输入数据更新out context数据，我们就完成了。

/// FILE: Sources/App/Framework/Form/Fields/ImageField.swift

import Vapor

public final class ImageField: AbstractFormField<FormImageInput, ImageFieldTemplate> {
    
    public var imageKey: String? {
        didSet {
            output.context.data.originalKey = imageKey
        }
    }
    
    public var path: String
    
    public init(_ key: String, path: String) {
        self.path = path
        super.init(key: key, input: .init(key: key), output: .init(.init(key: key)))
    }
    
    public override func process(req: Request) async throws {
        /// process input
        input.file = try? req.content.get(File.self, at: key)
        input.data.originalKey = try? req.content.get(String.self, at: key + "OriginalKey")
        
        if let temporaryFileKey = try? req.content.get(String.self, at: key + "TemporaryFileKey"), let temporaryFileName = try? req.content.get(String.self, at: key + "TemporaryFileName") {
            input.data.temporaryFile = .init(key: temporaryFileKey, name: temporaryFileName)
            
        }
        
        input.data.shouldRemove = (try? req.content.get(Bool.self, at: key + "ShouldRemove")) ?? false
        
        /// remove & upload file
        if input.data.shouldRemove {
            if let originalKey = input.data.originalKey {
                try? await req.fs.delete(key: originalKey)
            }
        }
        else if let file = input.file, let data = file.byteBuffer.data, !data.isEmpty {
            if let tmpKey = input.data.temporaryFile?.key {
                try? await req.fs.delete(key: tmpKey)
            }
            
            let key = "tmp/\(UUID().uuidString).tmp"
            
            _ = try await req.fs.upload(key: key, data: data)
            
            /// update the temporary image
            
            input.data.temporaryFile = .init(key: key, name: file.filename)
            
            
        }
        
        /// update output values
        output.context.data = input.data
    }
    
    public override func write(req: Request) async throws {
        
        imageKey = input.data.originalKey
        
        if input.data.shouldRemove {
            if let key = input.data.originalKey {
                try? await req.fs.delete(key: key)
            }
            imageKey = nil
        }
        else if let file = input.data.temporaryFile {
            
            var newKey = path + "/" + file.name
            if await req.fs.exists(key: newKey) {
                let formatter = DateFormatter()
                formatter.dateFormat="y-MM-dd-HH-mm-ss-"
                let prefix = formatter.string(from: .init())
                newKey = path + "/" + prefix + file.name
            }
            
            _ = try await req.fs.move(key: file.key, to: newKey)
            input.data.temporaryFile = nil
            if let key = input.data.originalKey {
                try? await req.fs.delete(key: key)
            }
            imageKey = newKey
        }
        
        try await super.write(req: req)
        
    }
    
    public override func render(req: Request) -> TemplateRepresentable {
        output.context.error = error
        return super.render(req: req)
    }
    
}

write 函数调用发生在验证步骤成功后，因此现在可以安全地将上传的文件移动到最终目的地。首先，我们必须检查是否有删除操作，如果我们必须执行此操作，我们只需根据原始密钥删除文件。

否则我们可以确定当前上传的文件已经作为临时文件存储在服务器上，我们可以将其移动到 assets 目录。如果已经存在具有给定key的文件，我们将在文件名前加上当前时间戳。

然后我们可以使用 req.fs.move 将临时文件移动到 assets 目录，如果存在则删除原始密钥，因为我们刚刚用新密钥替换了它。

我们将最终密钥存储在 imageKey 属性中，并调用 super.write(req:) 来处理进一步的操作。

ImageField("image", path: "blog/post") .read {
if let key = model.imageKey {
$1.output.context.previewUrl = $0.fs.resolve(key: key)
}
($1 as! ImageField).imageKey = model.imageKey }
.write { model.imageKey = ($1 as! ImageField).imageKey }

类似上面这样简单的代码，我们就可以使用ImageField完成图片上传。

最后

本章主要介绍新的表单字段。 我们为提交不可见的key value创建了一个隐藏表单字段，并为多行的用户输入添加了一个 textarea 字段。 选择表单字段是一种更复杂的类型，能够从选项数组中选择给定值。 最后，我们在项目中添加了 Liquid 文件存储驱动程序，这使我们可以轻松地将文件上传到服务器。 通过利用 Liquid，我们能够定义一个全新的 ImageField，它将帮助我们上传图像文件，在我们不再需要它们时替换或删除它们。 在下一篇中，我们将利用这些新的组件，并为我们的博客模块创建一个基本的 CMS 界面。