雲端 Mac 上的 iOS 下載檔案格式檢核

雲端 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

接下來,依專案階段選擇方案

先查看機型、租用週期與連線方式,再決定是否租用。