這篇文章我不想只講“上傳功能怎么做出來”而是把我這次做多附件上傳中心時真正踩到的工程邊界梳理清楚為什么單個上傳接口一旦遇到后臺切換、網(wǎng)絡抖動、超大文件就會很快失控以及我最后是怎么把斷點續(xù)傳、失敗重試、并發(fā)隊列和后臺調度收成一套能上線的結構。一、最開始的問題不是上傳失敗而是上傳邏輯太“直”了我最早做這個頁面時想法其實特別直接用戶選文件點上傳Request Kit 發(fā)請求成功了就改狀態(tài)失敗了就彈提示。剛跑 Demo 的時候這套邏輯看起來沒什么問題?？梢坏┌褕鼍皬摹吧蟼饕粋€ 3MB 圖片”換成“連續(xù)上傳 5 個附件其中還混著 1GB 的視頻、幾十 MB 的文檔、網(wǎng)絡中途斷一下、用戶切到后臺再回來”問題馬上就全出來了文件一多多個任務互相搶占某個大文件失敗以后整個隊列狀態(tài)會被拖亂頁面退出再回來任務狀態(tài)不連續(xù)網(wǎng)絡恢復以后不知道該從頭傳還是從上次分片繼續(xù)某個任務一直失敗會不會把剩下所有任務都卡住用戶看到“失敗”兩個字但根本不知道失敗在哪一段。也就是說表面看是“上傳中心”本質上已經(jīng)不是一個按鈕功能了而是一套任務調度系統(tǒng)。二、我后來先把任務拆成了“狀態(tài)機”頁面才開始好維護如果上傳任務只有“成功”和“失敗”兩個狀態(tài)這種功能幾乎一定會越寫越亂。因為真實業(yè)務里一個上傳任務至少會經(jīng)歷這些階段WAITING已經(jīng)入隊等待執(zhí)行UPLOADING正在上傳PAUSED手動暫?；蚓W(wǎng)絡暫時不可用RETRYING發(fā)生異常進入自動重試FAILED超過重試上限正式失敗SUCCESS上傳完成。我后面把每個文件都抽成一條UploadTask里面除了文件信息還會記錄當前狀態(tài)當前進度已上傳分片數(shù)失敗次數(shù)最大重試次數(shù)最近錯誤信息本地斷點位置。這樣做最大的變化是頁面不再憑感覺拼 UI而是完全跟著任務狀態(tài)走。最基礎的一版任務模型我最后收成了下面這種結構exportenumUploadStatus{WAITINGWAITING,UPLOADINGUPLOADING,PAUSEDPAUSED,RETRYINGRETRYING,FAILEDFAILED,SUCCESSSUCCESS}exportinterfaceUploadTask{id:stringfilePath:stringfileName:stringfileSize:numberchunkSize:numberuploadedChunk:numbertotalChunk:numberprogress:numberretryCount:numbermaxRetry:numberstatus:UploadStatus errorMessage?:string}這段代碼看起來只是多了幾個字段但它解決的是一個更底層的問題上傳任務終于有了統(tǒng)一的生命周期。三、真正讓我穩(wěn)下來的不是接口而是“上傳隊列”一開始我也試過最省事的做法用戶選了幾個文件就起幾個并發(fā)上傳。結果非?？靻栴}就來了。大文件占住帶寬小文件一直排隊網(wǎng)絡一差多個任務同時重試頁面上明明只壞了一項但用戶看到的卻像全部都卡住了。后來我就不再讓頁面直接發(fā)請求而是加了一層UploadManager。這層只做三件事維護任務隊列控制最大并發(fā)數(shù)統(tǒng)一管理重試和狀態(tài)回調。也就是說頁面負責“發(fā)起上傳”真正執(zhí)行上傳的是隊列管理器。我最后保留的核心邏輯大概是這樣classUploadManager{privatequeue:UploadTask[][]privaterunningCount:number0privatemaxConcurrent:number3addTask(task:UploadTask){this.queue.push(task)this.schedule()}privateschedule(){while(this.runningCountthis.maxConcurrent){constnextTaskthis.queue.find(itemitem.statusUploadStatus.WAITING)if(!nextTask){break}this.runningCount1nextTask.statusUploadStatus.UPLOADINGthis.uploadTask(nextTask).finally((){this.runningCount-1this.schedule()})}}}這里最關鍵的不是while這幾行而是思路變了上傳不是頁面事件而是隊列事件頁面點擊“上傳”只是在往隊列里塞任務調度權在管理器手里不在按鈕手里。這一點想通以后很多以前很亂的問題一下就有了歸宿。四、斷點續(xù)傳不是一個按鈕而是一段“已上傳分片”的記錄真正讓我覺得這個功能像樣起來的是把斷點續(xù)傳補完整。用戶看到的只是“繼續(xù)上傳”四個字但工程上它背后至少要回答三件事已經(jīng)傳到哪個分片了下次恢復時從哪里接著走失敗后重試是重試當前分片還是重試整個文件。我最后沒有做整文件一次性上傳而是把大文件按分片處理。每個分片完成以后立即更新uploadedChunkprogresslastCallbackTime本地持久化斷點位置這樣做的好處非常直接如果第 385 個分片超時恢復時就不必從第 1 個分片重新開始而是從384的下一個位置繼續(xù)。這也是為什么在上傳詳情頁里我刻意把“總分片數(shù)”“斷點位置”“重試次數(shù)”“最后回調時間”都顯式展示出來。你看這張圖其實就是在講這套鏈路的幾個關鍵證據(jù)紅圈標出的“總分片數(shù)”和“斷點位置”告訴我們恢復到底從哪一段開始“失敗原因”不是一句泛泛提示而是具體到網(wǎng)絡超時“重試次數(shù)”和“最后回調時間”能讓排查不再停留在猜測層面。很多上傳功能看起來也有失敗頁但如果沒有這些字段開發(fā)者很難判斷問題到底卡在哪一步。五、自動重試真正難的不是“重試一下”而是別把隊列拖崩自動重試聽起來像一句話真正落地時卻很講分寸。如果所有失敗都立刻重試網(wǎng)絡一抖整個隊列會同時重試某個必然失敗的任務會反復耗資源用戶會覺得頁面一直在轉但又不知道什么時候結束。所以我最后給重試定了三條規(guī)則只對可恢復錯誤重試例如網(wǎng)絡超時、瞬時連接失敗限制最大重試次數(shù)超過上限進入FAILED重試前做延遲退避避免多個任務瞬間同時重試。比如第 1 次重試等 2 秒第 2 次等 4 秒第 3 次等 8 秒。這樣一來網(wǎng)絡剛剛恢復時隊列不會一下子全部撞上去。頁面上我也把這件事講清楚了失敗任務不是徹底結束而是會先進入“可重試”的狀態(tài)再決定是系統(tǒng)自動兜底還是用戶手動觸發(fā)。這張圖里紅色標注圈出來的點其實剛好就是用戶最關心、開發(fā)者也最該先排查的幾個位置“并發(fā) 3” 對應的是隊列調度能力“重試”按鈕對應失敗任務的人工接管入口“繼續(xù)上傳”對應斷點續(xù)傳能力。讀者看一眼就能理解這不是一個簡單的文件列表而是一套帶調度、帶恢復、帶失敗兜底的上傳中心。六、后臺切走以后還能繼續(xù)是因為我把后臺任務和上傳鏈路接在了一起多附件上傳真正的考題很多時候不是前臺而是后臺。因為用戶上傳視頻、壓縮包這類大文件時幾乎不可能一直盯著頁面看。他切出去回消息、查文檔、鎖屏都是很正常的操作。如果這時候上傳能力完全依賴當前頁面生命周期用戶體驗一定很差。所以我后面又補上了Background Tasks Kit的調度邏輯讓上傳任務在應用退到后臺后仍然能維持可控執(zhí)行。在工程結構上我沒有把后臺任務另寫成一套上傳邏輯而是只讓后臺能力負責“?；钆c調度”真正的任務狀態(tài)還是統(tǒng)一落在UploadManager上。也就是說前臺和后臺不是兩套上傳系統(tǒng)它們共享同一套任務隊列后臺只是改變任務執(zhí)行時機而不改變任務模型。這個收法很重要。否則很容易出現(xiàn)前臺一個狀態(tài)、后臺一個狀態(tài)、頁面回來又對不上的情況。七、整個工程為什么能穩(wěn)下來我覺得關鍵不是某個 API而是“證據(jù)可見”后面我回頭看這次實戰(zhàn)真正讓我滿意的不是“上傳成功率提高了”而是整個系統(tǒng)開始有了可解釋性。比如在 DevEco 的開發(fā)視角里我會同時看三塊東西左邊項目結構里頁面、管理器、后臺任務是不是分層清楚中間代碼里隊列狀態(tài)、重試入口、后臺調度是不是收口在少數(shù)幾個方法里底部日志里任務回調、重試日志、隊列狀態(tài)是不是連續(xù)可追蹤。這張圖對我來說就很像這次工程的縮影紅色箭頭標注“隊列狀態(tài)”說明上傳中心不再是散點邏輯“重試入口”說明錯誤恢復是有結構的“后臺任務調度”說明頁面生命周期之外任務還能被系統(tǒng)托住底部日志把“回調—重試—隊列狀態(tài)”串成了一條完整證據(jù)鏈。這也是我這次最強烈的體會上傳功能一旦進入工程化階段最值錢的不是單次成功而是狀態(tài)可見、過程可追。八、本文小記如果讓我用一句話總結這次實戰(zhàn)我會寫成多附件上傳中心的難點不在“傳”而在“調度”。真正決定體驗的從來不是那個“選擇文件”按鈕而是隊列是不是穩(wěn)分片是不是能續(xù)失敗是不是能判重試是不是有邊界后臺是不是還能接著跑。對我自己來說這次做完以后有幾個判斷基本算是固定下來了任務一定要先抽成狀態(tài)機上傳一定要收進隊列管理器斷點續(xù)傳一定要落到可持久化的分片進度上自動重試一定要有錯誤類型和次數(shù)邊界后臺調度一定要和前臺任務共用一套狀態(tài)來源。如果你現(xiàn)在也在做 HarmonyOS 的文件上傳類功能我的建議不是“先把上傳接口接上”而是先想清楚你的上傳中心究竟只是一個頁面還是一套任務系統(tǒng)。想清楚這一點后面的工程結構會完全不一樣。