云端 Mac 上的 iOS 下载文件类型验收

云端 Mac 上的 iOS 下载文件类型验收

iOS 下载接口返回成功,预览页却打不开附件:有时拿到的是登录失效后的错误页,有时服务器把所有内容都标成通用二进制,还有时文件只下载了一半。在云端 Mac 上复现这类问题,不必先接真实服务。先把“声明了什么、实际像什么、能否完整解析”拆开,用固定样本建立三层验收,再接回下载流程。

先定义允许接收的格式

假设附件入口只接收 PNG、JPEG 和 PDF。规则应由业务白名单决定,而不是根据文件名猜测。文件名可以显示给用户,但不能决定交给哪个解析器,更不能直接拼成落盘路径。

验收顺序是:确认 HTTP 状态符合接口契约,限制实际接收字节数,核对响应 MIME 与文件头,最后执行格式专属解析。Content-Length 只能作为提前拒绝的依据之一,缺失或偏小都不能替代累计字节上限。

文件头匹配只说明“像这种格式”,不是完整性证明,更不是安全证明。一个只有 PNG 签名的文件仍然无法显示。

如果接口明确返回通用二进制,可以为该入口配置例外;不要让所有下载都获得同样的宽松待遇。以下实现采用严格模式,缺少 MIME 或声明冲突均拒绝。

用纯函数隔离类型判定

在远程 macOS 终端中新建 type-check.swift,保存以下内容。函数只接收头部数据与 MIME,不触网、不访问用户目录,便于随后迁入应用测试目标。代码中的样本只验证分类规则,不冒充有效图片或文档。

import Foundation

enum FileKind: String {
    case png, jpeg, pdf

    var mime: String {
        switch self {
        case .png: return "image/png"
        case .jpeg: return "image/jpeg"
        case .pdf: return "application/pdf"
        }
    }
}

enum TypeFailure: Error {
    case unknownHeader
    case missingMIME
    case conflictingMIME
}

func classify(
    prefix: Data,
    declaredMIME: String?
) throws -> FileKind {
    let bytes = Array(prefix.prefix(8))
    let kind: FileKind

    if bytes.starts(with: [137, 80, 78, 71, 13, 10, 26, 10]) {
        kind = .png
    } else if bytes.starts(with: [255, 216, 255]) {
        kind = .jpeg
    } else if bytes.starts(with: Array("%PDF-".utf8)) {
        kind = .pdf
    } else {
        throw TypeFailure.unknownHeader
    }

    guard let declaredMIME else {
        throw TypeFailure.missingMIME
    }

    let mime = declaredMIME
        .split(separator: ";", omittingEmptySubsequences: false)[0]
        .trimmingCharacters(in: .whitespacesAndNewlines)
        .lowercased()

    guard mime == kind.mime else {
        throw TypeFailure.conflictingMIME
    }
    return kind
}

struct Fixture {
    let head: [UInt8]
    let mime: String?
    let expected: FileKind?
}

let fixtures: [Fixture] = [
    .init(
        head: [137, 80, 78, 71, 13, 10, 26, 10],
        mime: "IMAGE/PNG; charset=binary",
        expected: .png
    ),
    .init(head: [255, 216, 255], mime: "image/jpeg", expected: .jpeg),
    .init(
        head: Array("%PDF-1.7".utf8),
        mime: "application/pdf",
        expected: .pdf
    ),
    .init(
        head: Array("<html>error".utf8),
        mime: "application/pdf",
        expected: nil
    ),
    .init(head: [137, 80, 78], mime: "image/png", expected: nil),
    .init(head: [255, 216, 255], mime: "image/png", expected: nil),
    .init(head: [255, 216, 255], mime: nil, expected: nil)
]

for (index, fixture) in fixtures.enumerated() {
    let actual = try? classify(
        prefix: Data(fixture.head),
        declaredMIME: fixture.mime
    )
    guard actual == fixture.expected else {
        fatalError("Fixture mismatch at index \(index)")
    }
}

执行 xcrun swift type-check.swift,全部匹配时安静退出,断言失败则返回非零。这里直接使用头部字符串是为了覆盖大小写和参数;应用若读取的是已规范化 MIME,也应保留原始响应头供问题定位,但不要记录鉴权字段。

接入下载时不要整文件读入内存

使用下载任务时,先检查任务错误、响应状态及临时文件是否存在,再用 FileHandle 读取最多八字节传给判定函数。句柄用 defer 关闭。不要为了读取签名而执行整文件的 Data(contentsOf:),大附件会让一次简单检查变成内存峰值。

流式接收时必须累计前八字节,不能假设第一次回调就包含完整签名;回调分片与文件格式边界没有关系。收到的数据不足以分类时继续等待,直到八字节齐全或传输结束,再给出结论。

下载任务提供的临时文件需要及时移动到应用控制的暂存目录。生成内部文件名,校验通过后再发布到正式位置;任何一步失败都清理暂存文件。用户给定的名称只能作为经过处理的展示字段。

为完整解析补上第二组样本

类型识别通过后,图片还要通过 ImageIO 创建图像源并实际生成图像。仅能读取尺寸或创建图像源,并不代表后续解码一定成功。先限制宽高、总像素和帧数,再触发所需帧的解码,避免小压缩文件展开成巨大内存对象。

PDF 可用 PDFKit 尝试创建文档,检查页数、加密状态及需要访问的页面。若业务要生成预览,应实际渲染目标页;文档对象创建成功并不说明每页都能正确显示。

准备真实的有效文件,以及只保留文件头、截断尾部、修改中间字节的副本。截断样本不一定全部被底层解析器拒绝:有些解析器能够容错,因此测试应围绕“能否完成应用要求的操作”断言,而不是假设任何字节变化都必须失败。

把失败原因变成可定位的结果

接入工程测试目标后,分别报告传输失败、格式未知、声明冲突、超出配额和解析失败。不要全部压成“文件损坏”,否则后端 MIME 配置错误与客户端解码问题会混在一起。

每次回归保留样本编号、实际字节数、规范化 MIME、候选类型及处理阶段。样本优先使用人工生成的无敏感内容文件;失败附件若含业务数据,不应随测试报告自动上传。

最后检查三件事:错误页不会进入预览器,截断样本不会被当成完整性已验证的文件,失败路径没有留下正式附件。云端 Mac 负责运行固定样本和模拟器流程;真机上的大文件内存表现仍需单独验收。两者分开记录,才能知道这一道门禁究竟证明了什么。

常见问题

响应 MIME 与文件头不一致时应该自动改类型吗?

默认拒绝并记录冲突原因。只有业务明确允许通用二进制响应时,才为特定入口建立例外,仍须通过文件头检查与完整解析。

文件头匹配能证明文件没有损坏吗?

不能。文件头只能识别候选类型;截断或损坏文件仍可能匹配。图片需要完整解码检查,PDF 需要解析及业务要求的页面验收。

让自己的工程决定租哪台 Mac

如果需要原生编译与模拟器调试,适合租一台 Apple Silicon 独享物理 Mac 验证;如果长期全职开发且常驻一地,买机也值得比较。按天验证更灵活,持续使用再考虑月付或季付。

租用远程 Mac

下一步,按项目阶段选方案

先看机型、周期与接入方式,再决定是否租用。