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