【Alamofire源码解析】04 - MultipartFormData

多表单是什么回事？简单地说，多表单可以让我们一次性上传多个不同类型的文件给服务器。

MultipartFormData，这个类可以帮助我们创建多表单数据，然后通过请求体上传到服务器。目前有两种方式可以编码多表单数据：1）直接在内存中编码，非常高效，但是数据不能太大；2）先把数据写到一个文件中，然后再进行编码，适用于视频等文件。大文件一定要使用第二种方式，否则会造成内存不够用的。

一、辅助类型

1. EncodingCharacters

crlf回车换行。

struct EncodingCharacters {
    static let crlf = "\r\n"
}

2. BoundaryGenerator

因为多表单上传的是多种不同的数据，所以我们要在不同类型的文件之间添加一个边界。而这个边界生成器就是用来生成边界的。

struct BoundaryGenerator {
    // 边界类型，开始/内部/结束
    enum BoundaryType {
        case initial, encapsulated, final
    }

    // 随机边界，`arc4random()`返回`UInt32`，`%08x`表示将UInt32格式化成十六进制，
    // 并取前面8位，如果不够8位，用0代替
    static func randomBoundary() -> String {
        return String(format: "alamofire.boundary.%08x%08x", arc4random(), arc4random())
    }

    // 将String类型的边界，根据边界的类型转化成Data
    static func boundaryData(forBoundaryType boundaryType: BoundaryType, boundary: String) -> Data {
        let boundaryText: String

        switch boundaryType {
        case .initial:
            boundaryText = "--\(boundary)\(EncodingCharacters.crlf)"
        case .encapsulated:
            boundaryText = "\(EncodingCharacters.crlf)--\(boundary)\(EncodingCharacters.crlf)"
        case .final:
            boundaryText = "\(EncodingCharacters.crlf)--\(boundary)--\(EncodingCharacters.crlf)"
        }

        return boundaryText.data(using: String.Encoding.utf8, allowLossyConversion: false)!
    }
}

3. BodyPart

表示多表单内部的一个表单：

class BodyPart {
    let headers: HTTPHeaders // [String: String]
    let bodyStream: InputStream // 数据输入流
    let bodyContentLength: UInt64 // 此表单的数据大小
    var hasInitialBoundary = false // 是否包含开始边界
    var hasFinalBoundary = false // 是否包含结束边界

    init(headers: HTTPHeaders, bodyStream: InputStream, bodyContentLength: UInt64) {
        self.headers = headers
        self.bodyStream = bodyStream
        self.bodyContentLength = bodyContentLength
    }
}

二、MultipartFormData类

1. 属性

/// 包含边界的`Content-Type`
open lazy var contentType: String = "multipart/form-data; boundary=\(self.boundary)"

/// 整个多表单的数据大小，不包括边界
public var contentLength: UInt64 { return bodyParts.reduce(0) { $0 + $1.bodyContentLength } }

/// 多表单的边界
public let boundary: String

private var bodyParts: [BodyPart] // 整个多表单内部的表单数组
private var bodyPartError: AFError? // 表单拼接过程中可能出现的错误
private let streamBufferSize: Int // 流的缓存大小，默认是1024个字节，也就是1kb

这部分用到了一个高阶函数reduce，这是一个Swift内置的集合类型的函数，通过传入一个closure来合并这个集合。bodyParts.reduce(0) { $0 + $1.bodyContentLength }的意思是求bodyParts数组中每个bodyPart的bodyContentLength的和。他这个是一种简写的方式，其实完整的写法是：

public var contentLength: UInt64 {
    return bodyParts.reduce(0, { (sum, bodyPart) -> UInt64 in
        return sum + bodyPart.bodyContentLength
    })
}

上面这种方式就容易理解多了吧。不懂的话，我们再看一个简单的例子：

let numbers = [1, 2, 3, 4]
let numberSum = numbers.reduce(0, { sum, number in
    return sum + number
})
// numberSum == 10

上面这个例子是求numbers元素的和，本质上跟我们源码是一个意思。当numbers.reduce在运行的时候，最开始的求和结果是我们传入的0，然后用第一个元素1放到closure运行，这时sum是0，number就是第一个元素1，所以结果就是0 + 1；然后用第二个元素2放到closure运行，这时sum就是上次的运算结果1，number就是第二个元素2，结果就是1 + 2；以此类推，最后结果是10。

Swift还内置了很多类似这样的函数，例如map、flatMap、filter等等，大家可以自己去了解下。

2. 初始化方法

我们看到这个self.bodyParts = []，[]数组初始化的简写方式，代码更简洁，而不需要写成这样[BodyPart]()。在Swift开发过程中，在不失去代码可读性的情况下，代码能简洁尽量简洁。关于代码风格问题，我们可以使用Swiftlint来帮助我们，可以看看我写的这篇文章【iOS开发】Swift代码风格检查库 —— SwiftLint。

public init() {
    self.boundary = BoundaryGenerator.randomBoundary()
    self.bodyParts = []
    self.streamBufferSize = 1024
}

3. Body Parts

// MARK: - 这三个方法可以让我们通过传入数据类型，然后通过流的形式把数据拼接到多表单；
// 这三个方法大同小异，只是请求头不同

public func append(_ data: Data, withName name: String) {
    let headers = contentHeaders(withName: name)
    let stream = InputStream(data: data)
    let length = UInt64(data.count)

    append(stream, withLength: length, headers: headers)
}

public func append(_ data: Data, withName name: String, mimeType: String) {
    let headers = contentHeaders(withName: name, mimeType: mimeType)
    let stream = InputStream(data: data)
    let length = UInt64(data.count)

    append(stream, withLength: length, headers: headers)
}

public func append(_ data: Data, withName name: String, fileName: String, mimeType: String) {
    let headers = contentHeaders(withName: name, fileName: fileName, mimeType: mimeType)
    let stream = InputStream(data: data)
    let length = UInt64(data.count)

    append(stream, withLength: length, headers: headers)
}

// MARK: - 这两个方法可以让我们传文件的url，然后通过流的形式把文件拼接到多表单中

public func append(_ fileURL: URL, withName name: String) {
    let fileName = fileURL.lastPathComponent
    let pathExtension = fileURL.pathExtension

    if !fileName.isEmpty && !pathExtension.isEmpty {
        let mime = mimeType(forPathExtension: pathExtension)
        append(fileURL, withName: name, fileName: fileName, mimeType: mime)
    } else {
        setBodyPartError(withReason: .bodyPartFilenameInvalid(in: fileURL))
    }
}

public func append(_ fileURL: URL, withName name: String, fileName: String, mimeType: String) {
    // 其实这个headers，不应该放在这里定义，而是放在这个方法里最后一行代码上面；
    // 因为这个headers只有在最后一行代码那里才被用到，我们应该遵循一个原则：用到的时候才创建。
    let headers = contentHeaders(withName: name, fileName: fileName, mimeType: mimeType)

    //============================================================
    //                 检查 1 - 是否是文件路径？
    //============================================================

    guard fileURL.isFileURL else {
        setBodyPartError(withReason: .bodyPartURLInvalid(url: fileURL))
        return
    }

    //============================================================
    //                检查 2 - 文件路径能否访问?
    //============================================================

    do {
        let isReachable = try fileURL.checkPromisedItemIsReachable()
        guard isReachable else {
            setBodyPartError(withReason: .bodyPartFileNotReachable(at: fileURL))
            return
        }
    } catch {
        setBodyPartError(withReason: .bodyPartFileNotReachableWithError(atURL: fileURL, error: error))
        return
    }

    //============================================================
    //             检查 3 - 文件路径是否是一个文件夹？
    //============================================================

    var isDirectory: ObjCBool = false
    let path = fileURL.path

    guard FileManager.default.fileExists(atPath: path, isDirectory: &isDirectory) && !isDirectory.boolValue else {
        setBodyPartError(withReason: .bodyPartFileIsDirectory(at: fileURL))
        return
    }

    //============================================================
    //               检查 4 - 是否能获得文件的大小?
    //============================================================

    let bodyContentLength: UInt64

    do {
        guard let fileSize = try FileManager.default.attributesOfItem(atPath: path)[.size] as? NSNumber else {
            setBodyPartError(withReason: .bodyPartFileSizeNotAvailable(at: fileURL))
            return
        }

        bodyContentLength = fileSize.uint64Value
    }
    catch {
        setBodyPartError(withReason: .bodyPartFileSizeQueryFailedWithError(forURL: fileURL, error: error))
        return
    }

    //============================================================
    //          检查 5 - 是否能通过文件路径创建一个流?
    //============================================================

    guard let stream = InputStream(url: fileURL) else {
        setBodyPartError(withReason: .bodyPartInputStreamCreationFailed(for: fileURL))
        return
    }

    append(stream, withLength: bodyContentLength, headers: headers)
}


// MARK: - 这两个方法可以让我们传一个流，然后拼接到多表单中

public func append(
    _ stream: InputStream,
    withLength length: UInt64,
    name: String,
    fileName: String,
    mimeType: String)
{
    let headers = contentHeaders(withName: name, fileName: fileName, mimeType: mimeType)
    append(stream, withLength: length, headers: headers)
}

public func append(_ stream: InputStream, withLength length: UInt64, headers: HTTPHeaders) {
    let bodyPart = BodyPart(headers: headers, bodyStream: stream, bodyContentLength: length)
    bodyParts.append(bodyPart)
}

// MARK: - 数据编码

// 一次性把所有body parts编码到一个Data中，只适用于小文件；
// 对于大文件，应该使用 `writeEncodedData(to:)`
public func encode() throws -> Data {
}

// 把数据写到一个文件中，适用于大文件
public func writeEncodedData(to fileURL: URL) throws {
    if let bodyPartError = bodyPartError {
        throw bodyPartError
    }

    if FileManager.default.fileExists(atPath: fileURL.path) {
        throw AFError.multipartEncodingFailed(reason: .outputStreamFileAlreadyExists(at: fileURL))
    } else if !fileURL.isFileURL {
        throw AFError.multipartEncodingFailed(reason: .outputStreamURLInvalid(url: fileURL))
    }

    guard let outputStream = OutputStream(url: fileURL, append: false) else {
        throw AFError.multipartEncodingFailed(reason: .outputStreamCreationFailed(for: fileURL))
    }

    // 打开了一个流，用完之后必须关闭
    // 很好地利用了Swift的defer特性，把打开和关闭写在一起
    outputStream.open()
    defer { outputStream.close() }

    self.bodyParts.first?.hasInitialBoundary = true
    self.bodyParts.last?.hasFinalBoundary = true

    for bodyPart in self.bodyParts {
        try write(bodyPart, to: outputStream)
    }
}

// MARK: - 私有的Body Part相关方法（不对外暴露的方法，我们应该加上private）

// 编码Body Part
private func encode(_ bodyPart: BodyPart) throws -> Data {
    var encoded = Data()

    let initialData = bodyPart.hasInitialBoundary ? initialBoundaryData() : encapsulatedBoundaryData()
    encoded.append(initialData)

    let headerData = encodeHeaders(for: bodyPart)
    encoded.append(headerData)

    let bodyStreamData = try encodeBodyStream(for: bodyPart)
    encoded.append(bodyStreamData)

    if bodyPart.hasFinalBoundary {
        encoded.append(finalBoundaryData())
    }

    return encoded
}

// 编码Header
private func encodeHeaders(for bodyPart: BodyPart) -> Data {
    var headerText = ""

    for (key, value) in bodyPart.headers {
        headerText += "\(key): \(value)\(EncodingCharacters.crlf)"
    }
    headerText += EncodingCharacters.crlf

    return headerText.data(using: String.Encoding.utf8, allowLossyConversion: false)!
}

// 编码body stream
private func encodeBodyStream(for bodyPart: BodyPart) throws -> Data {
    let inputStream = bodyPart.bodyStream
    inputStream.open()
    defer { inputStream.close() }

    var encoded = Data()

    while inputStream.hasBytesAvailable {
        var buffer = [UInt8](repeating: 0, count: streamBufferSize)
        let bytesRead = inputStream.read(&buffer, maxLength: streamBufferSize)

        if let error = inputStream.streamError {
            throw AFError.multipartEncodingFailed(reason: .inputStreamReadFailed(error: error))
        }

        if bytesRead > 0 {
            encoded.append(buffer, count: bytesRead)
        } else {
            break
        }
    }

    return encoded
}

// MARK: - 把Body Part写入到OutputStream的相关方法

private func write(_ bodyPart: BodyPart, to outputStream: OutputStream) throws {
    try writeInitialBoundaryData(for: bodyPart, to: outputStream)
    try writeHeaderData(for: bodyPart, to: outputStream)
    try writeBodyStream(for: bodyPart, to: outputStream)
    try writeFinalBoundaryData(for: bodyPart, to: outputStream)
}

private func writeInitialBoundaryData(for bodyPart: BodyPart, to outputStream: OutputStream) throws {
    let initialData = bodyPart.hasInitialBoundary ? initialBoundaryData() : encapsulatedBoundaryData()
    return try write(initialData, to: outputStream)
}

private func writeHeaderData(for bodyPart: BodyPart, to outputStream: OutputStream) throws {
    let headerData = encodeHeaders(for: bodyPart)
    return try write(headerData, to: outputStream)
}

private func writeBodyStream(for bodyPart: BodyPart, to outputStream: OutputStream) throws {
    let inputStream = bodyPart.bodyStream

    inputStream.open()
    defer { inputStream.close() }

    while inputStream.hasBytesAvailable {
        var buffer = [UInt8](repeating: 0, count: streamBufferSize)
        let bytesRead = inputStream.read(&buffer, maxLength: streamBufferSize)

        if let streamError = inputStream.streamError {
            throw AFError.multipartEncodingFailed(reason: .inputStreamReadFailed(error: streamError))
        }

        if bytesRead > 0 {
            if buffer.count != bytesRead {
                buffer = Array(buffer[0.. 0, outputStream.hasSpaceAvailable {
        let bytesWritten = outputStream.write(buffer, maxLength: bytesToWrite)

        if let error = outputStream.streamError {
            throw AFError.multipartEncodingFailed(reason: .outputStreamWriteFailed(error: error))
        }

        bytesToWrite -= bytesWritten

        if bytesToWrite > 0 {
            buffer = Array(buffer[bytesWritten.. String {
    if
        let id = UTTypeCreatePreferredIdentifierForTag(kUTTagClassFilenameExtension, pathExtension as CFString, nil)?.takeRetainedValue(),
        let contentType = UTTypeCopyPreferredTagWithClass(id, kUTTagClassMIMEType)?.takeRetainedValue()
    {
        return contentType as String
    }

    return "application/octet-stream"
}

// MARK: - 生成Content Headers

private func contentHeaders(withName name: String, fileName: String? = nil, mimeType: String? = nil) -> [String: String] {
    var disposition = "form-data; name=\"\(name)\""
    if let fileName = fileName { disposition += "; filename=\"\(fileName)\"" }

    var headers = ["Content-Disposition": disposition]
    if let mimeType = mimeType { headers["Content-Type"] = mimeType }

    return headers
}

// MARK: - 把边界编码为数据

private func initialBoundaryData() -> Data {
    return BoundaryGenerator.boundaryData(forBoundaryType: .initial, boundary: boundary)
}

private func encapsulatedBoundaryData() -> Data {
    return BoundaryGenerator.boundaryData(forBoundaryType: .encapsulated, boundary: boundary)
}

private func finalBoundaryData() -> Data {
    return BoundaryGenerator.boundaryData(forBoundaryType: .final, boundary: boundary)
}

// MARK: - 设置bodyPartError

private func setBodyPartError(withReason reason: AFError.MultipartEncodingFailureReason) {
    guard bodyPartError == nil else { return }
    bodyPartError = AFError.multipartEncodingFailed(reason: reason)
}

在这一部分中，重点提一下Swift的defer特性。对于某些操作，需要放到一个作用域内最后面、并且必须要执行的代码，我们可以用defer。例如上面的例子，打开了一个流，用完之后必须关闭，所以用defer把关闭代码封装起来，并且跟打开操作放在一起，这样可以很有效的减少漏写的几率。不管后面的代码发生了什么，defer里面的代码总会在最后一行代码执行完成后执行。

有任何问题，欢迎大家留言！

欢迎加入我管理的Swift开发群：536353151，本群只讨论Swift相关内容。

原创文章，转载请注明出处。谢谢！