AbilityStage 与 AppStartup：启动任务编排怎么落地

AbilityStage 与 AppStartup启动任务编排怎么落地启动代码直接写在 AbilityStage 里时任务顺序、耗时和失败处理都不透明。AppStartup 的价值是把启动动作变成可声明、可排序、可观测的任务。 这类问题通常不是某个 API 写错而是工程边界没有提前定好。本文从StartupTask这条主线出发把场景判断、协议设计、代码封装、异常兜底和验证方法串成一套可落地方案。本文围绕配置加载、日志初始化、账号恢复、首页预热展开重点解决四个问题这类能力应该放在入口、页面、服务层还是扩展能力里。协议字段怎样设计后续排查才不会靠猜。代码如何封装才能避免每个页面各写一套。异常、重试、日志和验证用例应该怎样补齐。1. 先明确适用场景和边界实际项目里配置加载、日志初始化、账号恢复、首页预热 经常横跨多个模块。如果边界不清调用方会把临时字段塞进参数里接收方也只能被动兼容。更稳的做法是先明确“谁发起、谁处理、失败谁兜底”。判断点推荐做法不建议做法调用来源明确 source 或 owner只看当前页面路径业务目标用 scene 或 type 表达直接传内部实现名异常处理启动前校验接收方兜底等页面空白后再排查日志字段从入口生成 traceId出问题后再补日志2. 先定义稳定协议模型协议模型要比页面实现更稳定。页面可以改名Ability 可以迁移但StartupTask这类入口模型不要频繁变。exportinterfaceStartupTask{name:string;dependsOn:string;async:string;critical:string;cost:string;}exportinterfaceStartupTaskResult{ok:boolean;reason?:string;}代码解释StartupTask把配置加载、日志初始化、账号恢复、首页预热需要的最小字段收敛到一个结构里。字段不是为了“传得多”而是为了启动、接收和日志三端都能对齐。后续扩展字段可以新增但核心字段不要随意改名。3. 字段设计要面向排查很多线上问题不是无法修而是无法定位。下面这些字段看起来简单但能把调用来源、业务目标和链路日志串起来。字段类型工程作用name协议关键字段启动、解析、日志都围绕它对齐dependsOn协议关键字段启动、解析、日志都围绕它对齐async协议关键字段启动、解析、日志都围绕它对齐critical协议关键字段启动、解析、日志都围绕它对齐cost协议关键字段启动、解析、日志都围绕它对齐4. 启动前先做校验不要把所有异常都留给接收方。启动前能发现的问题应该在封装层直接拦住并给出可记录的原因。exportclassStartupOrchestrator{staticvalidate(input:StartupTask):StartupTaskResult{if(!input.name)return{ok:false,reason:name is empty};if(!input.dependsOn)return{ok:false,reason:dependsOn is empty};if(!input.async)return{ok:false,reason:async is empty};return{ok:true};}}代码解释StartupOrchestrator是协议入口的第一道门。空字段、非法来源、缺少 traceId 这类问题越早拦截越好。返回结构带reason页面可以提示日志也能直接记录。5. 构造系统参数要集中到工厂如果每个页面都自己拼系统参数字段名迟早会分裂。把转换逻辑收敛到StartupTaskGraph调用方只提交业务模型。import{Want}fromkit.AbilityKit;exportclassStartupTaskGraph{staticcreate(input:StartupTask):Want{return{abilityName:StartupResultStore,parameters:{...input,generatedAt:String(Date.now())}};}}代码解释工厂只负责从业务协议转换到系统入口参数。generatedAt这类辅助字段统一补避免调用方各自处理。以后目标 Ability 或参数结构变化只改工厂和路由表。6. 接收方必须再次解析和兜底启动前校验不能替代接收方校验。来自通知、卡片、外部入口、系统恢复的参数都有可能缺失或过期。exportclassStartupResultStoreHandler{asynchandle(input:StartupTask):Promisevoid{constresultStartupOrchestrator.validate(input);if(!result.ok){StageIssueStore.save(25,result.reason??unknown);return;}StageTraceLogger.info(input.traceId,配置加载、日志初始化、账号恢复、首页预热);}}代码解释StartupResultStoreHandler不相信外部输入先走同一套校验。失败时写入StageIssueStore页面可以展示错误态而不是直接白屏。成功后记录 trace 日志方便跨生命周期排查。7. 生命周期里要处理重复进入Stage 模型下入口可能来自冷启动也可能来自已有实例的重复拉起。只在首次创建时处理参数后面就容易丢入口。exportclassStage25EntryBridge{privatelatest?:StartupTask;update(input:StartupTask,lifecycle:onCreate|onNewWant|onForeground):void{constresultStartupOrchestrator.validate(input);if(!result.ok){StageIssueStore.save(25,result.reason??invalid input);return;}this.latestinput;StageTraceLogger.info(input.traceId,lifecycle);}current():StartupTask|undefined{returnthis.latest;}}代码解释update同时支持onCreate、onNewWant和前台恢复。最新入口保存在桥接层页面只读取解析后的安全数据。生命周期名进入日志能判断问题发生在哪个阶段。8. 失败补偿要有明确策略不是所有失败都应该重试也不是所有失败都要提示用户。可以按错误来源做分层参数错误直接兜底系统约束延后处理业务失败进入可重试队列。exportenumStage25FailureAction{ShowFallbackshow_fallback,RetryLaterretry_later,Ignoreignore}exportfunctionresolveStage25Failure(reason:string):Stage25FailureAction{if(reason.includes(empty)||reason.includes(unknown)){returnStage25FailureAction.ShowFallback;}if(reason.includes(network)||reason.includes(timeout)){returnStage25FailureAction.RetryLater;}returnStage25FailureAction.Ignore;}代码解释参数类错误通常没有重试价值应该展示兜底。网络、超时、系统约束类问题可以进入延迟重试。失败策略写成函数后续能加日志、埋点和实验开关。9. 验证用例要覆盖正常和异常只验证正常路径没有意义。下面这些用例能覆盖配置加载、日志初始化、账号恢复、首页预热的核心边界。exportconststage25CheckCases[{name:关键任务失败,expect:可复现并有明确结果},{name:非关键任务失败,expect:可复现并有明确结果},{name:依赖循环,expect:可复现并有明确结果},{name:启动耗时,expect:可复现并有明确结果},{name:首屏可用,expect:可复现并有明确结果}];代码解释用例名称直接对应真实问题方便测试和产品一起确认。每个用例都要有明确期望不能只写“能打开”。如果后续改协议这组用例就是回归清单。10. 常见问题排查表现象高概率原因处理方式首屏慢非关键任务阻塞启动异步后置任务偶发未执行依赖声明错误检查 TaskGraph失败无感知结果未保存写入 ResultStore循环依赖任务互相等待启动前检查 graph11. 小结AbilityStage 与 AppStartup 的关键不是把代码写到能跑而是把边界提前设计清楚入口模型要稳定启动前要校验接收方要兜底生命周期要覆盖重复进入日志要能串起整条链路。这样文章里的方案迁移到真实 Stage 工程后才不会随着入口变多而失控。