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