HarmonyOS 启动任务编排实战：依赖、并发、超时与失败兜底

HarmonyOS 启动任务编排实战：依赖、并发、超时与失败兜底

启动慢不一定是某个任务慢，也可能是任务编排混乱：无依赖的任务被串行执行，非首屏任务挡住首屏，远程配置超时后没有降级，某个初始化失败就让首页空白。随着业务增长，启动阶段如果没有统一编排，很快会变成一堆散落在AbilityStage、UIAbility和首页里的初始化代码。

本文围绕 HarmonyOS 应用启动任务编排，设计一套轻量任务 DAG：任务声明依赖、执行器并发调度、超时后降级、失败后走兜底。目标是让启动链路可读、可测、可维护。

1. 启动编排先解决四个问题

2. 资料定位与适用范围

建议从华为开发者文档中心检索“启动性能”“AppStartup”“Launch”“Stage 模型生命周期”等资料：

• 华为开发者文档中心：https://developer.huawei.com/consumer/cn/doc/
• HarmonyOS Guides：https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/
• 本文重点核验启动任务依赖、超时和降级边界，不把任务并发当成唯一优化手段。

本文示例边界：

3. 定义启动任务

每个启动任务必须说明 id、依赖、是否关键、超时时间。

// common/startup/StartupTask.etsexporttypeStartupTaskResult='success'|'failed'|'timeout'|'skipped';exportinterfaceStartupTask{id:string;dependsOn:string[];critical:boolean;timeoutMs:number;run:()=>Promise<void>;fallback?:()=>Promise<void>;}exportinterfaceStartupTaskRecord{id:string;result:StartupTaskResult;costMs:number;note:string;}

代码解释：

4. 构建任务图

任务图负责判断哪些任务可以执行，哪些任务还在等依赖。

// common/startup/TaskGraph.etsimport{StartupTask}from'./StartupTask';exportclassTaskGraph{privatetasks:StartupTask[];privatedone:Set<string>=newSet();constructor(tasks:StartupTask[]){this.tasks=tasks;}ready():StartupTask[]{returnthis.tasks.filter(task=>{if(this.done.has(task.id)){returnfalse;}returntask.dependsOn.every(id=>this.done.has(id));});}markDone(id:string):void{this.done.add(id);}finished():boolean{returnthis.done.size===this.tasks.length;}}

这段图结构只处理依赖，不执行任务。它防止执行器里一边跑任务一边临时猜依赖关系。

5. 执行器处理超时和记录

启动任务必须有超时保护，尤其是远程配置、账号校验这类可能被网络影响的任务。

// common/startup/TaskExecutor.etsimport{StartupTask,StartupTaskRecord}from'./StartupTask';exportclassTaskExecutor{staticasyncexecute(task:StartupTask):Promise<StartupTaskRecord>{conststarted=Date.now();try{awaitPromise.race([task.run(),TaskExecutor.timeout(task.timeoutMs)]);return{id:task.id,result:'success',costMs:Date.now()-started,note:''};}catch(err){if(task.fallback!==undefined){awaittask.fallback();}return{id:task.id,result:'failed',costMs:Date.now()-started,note:`${err}`};}}privatestatictimeout(ms:number):Promise<void>{returnnewPromise((_,reject)=>{setTimeout(()=>reject(newError(`timeout${ms}ms`)),ms);});}}

这段执行器把超时和 fallback 放在同一处。它防止某个启动任务无限等待，导致首屏一直不出现。

6. 编排器并发执行 ready 任务

无依赖的任务可以并发执行，有依赖的任务等待前置完成。

// common/startup/StartupOrchestrator.etsimport{StartupTask,StartupTaskRecord}from'./StartupTask';import{TaskGraph}from'./TaskGraph';import{TaskExecutor}from'./TaskExecutor';exportclassStartupOrchestrator{staticasyncrun(tasks:StartupTask[]):Promise<StartupTaskRecord[]>{constgraph=newTaskGraph(tasks);constrecords:StartupTaskRecord[]=[];while(!graph.finished()){constreadyTasks=graph.ready();if(readyTasks.length===0){break;}constbatch=awaitPromise.all(readyTasks.map(task=>TaskExecutor.execute(task)));batch.forEach(record=>{records.push(record);graph.markDone(record.id);});}returnrecords;}}

这段编排器的重点是“批次并发”。它不会把所有任务强行串行，也不会让未满足依赖的任务提前执行。

7. 注册真实启动任务

下面是一个典型任务列表：本地配置和缓存预热可以先跑，远程配置失败时降级，非首屏任务不放关键路径。

// common/startup/AppStartupTasks.etsimport{StartupTask}from'./StartupTask';exportconstappStartupTasks:StartupTask[]=[{id:'load_local_config',dependsOn:[],critical:true,timeoutMs:300,run:async()=>{}},{id:'restore_account',dependsOn:['load_local_config'],critical:true,timeoutMs:500,run:async()=>{}},{id:'fetch_remote_config',dependsOn:['load_local_config'],critical:false,timeoutMs:800,run:async()=>{},fallback:async()=>{console.info('[Startup] use cached remote config');}}];

任务声明越清晰，启动排查越容易。哪个任务慢、哪个任务失败、哪个任务阻塞首屏，都能从记录中看到。

8. 在 UIAbility 中接入

启动编排不要阻塞所有 UI。关键任务完成后即可展示首页，非关键任务可以延后。

// entry/src/main/ets/entryability/EntryAbility.etsimportUIAbilityfrom'@ohos.app.ability.UIAbility';importwindowfrom'@ohos.window';import{StartupOrchestrator}from'../../common/startup/StartupOrchestrator';import{appStartupTasks}from'../../common/startup/AppStartupTasks';exportdefaultclassEntryAbilityextendsUIAbility{asynconWindowStageCreate(windowStage:window.WindowStage):Promise<void>{constrecords=awaitStartupOrchestrator.run(appStartupTasks);console.info(`[Startup] records=${JSON.stringify(records)}`);windowStage.loadContent('pages/HomePage');}}

实际项目里，如果启动任务较多，应进一步拆分关键路径和延迟任务，不要把所有任务都放在loadContent前。

9. 启动编排验证动作

启动验证要保留 records。没有记录，就无法判断是哪个任务拖慢了启动。

可以把启动记录转成简短摘要，方便连续启动时对比关键路径。

import{StartupTaskRecord}from'./StartupTask';exportfunctionsummarizeStartup(records:StartupTaskRecord[]):string{returnrecords.map(item=>`${item.id}:${item.result}:${item.costMs}ms`).join(' | ');}

这段摘要函数用于调试和测试记录。它能快速暴露某个任务耗时突然升高，或者某个任务从成功变成 fallback 的情况。

10. 启动编排排查表

11. 启动任务发布前检查

发布前建议至少做三组启动测试：首次安装冷启动、普通冷启动、断网冷启动。首次安装能暴露初始化问题，普通冷启动能看日常耗时，断网冷启动能验证 fallback 是否真的生效。

启动编排专项证据包：依赖、超时和降级要一起验收

启动任务不是越并发越好。真正需要验收的是依赖是否正确、失败是否隔离、超时是否降级、首屏是否被非必要任务阻塞。建议每个启动任务都有一条证据记录。

interfaceStartupTaskEvidence{taskName:stringdependsOn:string[]timeoutMs:numberfallback:'skip'|'default_value'|'block'}functionassertStartupTask(e:StartupTaskEvidence):void{if(e.timeoutMs>2000&&e.fallback==='block'){thrownewError(`${e.taskName}会阻塞启动且缺少降级`)}}

这段代码适合用于启动任务评审，目的是把“能不能放到首屏前”说清楚。

12. 启动编排总结

启动任务编排的核心是让依赖关系显性化。任务声明自己依赖谁、是否关键、多久超时、失败怎么兜底；编排器只负责找 ready 任务并发执行；执行器只负责运行和记录。这样启动链路从“散落初始化”变成“可观察任务图”，后续优化首屏和排查启动失败都会更稳。