HarmonyOS APP《画伴梦工厂》开发第47篇-错误处理与容错设计——鸿蒙应用健壮性

第6.5篇：错误处理与容错设计——鸿蒙应用健壮性

难度：⭐⭐⭐ 高级
前置知识：第 3.1 ~ 3.9 篇 图像识别、AI 服务与网络请求封装
涉及源文件：products/default/src/main/ets/services/AIGenerationService.ets、products/default/src/main/ets/services/ImageRecognitionService.ets、products/default/src/main/ets/pages/Index.ets

概述

企业级应用不仅要"能跑"，更要"稳得住"。在"画伴梦工厂"中，涉及系统相机调用、HTTP 网络请求、AI 模型推理、图片编解码、文件读写等多种高失败率操作。任何一个环节出错，若未妥善处理，轻则功能异常，重则应用闪退，对儿童用户极不友好。

本文将从"画伴梦工厂"的实际源码出发，系统梳理在 HarmonyOS 应用开发中构建纵深防御（Defense in Depth）错误处理体系的最佳实践，涵盖三层保护屏障、异步错误捕获、降级策略、资源清理与 UI 状态守卫。

一、三层防护模型：Try-Catch 边界 + 降级默认值 + 用户提示

项目的错误处理遵循经典的三层防护模型：

在 Index.ets 的saveCurrentVideo方法中，三层防护清晰可见：

privateasyncsaveCurrentVideo():Promise<void>{if(this.exportBusy)return;// UI 守卫（前置防护）this.exportBusy=true;this.showNotice('正在准备保存视频');// 操作前提示try{awaitVideoExportService.saveToLocal(...);this.downloadedActive=true;this.showNotice('视频已保存');// 成功提示}catch(error){this.showNotice('保存失败：'+this.getErrorMessage(errorasError));// 错误提示}finally{this.exportBusy=false;// 资源/状态清理}}

这套模型的核心思想是：每一层都有明确的职责，层与层之间互不替代。Try-Catch 保证不崩溃，降级保证有数据可用，用户提示保证体验不中断。

二、异步错误捕获：async/await 与 try-catch 的黄金组合

在鸿蒙应用中，网络请求、图片处理和 AI 任务全是异步操作。async/await语法让异步代码看起来像同步代码，但错误处理也必须配套跟上。

2.1 包裹整个异步链路

在sendChatPrompt方法中，整个异步操作被一个 try-catch 块包裹：

privateasyncsendChatPrompt(){constprompt=this.chatInput.trim();if(prompt===''||this.chatBusy)return;this.chatBusy=true;this.chatInput='';// ... 构建消息try{constgeneratedImage:GeneratedImage=awaitAIGenerationService.generateImage(prompt);// ... 处理成功结果}catch(error){this.showNotice('图片生成失败，请稍后重试');}finally{this.chatBusy=false;}}

关键要点：

1. Try 块要足够大：切勿只在await行加 try-catch，应将整个请求+处理逻辑包裹在内，这样才能捕获从请求发起、结果解析到状态更新的所有异常。
2. Catch 块要足够细：给用户一个可操作的提示（“请稍后重试”），而非技术堆栈。
3. Finally 块必须执行：无论成功还是失败，chatBusy状态都必须恢复为false，否则 UI 会永久卡住。

2.2 异步错误传播链

在 AIGenerationService 中，generateVideo方法调用了createImg2VideoTask、pollImg2VideoTask、downloadVideo等多个异步方法。每个子方法内部都使用 try-catch-finally，但错误会重新抛出（throw），逐层向上传播：

privatestaticasynccreateImg2VideoTask(base64:string):Promise<GeneratedVideoTask>{constrequest=http.createHttp();try{// ... 发起请求、解析响应if(response.responseCode<200||response.responseCode>=300){thrownewError('图片上传接口返回异常：'+response.responseCode.toString());}// ... 继续解析}catch(error){constsafeError=errorasError;AIGenerationService.logError('createImg2VideoTask failed: '+AIGenerationService.getErrorMessage(safeError));throwsafeError;// 重新抛出，让上层处理}finally{request.destroy();}}

这种模式的好处是：每层只处理自己关心的清理逻辑（finally），决策逻辑集中在顶层调用者。顶层调用者（如sendChatPrompt）根据业务场景决定是重试、降级还是提示用户。

三、BusinessError 格式转换与安全错误消息提取

在调用系统 API 或第三方接口时，抛出的错误类型多种多样——可能是Error对象、可能带message字段、也可能是一个无法直接显示的 JSON 对象。

项目中通过getErrorMessage方法对所有错误进行统一的消息提取：

// ImageRecognitionService.ets / AIGenerationService.etsstaticgetErrorMessage(error:Error):string{if(error&&error.message&&error.message!==''){returnerror.message;}returnJSON.stringify(error);}

3.1 为什么要统一格式化？

统一格式化的核心价值在于：无论什么错误结构，前端 UI 都能拿到一个可显示的字符串，不会因为error.message为空而显示undefined。

3.2 Index.ets 中的对称实现

Index 页面中的getErrorMessage与 Service 层的实现完全一致，确保 UI 层和 Service 层的错误显示风格统一：

privategetErrorMessage(error:Error):string{if(error&&error.message&&error.message!=='')returnerror.message;returnJSON.stringify(error);}

四、降级策略：Fallback Result 与兜底数据

当识别或生成服务完全不可用时，应用不能白屏或报错——它应该返回一个合理的默认值，让流程可以继续。

4.1 getFallbackResult：完整的兜底识别结果

ImageRecognitionService 中定义了DEFAULT_RESULT常量和getFallbackResult静态方法：

constDEFAULT_RESULT:DrawingRecognitionResult={protagonist:'小恐龙',scene:'草地和太阳',emotion:'快乐探险',animationSuggestion:'跳跃、摇尾、看向太阳',summary:'识别到儿童手绘中的主角、自然场景和明亮情绪，适合生成轻快的探险动画草稿。',elements:[{name:'小恐龙',confidence:96,color:'#D8F7EA'},{name:'太阳',confidence:91,color:'#FFF0DD'},{name:'草地',confidence:88,color:'#EAF8F0'},{name:'树木',confidence:84,color:'#F1EDFF'}]};staticgetFallbackResult():DrawingRecognitionResult{return{protagonist:DEFAULT_RESULT.protagonist,scene:DEFAULT_RESULT.scene,// ... 每个字段都从 DEFAULT_RESULT 获取};}

这个方法的使用场景包括：

• 图片 URI 为空时直接返回兜底结果，不发起网络请求
• AI 返回内容缺失（如protagonist为空）时，用默认值填充
• 模型接口异常时，作为候选降级方案

4.2 pickText：单字段的降级守卫

normalizeModelResult方法使用pickText对模型返回的每个字段进行空值检查：

privatestaticpickText(value:string|undefined,fallback:string):string{if(value&&value.trim()!==''){returnvalue.trim();}returnfallback;}

return{protagonist:ImageRecognitionService.pickText(parsed.protagonist,fallback.protagonist),scene:ImageRecognitionService.pickText(parsed.scene,fallback.scene),emotion:ImageRecognitionService.pickText(parsed.emotion,fallback.emotion),// ...};

这个简单的函数解决了一个常见痛点：AI 大模型的输出具有不确定性，返回的字段可能是undefined、空字符串或纯空白。通过pickText配合getFallbackResult的默认值，实现了字段级别的容错。

4.3 clampConfidence：数值范围的守卫

对于置信度等数值字段，clampConfidence确保数值始终在合法范围内：

privatestaticclampConfidence(value:number|undefined):number{if(value===undefined||Number.isNaN(value)){return86;// 默认置信度}returnMath.max(0,Math.min(100,Math.round(value)));}

这种"有界取值"模式确保了即使 AI 返回了异常数据（如confidence: -5或confidence: 250），界面上显示的进度条也不会出界。

4.4 图片压缩失败的降级

在 prepareUploadBase64 方法中，图片压缩失败时直接使用原图：

try{constcompressedBuffer=awaitAIGenerationService.compressImageBuffer(sourceBuffer);// ... 使用压缩后的 base64}catch(error){// 压缩失败，降级使用原图constsourceBase64=AIGenerationService.arrayBufferToBase64(sourceBuffer);returnsourceBase64;}

五、重试守卫：可重试错误识别

在长时间的 AI 动画生成任务中，网络抖动是常态。pollImg2VideoTask方法实现了自动重试机制，但并非所有错误都值得重试——认证错误（401）和资源不存在（404）就应该立即失败。

privatestaticcanRetryTaskQuery(message:string):boolean{returnmessage.indexOf('400')<0&&message.indexOf('401')<0&&message.indexOf('403')<0&&message.indexOf('404')<0;}

5.1 重试逻辑的完整闭环

结合canRetryTaskQuery的轮询重试模式如下：

while(Date.now()-startedAt<MAX_SEEDANCE_WAIT_MS){letresponseBody;try{responseBody=awaitAIGenerationService.queryImg2VideoTask(taskId);}catch(error){lastErrorMessage=AIGenerationService.getErrorMessage(errorasError);if(!AIGenerationService.canRetryTaskQuery(lastErrorMessage)){thrownewError(lastErrorMessage);// 不可重试，立即抛出}// 可重试，等待后继续awaitAIGenerationService.sleep(POLL_INTERVAL_MS);continue;}// ... 检查任务状态}

5.2 超时兜底

轮询还有一重安全网——超时保护：

thrownewError('视频生成超时，请稍后重试'+(lastErrorMessage!==''?'，'+lastErrorMessage:''));

MAX_SEEDANCE_WAIT_MS被设置为 6 分钟，超过这个时间无论任务是否完成都终止轮询。这防止了用户在极端情况下面临无限等待的困境。

六、资源清理：Finally 块中的确定性释放

HarmonyOS 中的系统资源（HTTP 请求、PixelMap、ImageSource、ImagePacker 等）必须显式释放，否则会造成内存泄漏。

6.1 HTTP 请求的销毁

每个 HTTP 请求方法都使用 try-catch-finally 模式，确保request.destroy()一定执行：

privatestaticasynccreateSeedanceTask(...):Promise<string>{constrequest=http.createHttp();try{// ... 发起请求和处理}finally{request.destroy();// 无论成功还是失败，都要销毁请求}}

6.2 图片资源的链式释放

图片压缩涉及多个资源对象，释放顺序有严格要求——必须先释放子对象，再释放父对象：

privatestaticasynccompressImageBuffer(sourceBuffer:ArrayBuffer):Promise<ArrayBuffer>{constsource:image.ImageSource=image.createImageSource(sourceBuffer);letpixelMap:image.PixelMap|null=null;constpacker:image.ImagePacker=image.createImagePacker();try{// ... 解码、缩放、编码}finally{if(pixelMap!==null){awaitpixelMap.release();// 先释放 PixelMap}awaitpacker.release();// 再释放 Packerawaitsource.release();// 最后释放 ImageSource}}

6.3 文件句柄的关闭

文件操作也遵循同样的模式——内层 finally 保证文件关闭，外层 finally 保证资源销毁：

constfile=fileIo.openSync(path,fileIo.OpenMode.READ_ONLY);try{// ... 文件读取操作}finally{fileIo.closeSync(file);// 一定关闭文件}

七、UI 状态守卫：重复操作的预防

在 UI 层面，最典型的错误就是重复点击导致的并发操作。项目中通过布尔状态变量实现了简单的互斥守卫：

// 视频导出守卫privateasyncsaveCurrentVideo():Promise<void>{if(this.exportBusy)return;// 导出中，忽略重复点击this.exportBusy=true;// ...}// 语音识别守卫privateasyncstartVoiceInput():Promise<void>{if(this.voiceListening){// 正在听，执行停止逻辑this.voiceListening=false;awaitthis.voiceRecognitionService.stop();return;}// ...}// AI 图片生成守卫if(this.chatBusy)return;this.chatBusy=true;// ...

7.1 守卫的可视化反馈

更进一步的优化是，在chatBusy为 true 时，UI 层也给出视觉反馈：

Button(this.chatBusy?'生成中':'发送').backgroundColor(this.chatBusy?'#A9A0D8':this.brandPurple)

用户在界面上一眼就能看出当前操作的状态，既防止了重复操作，又消除了用户的不确定性。

八、通知系统：用户友好的错误呈现

所有的 catch 块最终都通过showNotice方法向用户展示错误信息：

privateshowNotice(text:string){this.noticeText=text;}

而在 UI 模板中，NoticeBar组件会根据noticeText非空自动渲染：

@BuilderprivateNoticeBar(){if(this.noticeText!==''){Row(){Text(this.noticeText).fontSize(12).fontColor('#FFFFFF').layoutWeight(1)Text('x').onClick(()=>{this.noticeText='';})}.backgroundColor('#D94C3D')// 红色警示.borderRadius(18)}}

项目中的错误提示遵循几个原则：

九、容错策略全景图

将上述所有模式综合起来，可以看到"画伴梦工厂"中的容错体系覆盖了代码执行的每一个关键节点：

用户操作 │ ├── UI 状态守卫 ─────── exportBusy / chatBusy / recording │ └── 进入异步操作 │ ├── try: │ ├── 参数校验（空值检查、格式检查） │ ├── 网络请求 / AI 调用 / 本地 IO │ └── 结果解析与数据清洗 │ ├── catch(error): │ ├── getErrorMessage() 格式化 │ ├── canRetryTaskQuery() 判断是否可重试 │ │ ├── 可重试 → 休眠后继续 │ │ └── 不可重试 → 抛出给上层 │ ├── pickText() / clampConfidence() 字段降级 │ ├── getFallbackResult() 整体降级 │ └── showNotice() 通知用户 │ └── finally: ├── request.destroy() HTTP 请求销毁 ├── pixelMap.release() 图片资源释放 ├── fileIo.closeSync() 文件句柄关闭 └── chatBusy = false 状态守卫还原

这九个字概括了项目的容错哲学：防得住（guard）、抓得住（try）、兜得住（fallback）、说得清（notice）、收得净（finally）。

十、最佳实践总结

以下是本文所有容错模式的速查表，供实际开发中参考：

总结

本文从"画伴梦工厂"的实际源码出发，系统总结了在鸿蒙应用中构建错误处理与容错设计的方法论：

错误处理不是"锦上添花"的功能，而是应用健壮性的基石。一个好的错误处理体系，要做到"悄无声息地处理可恢复错误，不失体面地展示不可恢复错误"——这正是"画伴梦工厂"代码中透露的工程智慧。

在下一篇中，我们将探讨跨页面通信与全局状态管理的最佳实践。

参考源码

本文所有代码均来自项目文件：

• products/default/src/main/ets/pages/Index.ets— 首页主组件，包含saveCurrentVideo、sendChatPrompt、saveCurrentVideo、getErrorMessage、showNotice等 UI 守卫和错误处理示例
• products/default/src/main/ets/services/ImageRecognitionService.ets— 图像识别服务，包含getFallbackResult、pickText、clampConfidence、getErrorMessage等降级策略
• products/default/src/main/ets/services/AIGenerationService.ets— AI 生成服务，包含canRetryTaskQuery、轮询重试、finally资源清理等高级容错模式