第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 边界 降级默认值 用户提示项目的错误处理遵循经典的三层防护模型层级职责典型实现第一层Try-Catch 边界捕获异常防止崩溃扩散try { ... } catch (error) { ... } finally { ... }第二层降级默认值返回合理的兜底数据getFallbackResult()、pickText()、use mock data第三层用户友好提示将错误转化为用户可理解的消息showNotice()、getErrorMessage()在 Index.ets 的saveCurrentVideo方法中三层防护清晰可见privateasyncsaveCurrentVideo():Promisevoid{if(this.exportBusy)return;// UI 守卫前置防护this.exportBusytrue;this.showNotice(正在准备保存视频);// 操作前提示try{awaitVideoExportService.saveToLocal(...);this.downloadedActivetrue;this.showNotice(视频已保存);// 成功提示}catch(error){this.showNotice(保存失败this.getErrorMessage(errorasError));// 错误提示}finally{this.exportBusyfalse;// 资源/状态清理}}这套模型的核心思想是每一层都有明确的职责层与层之间互不替代。Try-Catch 保证不崩溃降级保证有数据可用用户提示保证体验不中断。二、异步错误捕获async/await 与 try-catch 的黄金组合在鸿蒙应用中网络请求、图片处理和 AI 任务全是异步操作。async/await语法让异步代码看起来像同步代码但错误处理也必须配套跟上。2.1 包裹整个异步链路在sendChatPrompt方法中整个异步操作被一个 try-catch 块包裹privateasyncsendChatPrompt(){constpromptthis.chatInput.trim();if(prompt||this.chatBusy)return;this.chatBusytrue;this.chatInput;// ... 构建消息try{constgeneratedImage:GeneratedImageawaitAIGenerationService.generateImage(prompt);// ... 处理成功结果}catch(error){this.showNotice(图片生成失败请稍后重试);}finally{this.chatBusyfalse;}}关键要点Try 块要足够大切勿只在await行加 try-catch应将整个请求处理逻辑包裹在内这样才能捕获从请求发起、结果解析到状态更新的所有异常。Catch 块要足够细给用户一个可操作的提示“请稍后重试”而非技术堆栈。Finally 块必须执行无论成功还是失败chatBusy状态都必须恢复为false否则 UI 会永久卡住。2.2 异步错误传播链在 AIGenerationService 中generateVideo方法调用了createImg2VideoTask、pollImg2VideoTask、downloadVideo等多个异步方法。每个子方法内部都使用 try-catch-finally但错误会重新抛出throw逐层向上传播privatestaticasynccreateImg2VideoTask(base64:string):PromiseGeneratedVideoTask{constrequesthttp.createHttp();try{// ... 发起请求、解析响应if(response.responseCode200||response.responseCode300){thrownewError(图片上传接口返回异常response.responseCode.toString());}// ... 继续解析}catch(error){constsafeErrorerrorasError;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(errorerror.messageerror.message!){returnerror.message;}returnJSON.stringify(error);}3.1 为什么要统一格式化错误来源原始格式getErrorMessage输出throw new Error(网络超时)Error: 网络超时网络超时JSON parse 失败SyntaxError: Unexpected tokenUnexpected tokenHTTP 返回 401Error: 401 Unauthorized401 Unauthorized框架抛出系统异常无message的对象{code:201,...}统一格式化的核心价值在于无论什么错误结构前端 UI 都能拿到一个可显示的字符串不会因为error.message为空而显示undefined。3.2 Index.ets 中的对称实现Index 页面中的getErrorMessage与 Service 层的实现完全一致确保 UI 层和 Service 层的错误显示风格统一privategetErrorMessage(error:Error):string{if(errorerror.messageerror.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(valuevalue.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(valueundefined||Number.isNaN(value)){return86;// 默认置信度}returnMath.max(0,Math.min(100,Math.round(value)));}这种有界取值模式确保了即使 AI 返回了异常数据如confidence: -5或confidence: 250界面上显示的进度条也不会出界。4.4 图片压缩失败的降级在 prepareUploadBase64 方法中图片压缩失败时直接使用原图try{constcompressedBufferawaitAIGenerationService.compressImageBuffer(sourceBuffer);// ... 使用压缩后的 base64}catch(error){// 压缩失败降级使用原图constsourceBase64AIGenerationService.arrayBufferToBase64(sourceBuffer);returnsourceBase64;}五、重试守卫可重试错误识别在长时间的 AI 动画生成任务中网络抖动是常态。pollImg2VideoTask方法实现了自动重试机制但并非所有错误都值得重试——认证错误401和资源不存在404就应该立即失败。privatestaticcanRetryTaskQuery(message:string):boolean{returnmessage.indexOf(400)0message.indexOf(401)0message.indexOf(403)0message.indexOf(404)0;}5.1 重试逻辑的完整闭环结合canRetryTaskQuery的轮询重试模式如下while(Date.now()-startedAtMAX_SEEDANCE_WAIT_MS){letresponseBody;try{responseBodyawaitAIGenerationService.queryImg2VideoTask(taskId);}catch(error){lastErrorMessageAIGenerationService.getErrorMessage(errorasError);if(!AIGenerationService.canRetryTaskQuery(lastErrorMessage)){thrownewError(lastErrorMessage);// 不可重试立即抛出}// 可重试等待后继续awaitAIGenerationService.sleep(POLL_INTERVAL_MS);continue;}// ... 检查任务状态}HTTP 状态码canRetryTaskQuery行为400 Bad Request❌ 不可重试请求格式错误重试无意义401 Unauthorized❌ 不可重试API Key 过期需重新配置403 Forbidden❌ 不可重试无权限访问重试无意义404 Not Found❌ 不可重试资源不存在500 / 网络超时✅ 可重试服务端临时故障重试可能成功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(...):Promisestring{constrequesthttp.createHttp();try{// ... 发起请求和处理}finally{request.destroy();// 无论成功还是失败都要销毁请求}}6.2 图片资源的链式释放图片压缩涉及多个资源对象释放顺序有严格要求——必须先释放子对象再释放父对象privatestaticasynccompressImageBuffer(sourceBuffer:ArrayBuffer):PromiseArrayBuffer{constsource:image.ImageSourceimage.createImageSource(sourceBuffer);letpixelMap:image.PixelMap|nullnull;constpacker:image.ImagePackerimage.createImagePacker();try{// ... 解码、缩放、编码}finally{if(pixelMap!null){awaitpixelMap.release();// 先释放 PixelMap}awaitpacker.release();// 再释放 Packerawaitsource.release();// 最后释放 ImageSource}}6.3 文件句柄的关闭文件操作也遵循同样的模式——内层 finally 保证文件关闭外层 finally 保证资源销毁constfilefileIo.openSync(path,fileIo.OpenMode.READ_ONLY);try{// ... 文件读取操作}finally{fileIo.closeSync(file);// 一定关闭文件}七、UI 状态守卫重复操作的预防在 UI 层面最典型的错误就是重复点击导致的并发操作。项目中通过布尔状态变量实现了简单的互斥守卫// 视频导出守卫privateasyncsaveCurrentVideo():Promisevoid{if(this.exportBusy)return;// 导出中忽略重复点击this.exportBusytrue;// ...}// 语音识别守卫privateasyncstartVoiceInput():Promisevoid{if(this.voiceListening){// 正在听执行停止逻辑this.voiceListeningfalse;awaitthis.voiceRecognitionService.stop();return;}// ...}// AI 图片生成守卫if(this.chatBusy)return;this.chatBusytrue;// ...7.1 守卫的可视化反馈更进一步的优化是在chatBusy为 true 时UI 层也给出视觉反馈Button(this.chatBusy?生成中:发送).backgroundColor(this.chatBusy?#A9A0D8:this.brandPurple)用户在界面上一眼就能看出当前操作的状态既防止了重复操作又消除了用户的不确定性。八、通知系统用户友好的错误呈现所有的 catch 块最终都通过showNotice方法向用户展示错误信息privateshowNotice(text:string){this.noticeTexttext;}而在 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)}}项目中的错误提示遵循几个原则原则说明示例以用户为中心不说技术术语只说影响和操作“保存失败”而非 “TypeError: Cannot read properties”可操作性提示用户能做什么“请稍后重试”正向引导即使失败也提供替代路径“已载入示例画作便于继续流程”一致性所有错误走同一个展示通道统一通过showNotice→NoticeBar九、容错策略全景图将上述所有模式综合起来可以看到画伴梦工厂中的容错体系覆盖了代码执行的每一个关键节点用户操作 │ ├── 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。十、最佳实践总结以下是本文所有容错模式的速查表供实际开发中参考模式代码位置适用场景UI 状态守卫if (this.exportBusy) return防止按钮重复点击、并发操作同步 try-catch-finallyreadImageAsBase64文件读取、JSON 解析等同步操作异步 try-catch-finallysaveCurrentVideo网络请求、AI 服务等异步操作统一错误格式化getErrorMessage()将各种 Error 类型转为可显示字符串字段级降级pickText()/clampConfidence()AI 输出字段缺失或越界整体降级getFallbackResult()服务完全不可用时返回默认 UI 数据重试守卫canRetryTaskQuery()HTTP 请求失败的重试决策超时保护MAX_SEEDANCE_WAIT_MS长时间轮询的超时兜底资源释放finally { request.destroy() }HTTP、PixelMap、ImageSource、文件句柄用户通知showNotice()NoticeBar所有错误的对外呈现总结本文从画伴梦工厂的实际源码出发系统总结了在鸿蒙应用中构建错误处理与容错设计的方法论维度核心思路关键代码三层防护try-catch 捕获 → 降级兜底 → 用户提示saveCurrentVideo、sendChatPrompt错误格式化统一提取error.messagegetErrorMessage()降级策略字段级 整体级兜底数据pickText、getFallbackResult、clampConfidence重试机制根据错误类型判断是否可重试canRetryTaskQuery资源清理finally 块中对称释放request.destroy、pixelMap.releaseUI 守卫布尔状态互斥锁exportBusy、chatBusy、recording用户通知统一通道 可关闭的 NotificationBarshowNoticeNoticeBar错误处理不是锦上添花的功能而是应用健壮性的基石。一个好的错误处理体系要做到悄无声息地处理可恢复错误不失体面地展示不可恢复错误——这正是画伴梦工厂代码中透露的工程智慧。在下一篇中我们将探讨跨页面通信与全局状态管理的最佳实践。参考源码本文所有代码均来自项目文件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资源清理等高级容错模式