【HarmonyOS】鸿蒙应用架构原则参考（HarmonyOS 5 企业级架构设计）

一、为什么需要应用架构很多刚开始学习鸿蒙的开发者都有一个疑问为什么官方Demo那么简单而企业项目却那么复杂例如一个商城APP首页 分类 购物车 订单 我的 消息 支付 登录如果全部写到一个Entry里面会出现entry pages Index Login Order Mine Home Cart ....随着项目越来越大代码越来越难维护 业务越来越混乱 重复代码越来越多 页面越来越臃肿 修改一个模块影响整个项目因此官方提出了分层 模块化 公共能力抽离这就是HarmonyOS官方推荐架构。二、HarmonyOS 官方推荐架构官方推荐的整体架构如下Product Layer 产品定制层 Home Mine Order Member Message ──────────────────────────── Feature Layer 基础业务层 User Goods Cart Order ──────────────────────────── Common Layer 公共能力层 Network Storage Log Router Utils Dialog Loading CommonUI整个项目可以理解成UI ↓ 业务 ↓ 公共能力 ↓ 系统API这种设计能够实现高内聚低耦合易维护易扩展易复用也是HarmonyOS官方模板推荐的组织方式。三、架构设计六大原则企业项目一般遵循以下六个原则。原则一高内聚一个模块只负责一件事情。例如UserModule 负责 登录 退出 修改头像 修改昵称 获取用户信息不要把支付 订单 首页 全部放进去原则二低耦合模块之间不要直接依赖。错误Home 直接调用 Mine里的变量正确Home ↓ Repository ↓ Network通过接口进行通信。原则三单一职责例如Network 只负责网络不要网络 缓存 登录 Toast 全部写里面原则四依赖倒置业务不要依赖具体实现。例如UserRepository ↓ IUserApi ↓ Http实现以后Mock 测试 正式服务器都可以替换。原则五模块独立官方建议首页 一个HAR 订单 一个HAR 购物车 一个HAR互不影响。原则六公共能力统一管理例如Toast Dialog Loading Log Storage Network Utils全部放Common。不要首页一个Toast 我的一个Toast 订单一个Toast四、官方推荐三层架构官方推荐的应用架构主要分为三层第一层产品定制层Product Layer负责最终面向用户的页面和交互是应用入口可根据设备形态手机、平板、PC等进行差异化定制。例如Home Mine Order Message Setting特点只负责页面 不写业务 调用Feature第二层基础特性层Feature Layer负责独立业务能力。例如商品 订单 支付 登录 搜索这一层具有高内聚 低耦合 可拆分 可组合每个业务模块都可以独立维护。第三层公共能力层Common Layer放所有公共代码例如网络 日志 缓存 工具类 Dialog Loading Router 公共组件特点所有业务共享 禁止业务逻辑五、企业级目录结构推荐App │ ├── entry │ ├── feature_home │ ├── feature_order │ ├── feature_cart │ ├── feature_user │ ├── feature_login │ ├── feature_message │ ├── common_base │ ├── common_network │ ├── common_storage │ ├── common_ui │ ├── common_router │ ├── common_utils │ └── common_log这种目录结构非常适合大型 HarmonyOS 项目便于团队协作和模块复用。六、为什么推荐使用 HAR官方推荐将公共能力封装为HARHarmonyOS Archive例如common-network.har common-ui.har common-log.har common-storage.har优点所有业务模块共享降低重复代码独立维护方便版本升级提高编译效率七、MVVM 在 HarmonyOS 中的实践推荐分层Page(UI) ↓ ViewModel ↓ Repository ↓ RemoteDataSource ↓ Network ↓ Server职责清晰UI ↓ ViewModel ↓ Repository ↓ NetworkUI 不直接请求网络所有数据通过 ViewModel 与 Repository 流转。八、Repository 模式Repository 的作用统一数据入口无论数据来自网络 数据库 缓存 文件页面始终调用Repository这样以后切换数据来源 UI不用改九、状态管理原则建议State 页面状态Observed 对象状态ObjectLink 子组件共享AppStorage 全局配置PersistentStorage 持久化做到页面只负责展示状态统一管理避免状态分散导致维护困难。十、总结HarmonyOS 企业级架构的核心可以概括为分层架构产品层 → 基础特性层 → 公共能力层。模块化设计业务拆分为独立 Feature公共能力沉淀为 HAR。高内聚、低耦合模块职责单一通过接口通信。数据流清晰UI → ViewModel → Repository → DataSource → Network。状态管理统一合理使用 ArkUI 状态装饰器避免数据混乱。多端适配同一套架构支持手机、平板、折叠屏、PC 等多设备形态。这只是第一部分约3000 字。如果扩展成2 万字 CSDN 系列后续还可以继续深入分层架构源码实战3000字HAR 模块化最佳实践2500字MVVM Repository 企业级实现3000字网络层封装Axios/HttpClient2500字Router 与 Navigation 架构设计2500字状态管理最佳实践2500字企业商城项目完整架构案例4000字继续十一、HarmonyOS 企业级架构实战商城项目案例前面介绍了官方推荐的三层架构那么在真实企业项目中应该如何落地下面以一个商城 App为例讲解 HarmonyOS 企业级架构设计。1、项目整体结构一个中大型商城项目一般不会只有一个entry模块而是由多个 Feature Common 模块组成。MallApp │ ├── AppScope │ ├── entry // 应用入口 │ ├── feature-home // 首页 │ ├── feature-category // 分类 │ ├── feature-cart // 购物车 │ ├── feature-order // 订单 │ ├── feature-user // 我的 │ ├── feature-login // 登录 │ ├── feature-pay // 支付 │ ├── feature-search // 搜索 │ ├── common-base // 基础能力 │ ├── common-network // 网络库 │ ├── common-router // 路由 │ ├── common-storage // 本地存储 │ ├── common-ui // UI组件 │ ├── common-dialog // Dialog │ ├── common-utils // 工具类 │ ├── common-log // 日志 │ └── common-http-api // API定义整个项目几乎所有大型互联网公司都会按照类似方式进行拆分。这样做最大的优点就是模块职责清晰编译速度快团队多人开发互不影响公共代码统一维护十二、Entry 为什么越简单越好很多初学者喜欢把所有代码都放到 Entry。例如entry pages Home Mine Order Cart Login Setting随着项目越来越大entry ↓↓↓ 300多个页面 ↓↓↓ 几百M代码 ↓↓↓ 每次编译几十秒这是官方并不推荐的。正确做法Entry 只负责启动APP 初始化SDK 初始化Router 初始化日志 初始化网络 初始化数据库 加载首页除此之外不负责任何业务。例如Application ↓ 初始化 ↓ 跳转首页 ↓ 结束真正业务全部交给 Feature。十三、Feature 模块应该如何设计官方建议一个 Feature 就代表一个业务。例如feature-order里面只有订单相关内容pages viewmodel repository api bean component utils例如feature-order │ ├── pages ├── viewmodel ├── repository ├── api ├── model ├── component └── utils不要feature-order ↓ 支付 ↓ 登录 ↓ 首页 ↓ 消息 全部塞进去这样后期维护十分困难。十四、Common 模块如何拆很多人把 Common 做成一个巨大的模块。最后common 300多个类 200多个工具 几十万个代码最后没人敢改。正确做法继续拆。例如common-ui负责Button Loading Dialog TitleBar TabBar EmptyViewcommon-network负责Http Interceptor Token Retry Log Upload Downloadcommon-storage负责Preferences Database MMKV Cachecommon-router负责Navigation NavPathStack Router DeepLinkcommon-utils负责Date String Color File Json Encrypt每个模块只做自己的事情。十五、页面应该有多瘦企业开发有一句经典的话页面越瘦越好。什么意思例如很多新手这样写Button.onClick(() { 请求网络 保存数据库 判断登录 Toast Loading 更新UI })一个点击事件几百行。这是最典型的问题。推荐Page ↓ ViewModel.login()页面只负责显示 点击 刷新其它事情全部交给 ViewModel。十六、ViewModel 应该负责什么ViewModel 是UI 和 Repository 中间层。例如Page ↓ ViewModel ↓ RepositoryViewModel负责参数校验 Loading 业务组合 状态更新 异常处理例如登录输入账号 ↓ 输入密码 ↓ ViewModel ↓ Repository.login() ↓ 更新UI页面不知道网络。页面不知道数据库。页面只知道登录成功 登录失败即可。十七、Repository 为什么越来越流行以前页面请求接口 ↓ 解析JSON ↓ 更新UI后来越来越多人发现如果以后接口改了 数据库改了 缓存改了所有页面都要修改。于是Google提出Repository。例如Repository ↓ 决定数据来源它可以先查缓存 ↓ 没有 ↓ 查数据库 ↓ 没有 ↓ 请求网络 ↓ 保存缓存 ↓ 返回UI页面根本不知道。页面只会repository.getUser()结束。十八、Repository 最佳结构例如repository │ ├── UserRepository ├── OrderRepository ├── GoodsRepository ├── CartRepository └── PayRepository每个 Repository对应一个业务。例如OrderRepository只负责订单列表 订单详情 取消订单 确认收货 删除订单不要订单 ↓ 登录 ↓ 首页 ↓ 支付 ↓ 消息 全部写进去十九、DataSource 再拆一层大型项目Repository 下面还会继续拆。例如Repository ↓ LocalDataSource ↓ RemoteDataSource例如UserRepository ↓ UserLocalDataSource UserRemoteDataSourceRepository负责协调。Remote负责服务器。Local负责数据库。这样以后换数据库Repository不用改。换接口UI不用改。二十、一个完整的数据流HarmonyOS 推荐的数据流如下Button Click ↓ Page ↓ ViewModel ↓ Repository ↓ RemoteDataSource ↓ Http ↓ Server ↓ Json ↓ Repository ↓ ViewModel ↓ UI刷新如果增加缓存Repository ↓ Local ↓ Remote ↓ Cache ↓ UI整个流程十分清晰。二十一、网络层应该如何设计企业开发中绝不能在页面直接请求网络。推荐统一封装HttpClient ↓ Interceptor ↓ Token ↓ Api ↓ Repository例如Network │ ├── HttpClient ├── BaseResponse ├── ApiService ├── Upload ├── Download ├── Retry ├── Logger ├── Exception └── Interceptor页面永远不知道Http只知道Repository二十二、统一错误处理不要每个页面try catch Toast推荐统一Http ↓ Interceptor ↓ 统一异常 ↓ 统一Toast ↓ 统一登录失效例如服务器401自动跳登录页面不用处理。本章总结本章完成了 HarmonyOS 企业级架构落地实践的第一部分重点介绍了企业商城项目整体模块划分Entry、Feature、Common 的职责划分页面瘦身原则Thin UIViewModel 的职责边界Repository DataSource 分层设计企业级网络层封装全局异常统一处理下一章将继续深入《HarmonyOS 模块化HAR/HSP架构设计与大型项目拆分》详细讲解HAR 与 HSP 的区别模块依赖原则跨模块通信模块版本管理企业级组件库设计多团队协作架构实践大型项目目录优化与编译加速技巧继续二十三、HarmonyOS 模块化架构设计HAR / HSP 深度解析前面我们已经介绍了企业级应用整体架构本章开始深入讲解HarmonyOS 模块化设计。对于一个只有十几个页面的小项目来说所有代码放在entry中问题并不大。但当项目规模达到100 页面20 开发人员数十万行代码多端手机、平板、折叠屏共用如果仍然采用单 Module 开发项目将很快陷入维护困难、编译缓慢、代码耦合严重的问题。因此HarmonyOS 官方推荐采用模块化Modular Architecture。二十四、为什么要模块化很多开发者刚开始都会问一个 App 为什么要拆成几十个 Module例如一个商城项目首页 分类 搜索 购物车 订单 支付 登录 消息 客服 活动 优惠券 积分如果全部放到一个 Moduleentry │ ├── pages ├── components ├── utils ├── api ├── model ├── network └── ...半年之后entry ↓ 500多个Page ↓ 1000多个ArkTS文件 ↓ 几十万行代码最终会出现编译越来越慢Merge 冲突频繁页面之间互相依赖修改一个模块影响整个项目新成员学习成本极高因此模块化几乎是大型 HarmonyOS 项目的必选项。二十五、HarmonyOS Module 类型HarmonyOS 工程中常见的模块类型包括Entry HAR HSP Static Library部分场景企业项目最常用的是前三种。1、EntryEntry 是应用入口模块。例如entry主要职责Ability 启动页面 初始化SDK 初始化Router 初始化日志 初始化数据库 应用生命周期原则Entry 不写业务。它更像是整个应用的“启动器”。2、HARHarmony ArchiveHAR 是 HarmonyOS 官方推荐的共享代码模块。可以理解成Android Library ↓ Harmony HAR例如common-ui.har common-network.har common-storage.har common-utils.har所有 Feature 都可以依赖这些 HAR。例如feature-order ↓ common-network.harfeature-home ↓ common-network.har整个项目只维护一套网络库。二十六、HAR 的特点HAR 最大优势就是公共能力复用。例如Toast Dialog Loading Http Log Storage全部封装到common-ui.har common-network.har以后任何业务模块feature-user feature-order feature-cart都可以直接引用。这样可以避免订单一套Toast 首页一套Toast 我的一套Toast造成大量重复代码。二十七、HSPHarmony Shared Package相比 HARHSP 更适合大型业务能力共享。例如支付 IM 直播 地图 音视频这些模块代码量巨大。可能几十个页面 几百个类 几万个函数如果仍然做成 HAR维护成本很高。于是官方增加HSP它更适合大型业务模块共享。例如feature-live.hsp feature-pay.hsp feature-chat.hsp多个 App都可以直接使用。二十八、HAR 与 HSP 的区别对比项HARHSP主要用途公共能力复用大型业务能力共享典型内容UI、工具、网络、存储支付、聊天、直播、地图代码规模小到中等中大型是否适合业务模块一般不建议推荐维护方式公共团队维护独立业务团队维护企业项目通常是Entry ↓ Feature ↓ HAR ↓ HSP ↓ System API二十九、Feature 是否可以互相依赖很多新人会这样设计feature-home ↓ 调用 ↓ feature-order或者feature-order ↓ 调用 ↓ feature-user这样会导致循环依赖例如Home ↓ Order ↓ User ↓ Home最后整个项目编译失败或者模块无法拆分官方推荐Feature 之间不要直接依赖。正确方式Feature ↓ Repository ↓ Common ↓ System如果两个模块都需要用户信息。应该feature-home ↓ UserRepository ↓ common-user而不是feature-home ↓ feature-user三十、模块之间如何通信企业开发中经常需要例如首页点击商品通知购物车更新数量。很多新人直接import CartPage然后CartPage.refresh()这是非常错误的设计。正确方案有以下几种方案一Repository适用于共享数据例如用户信息 订单数据 购物车数据所有模块统一访问 Repository。方案二EventHub适用于发送通知例如登录成功 退出登录 购物车更新 主题切换特点松耦合无需互相引用官方推荐事件机制方案三AppStorage适用于全局状态例如DarkMode Language Theme LoginState页面自动刷新。方案四Router 返回结果例如支付页面 ↓ 支付成功 ↓ 返回订单通过路由返回数据。三十一、企业项目如何划分公共模块建议按能力拆分而不是按技术拆分。推荐目录common-base │ ├── BaseAbility ├── BaseViewModel ├── BaseRepository └── BasePage common-network │ ├── HttpClient ├── ApiService ├── Interceptor ├── Upload ├── Download └── Retry common-storage │ ├── Preferences ├── Database ├── KVStore └── CacheManager common-ui │ ├── Dialog ├── Loading ├── EmptyView ├── TitleBar ├── NavigationBar └── Popup common-router │ ├── NavManager ├── RouterUtils ├── DeepLink └── RouteConfig common-utils │ ├── DateUtils ├── StringUtils ├── JsonUtils ├── FileUtils ├── EncryptUtils └── DeviceUtils这样每个模块边界清晰维护方便。三十二、模块依赖原则重点大型项目一定要遵循单向依赖原则Entry │ ▼ Feature Module │ ▼ Common Module │ ▼ System API禁止出现Common ↓ 依赖 ↓ Feature因为公共模块应该保持独立不应包含任何业务逻辑。同样也应避免Feature A ↓ Feature B ↓ Feature C ↓ Feature A这种循环依赖会导致项目复杂度急剧上升。