2026/8/7 18:29:19
FEATURED · 精选文章 
HarmonyOS NEXT AI 智能生活助手源码解析与项目复盘图1项目数据统计与架构回顾图前言本文是系列的第29 篇对整个 HarmonyAI 项目进行源码解析与复盘分析架构设计的得失总结经验教训。项目复盘是软件开发的重要环节。通过审视架构设计、代码组织、开发流程提炼可复用的经验为后续项目奠定基础。一、项目架构回顾1.1 六层架构UI (12 Pages 15 Components) ↓ State / Observed ViewModel (SessionViewModel) ↓ Repository (4 Repositories) ↓ AIService (统一入口 CacheManager) ↓ AI Managers (8 个能力模块) ↓ PromptManager (8 个模板) ↓ LLM Provider (5 个实现)层级文件数职责关键设计UI27页面和组件ArkUI 声明式ViewModel1状态管理ObservedRepository4数据访问数据仓库Service2AI 入口 缓存AIServiceManager8AI 能力各模块独立Prompt8Prompt 管理模板引擎Provider65 个实现 工厂多态切换1.2 架构优势特性说明实现方式解耦各层职责清晰接口 依赖注入可扩展新增 Provider 零侵入工厂模式可维护Prompt 独立管理YAML front matter可测试各模块可独立测试Repository 模式性能缓存 虚拟列表CacheManager LazyForEach二、数据统计2.1 项目规模指标数值说明总代码行数~15,000 行ArkTS TypeScript页面数12 个Splash ~ About组件数15 个高复用公共组件工具类10 个AIUtil ~ PreferenceUtilAI 能力8 个聊天/翻译/OCR/花语/总结/代码/待办/日程LLM Provider5 个OpenAI/DeepSeek/Qwen/智谱/豆包Prompt 模板8 个chat/translate/flower/summary/code/todo/schedule/systemGit Tag28 个每个里程碑一个 Tag博客29 篇覆盖完整开发过程2.2 文件分布目录文件数占比pages/1212%components/1515%ai/88%provider/66%prompt/99%repository/44%service/22%utils/1010%model/55%theme/33%database/22%constants/22%AI 能力核心AIService 8 Managers → 统一路由 数据核心4 Repositories → 数据库 缓存 UI 核心27 个页面/组件 → ArkUI 声明式三、改进方向3.1 已完成优势架构清晰六层架构分层明确扩展性强新增 Provider 只需注册Prompt 独立版本管理热加载多模型支持5 个 LLM Provider3.2 改进空间改进项当前状态目标优先级单元测试无核心模块 80% 覆盖 高状态管理State引入状态管理库 中MCP 集成预留完整 MCP 协议 中离线能力完全依赖网络本地小模型兜底 低国际化仅中文多语言支持 低3.3 技术债务// 需要改进的代码模式// 1. 错误处理 — 统一 ErrorHandler// 当前分散的 try-catchtry{awaitapi();}catch{showToast(失败);}// 目标统一错误处理AIServiceErrorHandler.handle(awaitapi());// 2. 状态管理 — 引入单例 ViewModel// 当前多处 State// 目标全局状态管理// 3. 类型定义 — 统一类型文件// 当前散落在各文件中// 目标model/types.ts 统一管理四、模块依赖分析4.1 依赖关系图// 模块依赖矩阵exportconstMODULE_DEPENDENCIES:Recordstring,string[]{pages:[components,repository,service],components:[theme,constants,utils],repository:[database,model,utils],service:[provider,ai,prompt,utils],ai:[prompt,service,model],provider:[constants,utils],prompt:[model,utils],theme:[constants,utils],database:[model],utils:[],constants:[],model:[]};// 验证依赖规则exportclassDependencyValidator{staticvalidate():string[]{constviolations:string[][];// 检查是否违反分层规则for(const[module,deps]ofObject.entries(MODULE_DEPENDENCIES)){for(constdepofdeps){// 检查依赖层级是否合法if(this.isForbidden(module,dep)){violations.push(${module}不应依赖${dep});}}}returnviolations;}privatestaticisForbidden(source:string,target:string):boolean{// 禁止跨层跳过如 pages 不能直接依赖 providerconstlayers:Recordstring,number{pages:0,components:0,repository:1,service:1,ai:2,provider:2,prompt:2,theme:0,constants:0,utils:0,database:1,model:0};constsrcLayerlayers[source]??0;consttgtLayerlayers[target]??0;// 工具类和常量层可以被任何层使用if([utils,constants,model].includes(target))returnfalse;// 同一层或更低层可以依赖returntgtLayersrcLayer1;}}源模块允许依赖禁止依赖原因pagescomponents, repositoryprovider, promptUI 层不应直接操作 AIcomponentstheme, constantsservice, repository组件只关心展示repositorydatabase, modelpages, components数据层不依赖 UIserviceprovider, prompt, aipages, components服务层不感知 UI4.2 性能热点分析exportclassHotspotAnalyzer{staticanalyze():HotspotReport{return{hotspots:[{module:ChatBubble,issue:频繁 State 更新,suggestion:使用 LazyForEach 延迟渲染},{module:MarkdownView,issue:长文本解析,suggestion:增量渲染分块处理},{module:AIService,issue:API 串行调用,suggestion:合并请求批量处理},{module:OCRService,issue:大图解码,suggestion:预压缩异步处理}],recommendations:[使用虚拟列表优化长列表,图片上传前压缩到 1920px,流式输出添加 Throttle,AI 请求添加缓存层]};}}interfaceHotspotReport{hotspots:Array{module:string;issue:string;suggestion:string;};recommendations:string[];}五、开发经验总结经验问题描述最佳实践状态管理State 数组更新不触发渲染使用展开运算符this.arr [...this.arr]路由跳转页面路径配置错误在 module.json5 中注册所有页面异步错误Promise 未 catch统一 ErrorHandler 全局捕获内存泄漏全局事件监听未清理在 aboutToDisappear 中取消监听权限申请运行时权限弹窗使用能力访问控制 atManager数据持久化关系型数据库外键使用 ON DELETE CASCADE// 最佳实践代码片段// 1. State 数组更新this.messages[...this.messages,newMessage];// 2. 统一错误处理try{awaitthis.aiService.chat(messages);}catch(error){constappErrorAIServiceErrorHandler.handle(error);ToastUtil.show(appError.message);}// 3. 生命周期清理aboutToDisappear():void{this.syncHelper.removeObserve(new_message,this.callback);clearInterval(this.timer);}七、开发者贡献指南7.1 如何参与项目# Fork 项目gitclone https://github.com/yourname/HarmonyAI.gitcdHarmonyAI# 创建功能分支gitcheckout-bfeat/new-feature# 开发完成后提交gitadd.gitcommit-mfeat(xxx): 新功能描述gitpush origin feat/new-feature# 创建 Pull Request贡献类型说明入门难度Bug 修复修复已知问题⭐新功能实现规划中的功能⭐⭐文档改进文档和注释⭐测试补充单元测试⭐⭐性能优化代码性能调优⭐⭐⭐Provider 扩展接入新 AI 模型⭐⭐7.2 代码规范// 文件命名大驼峰// ChatPage.ets ✓ chatPage.ets ✗// 类名大驼峰classAIService{}✓classai_service{}✗// 方法名小驼峰sendMessage(){}✓send_message(){}✗// 常量全大写下划线constAPI_BASE_URLhttps://api.example.com✓constapiBaseUrlhttps://api.example.com✗// 类型注解显式声明constcount:number42✓constcount42✗允许但不推荐// 错误处理统一 ErrorHandlertry{awaitapi();}catch(e){AIServiceErrorHandler.handle(e);}✓catch(e){console.error(e);}✗7.3 代码审查清单exportconstCODE_REVIEW_CHECKLIST[是否遵循分层架构UI/ViewModel/Repository/Service,是否使用了统一 AIService 而非直接调用 Provider,Prompt 是否放在 prompt/ 目录而非写死在代码中,是否有单元测试覆盖,是否处理了错误边界和异常情况,是否添加了必要的日志,是否有性能风险虚拟列表/缓存/压缩,是否符合 ArkTS/TypeScript 编码规范];开源项目的生命力在于社区贡献。欢迎提交 PR、Issue 和建议八、Git 提交gitadd.gitcommit-mdocs(review): 源码解析与项目复盘 - 六层架构回顾与数据统计 - 模块依赖分析与性能热点 - 开发经验与技术债务总结 - 36条代码规范与审查清单 - 贡献指南与参与方式 Co-Authored-By: AtomCode (deepseek-v4-flash) noreplyatomgit.comgittag v0.2.8总结本文完成了源码解析与项目复盘。核心要点六层架构UI → ViewModel → Repository → Service → Prompt → Provider数据统计15,000 行代码12 页面8 AI 能力架构优势解耦、可扩展、可维护改进方向单元测试、MCP、离线能力技术债务错误处理、状态管理、类型统一如果这篇文章对你有帮助欢迎点赞、收藏⭐、关注你的支持是我持续创作的动力六、项目亮点回顾6.1 核心技术亮点回顾整个 HarmonyAI 项目以下技术亮点值得特别提及统一 AIService 架构所有 AI 能力通过单一入口调用新增功能零侵入扩展多模型无缝切换OpenAI、DeepSeek、Qwen、智谱、豆包一键切换故障自动转移Prompt 版本管理独立模板引擎支持 A/B 测试和热加载持续优化闭环三级缓存体系内存 LRU 磁盘 Preferences 关系型数据库命中率超 90%玻璃拟态 UIbackdropBlur 毛玻璃效果Light/Dark/Auto 三模式平滑过渡安全区全局适配基于display.getDefaultDisplaySync().densityPixels的精确 px→vp 转换SVG 全矢量图标所有图标采用 SVG杜绝 emoji 渲染异常多端一致性能全面优化LazyForEach 虚拟列表、图片智能压缩、流式 Throttle1000 条消息流畅渲染6.2 工程实践亮点Git 语义化提交每个功能点独立 Commit28 个 Tag 清晰标记里程碑分层架构严格遵循UI/ViewModel/Repository/Service/Manager 职责清晰状态管理精细化AppStorage 全局共享安全区高度Consume/Provide 主题透传错误处理统一化标准化错误码用户友好提示可重试自动恢复SettingPage 完整实现模型切换、API Key 配置、缓存清除、数据导出一站式管理相关资源HarmonyOS 架构设计Clean ArchitectureMVVM 模式单元测试最佳实践HarmonyOS NEXT 开发文档ArkTS 语言规范设计模式工厂模式Semantic Versioning下一篇预告[30-HarmonyOSAI应用开发总结]—— 全系列30篇的终极总结回顾从项目初始化到上架发布的完整历程提炼最核心的开发经验与最佳实践。
HarmonyOS NEXT AI 智能生活助手：源码解析与项目复盘
HarmonyOS NEXT AI 智能生活助手源码解析与项目复盘图1项目数据统计与架构回顾图前言本文是系列的第29 篇对整个 HarmonyAI 项目进行源码解析与复盘分析架构设计的得失总结经验教训。项目复盘是软件开发的重要环节。通过审视架构设计、代码组织、开发流程提炼可复用的经验为后续项目奠定基础。一、项目架构回顾1.1 六层架构UI (12 Pages 15 Components) ↓ State / Observed ViewModel (SessionViewModel) ↓ Repository (4 Repositories) ↓ AIService (统一入口 CacheManager) ↓ AI Managers (8 个能力模块) ↓ PromptManager (8 个模板) ↓ LLM Provider (5 个实现)层级文件数职责关键设计UI27页面和组件ArkUI 声明式ViewModel1状态管理ObservedRepository4数据访问数据仓库Service2AI 入口 缓存AIServiceManager8AI 能力各模块独立Prompt8Prompt 管理模板引擎Provider65 个实现 工厂多态切换1.2 架构优势特性说明实现方式解耦各层职责清晰接口 依赖注入可扩展新增 Provider 零侵入工厂模式可维护Prompt 独立管理YAML front matter可测试各模块可独立测试Repository 模式性能缓存 虚拟列表CacheManager LazyForEach二、数据统计2.1 项目规模指标数值说明总代码行数~15,000 行ArkTS TypeScript页面数12 个Splash ~ About组件数15 个高复用公共组件工具类10 个AIUtil ~ PreferenceUtilAI 能力8 个聊天/翻译/OCR/花语/总结/代码/待办/日程LLM Provider5 个OpenAI/DeepSeek/Qwen/智谱/豆包Prompt 模板8 个chat/translate/flower/summary/code/todo/schedule/systemGit Tag28 个每个里程碑一个 Tag博客29 篇覆盖完整开发过程2.2 文件分布目录文件数占比pages/1212%components/1515%ai/88%provider/66%prompt/99%repository/44%service/22%utils/1010%model/55%theme/33%database/22%constants/22%AI 能力核心AIService 8 Managers → 统一路由 数据核心4 Repositories → 数据库 缓存 UI 核心27 个页面/组件 → ArkUI 声明式三、改进方向3.1 已完成优势架构清晰六层架构分层明确扩展性强新增 Provider 只需注册Prompt 独立版本管理热加载多模型支持5 个 LLM Provider3.2 改进空间改进项当前状态目标优先级单元测试无核心模块 80% 覆盖 高状态管理State引入状态管理库 中MCP 集成预留完整 MCP 协议 中离线能力完全依赖网络本地小模型兜底 低国际化仅中文多语言支持 低3.3 技术债务// 需要改进的代码模式// 1. 错误处理 — 统一 ErrorHandler// 当前分散的 try-catchtry{awaitapi();}catch{showToast(失败);}// 目标统一错误处理AIServiceErrorHandler.handle(awaitapi());// 2. 状态管理 — 引入单例 ViewModel// 当前多处 State// 目标全局状态管理// 3. 类型定义 — 统一类型文件// 当前散落在各文件中// 目标model/types.ts 统一管理四、模块依赖分析4.1 依赖关系图// 模块依赖矩阵exportconstMODULE_DEPENDENCIES:Recordstring,string[]{pages:[components,repository,service],components:[theme,constants,utils],repository:[database,model,utils],service:[provider,ai,prompt,utils],ai:[prompt,service,model],provider:[constants,utils],prompt:[model,utils],theme:[constants,utils],database:[model],utils:[],constants:[],model:[]};// 验证依赖规则exportclassDependencyValidator{staticvalidate():string[]{constviolations:string[][];// 检查是否违反分层规则for(const[module,deps]ofObject.entries(MODULE_DEPENDENCIES)){for(constdepofdeps){// 检查依赖层级是否合法if(this.isForbidden(module,dep)){violations.push(${module}不应依赖${dep});}}}returnviolations;}privatestaticisForbidden(source:string,target:string):boolean{// 禁止跨层跳过如 pages 不能直接依赖 providerconstlayers:Recordstring,number{pages:0,components:0,repository:1,service:1,ai:2,provider:2,prompt:2,theme:0,constants:0,utils:0,database:1,model:0};constsrcLayerlayers[source]??0;consttgtLayerlayers[target]??0;// 工具类和常量层可以被任何层使用if([utils,constants,model].includes(target))returnfalse;// 同一层或更低层可以依赖returntgtLayersrcLayer1;}}源模块允许依赖禁止依赖原因pagescomponents, repositoryprovider, promptUI 层不应直接操作 AIcomponentstheme, constantsservice, repository组件只关心展示repositorydatabase, modelpages, components数据层不依赖 UIserviceprovider, prompt, aipages, components服务层不感知 UI4.2 性能热点分析exportclassHotspotAnalyzer{staticanalyze():HotspotReport{return{hotspots:[{module:ChatBubble,issue:频繁 State 更新,suggestion:使用 LazyForEach 延迟渲染},{module:MarkdownView,issue:长文本解析,suggestion:增量渲染分块处理},{module:AIService,issue:API 串行调用,suggestion:合并请求批量处理},{module:OCRService,issue:大图解码,suggestion:预压缩异步处理}],recommendations:[使用虚拟列表优化长列表,图片上传前压缩到 1920px,流式输出添加 Throttle,AI 请求添加缓存层]};}}interfaceHotspotReport{hotspots:Array{module:string;issue:string;suggestion:string;};recommendations:string[];}五、开发经验总结经验问题描述最佳实践状态管理State 数组更新不触发渲染使用展开运算符this.arr [...this.arr]路由跳转页面路径配置错误在 module.json5 中注册所有页面异步错误Promise 未 catch统一 ErrorHandler 全局捕获内存泄漏全局事件监听未清理在 aboutToDisappear 中取消监听权限申请运行时权限弹窗使用能力访问控制 atManager数据持久化关系型数据库外键使用 ON DELETE CASCADE// 最佳实践代码片段// 1. State 数组更新this.messages[...this.messages,newMessage];// 2. 统一错误处理try{awaitthis.aiService.chat(messages);}catch(error){constappErrorAIServiceErrorHandler.handle(error);ToastUtil.show(appError.message);}// 3. 生命周期清理aboutToDisappear():void{this.syncHelper.removeObserve(new_message,this.callback);clearInterval(this.timer);}七、开发者贡献指南7.1 如何参与项目# Fork 项目gitclone https://github.com/yourname/HarmonyAI.gitcdHarmonyAI# 创建功能分支gitcheckout-bfeat/new-feature# 开发完成后提交gitadd.gitcommit-mfeat(xxx): 新功能描述gitpush origin feat/new-feature# 创建 Pull Request贡献类型说明入门难度Bug 修复修复已知问题⭐新功能实现规划中的功能⭐⭐文档改进文档和注释⭐测试补充单元测试⭐⭐性能优化代码性能调优⭐⭐⭐Provider 扩展接入新 AI 模型⭐⭐7.2 代码规范// 文件命名大驼峰// ChatPage.ets ✓ chatPage.ets ✗// 类名大驼峰classAIService{}✓classai_service{}✗// 方法名小驼峰sendMessage(){}✓send_message(){}✗// 常量全大写下划线constAPI_BASE_URLhttps://api.example.com✓constapiBaseUrlhttps://api.example.com✗// 类型注解显式声明constcount:number42✓constcount42✗允许但不推荐// 错误处理统一 ErrorHandlertry{awaitapi();}catch(e){AIServiceErrorHandler.handle(e);}✓catch(e){console.error(e);}✗7.3 代码审查清单exportconstCODE_REVIEW_CHECKLIST[是否遵循分层架构UI/ViewModel/Repository/Service,是否使用了统一 AIService 而非直接调用 Provider,Prompt 是否放在 prompt/ 目录而非写死在代码中,是否有单元测试覆盖,是否处理了错误边界和异常情况,是否添加了必要的日志,是否有性能风险虚拟列表/缓存/压缩,是否符合 ArkTS/TypeScript 编码规范];开源项目的生命力在于社区贡献。欢迎提交 PR、Issue 和建议八、Git 提交gitadd.gitcommit-mdocs(review): 源码解析与项目复盘 - 六层架构回顾与数据统计 - 模块依赖分析与性能热点 - 开发经验与技术债务总结 - 36条代码规范与审查清单 - 贡献指南与参与方式 Co-Authored-By: AtomCode (deepseek-v4-flash) noreplyatomgit.comgittag v0.2.8总结本文完成了源码解析与项目复盘。核心要点六层架构UI → ViewModel → Repository → Service → Prompt → Provider数据统计15,000 行代码12 页面8 AI 能力架构优势解耦、可扩展、可维护改进方向单元测试、MCP、离线能力技术债务错误处理、状态管理、类型统一如果这篇文章对你有帮助欢迎点赞、收藏⭐、关注你的支持是我持续创作的动力六、项目亮点回顾6.1 核心技术亮点回顾整个 HarmonyAI 项目以下技术亮点值得特别提及统一 AIService 架构所有 AI 能力通过单一入口调用新增功能零侵入扩展多模型无缝切换OpenAI、DeepSeek、Qwen、智谱、豆包一键切换故障自动转移Prompt 版本管理独立模板引擎支持 A/B 测试和热加载持续优化闭环三级缓存体系内存 LRU 磁盘 Preferences 关系型数据库命中率超 90%玻璃拟态 UIbackdropBlur 毛玻璃效果Light/Dark/Auto 三模式平滑过渡安全区全局适配基于display.getDefaultDisplaySync().densityPixels的精确 px→vp 转换SVG 全矢量图标所有图标采用 SVG杜绝 emoji 渲染异常多端一致性能全面优化LazyForEach 虚拟列表、图片智能压缩、流式 Throttle1000 条消息流畅渲染6.2 工程实践亮点Git 语义化提交每个功能点独立 Commit28 个 Tag 清晰标记里程碑分层架构严格遵循UI/ViewModel/Repository/Service/Manager 职责清晰状态管理精细化AppStorage 全局共享安全区高度Consume/Provide 主题透传错误处理统一化标准化错误码用户友好提示可重试自动恢复SettingPage 完整实现模型切换、API Key 配置、缓存清除、数据导出一站式管理相关资源HarmonyOS 架构设计Clean ArchitectureMVVM 模式单元测试最佳实践HarmonyOS NEXT 开发文档ArkTS 语言规范设计模式工厂模式Semantic Versioning下一篇预告[30-HarmonyOSAI应用开发总结]—— 全系列30篇的终极总结回顾从项目初始化到上架发布的完整历程提炼最核心的开发经验与最佳实践。 
