一、为什么需要应用架构？

很多刚开始学习鸿蒙的开发者都有一个疑问：

为什么官方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？

官方推荐将公共能力封装为HAR（HarmonyOS 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 ↓ Network

UI 不直接请求网络，所有数据通过 ViewModel 与 Repository 流转。

八、Repository 模式

Repository 的作用：

统一数据入口

无论数据来自：

网络 数据库 缓存 文件

页面始终调用：

Repository

这样：

以后切换数据来源 UI不用改

九、状态管理原则

建议：

@State 页面状态

@Observed 对象状态

@ObjectLink 子组件共享

AppStorage 全局配置

PersistentStorage 持久化

做到：

页面只负责展示，状态统一管理，避免状态分散导致维护困难。

十、总结

HarmonyOS 企业级架构的核心可以概括为：

• 分层架构：产品层 → 基础特性层 → 公共能力层。
• 模块化设计：业务拆分为独立 Feature，公共能力沉淀为 HAR。
• 高内聚、低耦合：模块职责单一，通过接口通信。
• 数据流清晰：UI → ViewModel → Repository → DataSource → Network。
• 状态管理统一：合理使用 ArkUI 状态装饰器，避免数据混乱。
• 多端适配：同一套架构支持手机、平板、折叠屏、PC 等多设备形态。

这只是第一部分（约3000+ 字）。如果扩展成2 万字 CSDN 系列，后续还可以继续深入：

1. 分层架构源码实战（3000字）
2. HAR 模块化最佳实践（2500字）
3. MVVM + Repository 企业级实现（3000字）
4. 网络层封装（Axios/HttpClient）（2500字）
5. Router 与 Navigation 架构设计（2500字）
6. 状态管理最佳实践（2500字）
7. 企业商城项目完整架构案例（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 EmptyView

common-network

负责：

Http Interceptor Token Retry Log Upload Download

common-storage

负责：

Preferences Database MMKV Cache

common-router

负责：

Navigation NavPathStack Router DeepLink

common-utils

负责：

Date String Color File Json Encrypt

每个模块只做自己的事情。

十五、页面应该有多"瘦"？

企业开发有一句经典的话：

页面越瘦越好。

什么意思？

例如：

很多新手这样写：

Button.onClick(() => { 请求网络 保存数据库 判断登录 Toast Loading 更新UI })

一个点击事件几百行。

这是最典型的问题。

推荐：

Page ↓ ViewModel.login()

页面：

只负责：

显示 点击 刷新

其它事情：

全部交给 ViewModel。

十六、ViewModel 应该负责什么？

ViewModel 是：

UI 和 Repository 中间层。

例如：

Page ↓ ViewModel ↓ Repository

ViewModel：

负责：

参数校验 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 UserRemoteDataSource

Repository：

负责：

协调。

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 UI）
• ViewModel 的职责边界
• Repository + DataSource 分层设计
• 企业级网络层封装
• 全局异常统一处理

下一章将继续深入《HarmonyOS 模块化（HAR/HSP）架构设计与大型项目拆分》，详细讲解：

• HAR 与 HSP 的区别
• 模块依赖原则
• 跨模块通信
• 模块版本管理
• 企业级组件库设计
• 多团队协作架构实践
• 大型项目目录优化与编译加速技巧

继续

二十三、HarmonyOS 模块化架构设计（HAR / HSP 深度解析）

前面我们已经介绍了企业级应用整体架构，本章开始深入讲解HarmonyOS 模块化设计。

对于一个只有十几个页面的小项目来说，所有代码放在entry中问题并不大。但当项目规模达到：

• 100+ 页面
• 20+ 开发人员
• 数十万行代码
• 多端（手机、平板、折叠屏）共用

如果仍然采用单 Module 开发，项目将很快陷入维护困难、编译缓慢、代码耦合严重的问题。

因此，HarmonyOS 官方推荐采用模块化（Modular Architecture）。

二十四、为什么要模块化？

很多开发者刚开始都会问：

一个 App 为什么要拆成几十个 Module？

例如一个商城项目：

首页 分类 搜索 购物车 订单 支付 登录 消息 客服 活动 优惠券 积分

如果全部放到一个 Module：

entry │ ├── pages ├── components ├── utils ├── api ├── model ├── network └── ...

半年之后：

entry ↓ 500多个Page ↓ 1000多个ArkTS文件 ↓ 几十万行代码

最终会出现：

• 编译越来越慢
• Merge 冲突频繁
• 页面之间互相依赖
• 修改一个模块影响整个项目
• 新成员学习成本极高

因此，模块化几乎是大型 HarmonyOS 项目的必选项。

二十五、HarmonyOS Module 类型

HarmonyOS 工程中常见的模块类型包括：

Entry HAR HSP Static Library（部分场景）

企业项目最常用的是前三种。

1、Entry

Entry 是应用入口模块。

例如：

entry

主要职责：

Ability 启动页面 初始化SDK 初始化Router 初始化日志 初始化数据库 应用生命周期

原则：

Entry 不写业务。

它更像是整个应用的“启动器”。

2、HAR（Harmony Archive）

HAR 是 HarmonyOS 官方推荐的共享代码模块。

可以理解成：

Android Library ↓ Harmony HAR

例如：

common-ui.har common-network.har common-storage.har common-utils.har

所有 Feature 都可以依赖这些 HAR。

例如：

feature-order ↓ common-network.har

feature-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

造成大量重复代码。

二十七、HSP（Harmony Shared Package）

相比 HAR，HSP 更适合：

大型业务能力共享。

例如：

支付 IM 直播 地图 音视频

这些模块：

代码量巨大。

可能：

几十个页面 几百个类 几万个函数

如果仍然做成 HAR：

维护成本很高。

于是：

官方增加：

HSP

它更适合：

大型业务模块共享。

例如：

feature-live.hsp feature-pay.hsp feature-chat.hsp

多个 App：

都可以直接使用。

二十八、HAR 与 HSP 的区别

企业项目通常是：

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

这种循环依赖会导致项目复杂度急剧上升。