鸿蒙应用推荐使用的”三层工程结构”

在鸿蒙应用开发中，为了实现代码的高内聚、低耦合以及更好的可维护性和可扩展性，官方推荐采用”三层工程结构”的设计模式。这种架构能够帮助开发者更好地组织代码，提升开发效率。

三层工程结构概览

三层工程结构从下至上分为：

1. commons（公共能力层）
2. features（基础特性层）
3. products（产品定制层）

┌─────────────────────────────────────┐
│         products (产品定制层)        │  ← Entry HAP
├─────────────────────────────────────┤
│         features (基础特性层)        │  ← Feature HAP / HAR / HSP
├─────────────────────────────────────┤
│         commons (公共能力层)         │  ← HAR / HSP
└─────────────────────────────────────┘

commons（公共能力层）

定位与职责

commons 层用于存放公共基础能力集合，包括但不限于：

• 工具库（utils、helpers）
• 公共配置
• 基础数据模型
• 通用 UI 组件
• 网络请求封装
• 本地存储封装

编译产物

commons 层可编译成一个或多个：

• HAR包（Harmony Archive）
• HSP包（Harmony Shared Package）

依赖规则

✅ 可以被依赖：products 层、features 层

❌ 不可以反向依赖：commons 层不能依赖 features 层或 products 层

典型目录结构

commons/
├── utils/              # 工具函数
│   ├── logger.ets
│   ├── dateUtil.ets
│   └── validators.ets
├── network/            # 网络封装
│   └── httpClient.ets
├── storage/            # 存储封装
│   └── preferences.ets
├── models/             # 公共数据模型
│   └── baseModel.ets
└── components/         # 公共组件
    └── button.ets

features（基础特性层）

定位与职责

features层用于存放基础特性集合，通常包含：

• 应用中相对独立的各个功能模块的 UI 界面及业务逻辑实现
• 特定领域的功能实现

设计原则

各个feature应当：

• 高内聚：功能相关的代码集中在一起
• 低耦合：模块间依赖关系清晰且最小化
• 可定制：支持灵活的配置和扩展

编译产物

根据是否需要单独部署，features层可以编译为：

场景	编译产物	说明
不需要单独部署	HAR包 / HSP包	供products或其他feature使用
需要单独部署	Feature类型的HAP包	与products的Entry HAP组合部署

依赖规则

✅ 可以横向调用：features 层之间可以相互依赖

✅ 可以依赖 commons 层：可以使用公共能力

❌ 不能依赖 products 层：保持向下依赖的单向性

典型目录结构

features/
├── userCenter/         # 用户中心功能
│   ├── src/main/ets/
│   │   ├── pages/
│   │   ├── viewmodels/
│   │   └── services/
│   └── build-profile.json5
├── shoppingCart/       # 购物车功能
│   ├── src/main/ets/
│   │   ├── pages/
│   │   └── components/
│   └── build-profile.json5
└── payment/            # 支付功能
    ├── src/main/ets/
    └── build-profile.json5

products（产品定制层）

定位与职责

products 层用于针对不同设备形态进行功能和特性集成，主要职责包括：

• 功能组合与集成
• 设备适配
• 作为应用的主入口点

编译产物

products 层的各个子目录各自编译为一个：

• Entry类型的HAP包（Harmony Ability Package）

这是应用的主入口包。

依赖规则

✅ 可以依赖features层：集成各个 feature 模块

✅ 可以依赖commons层：使用公共能力

❌ 不可以横向调用：products 层之间不能相互依赖

典型目录结构

products/
├── phone/              # 手机设备形态
│   ├── src/main/ets/
│   │   └── entryability/
│   ├── src/main/resources/
│   └── module.json5
├── tablet/             # 平板设备形态
│   ├── src/main/ets/
│   │   └── entryability/
│   ├── src/main/resources/
│   └── module.json5
└── wearable/           # 穿戴设备形态
    ├── src/main/ets/
    │   └── entryability/
    ├── src/main/resources/
    └── module.json5

依赖关系总结

graph TD
    P[products层] --> F[features层]
    P --> C[commons层]
    F --> F
    F --> C
    F -.->|禁止| P
    C -.->|禁止| F
    C -.->|禁止| P

    style P fill:#e1f5ff
    style F fill:#fff4e1
    style C fill:#f0f0f0

依赖规则一览表

层级	可被依赖	可依赖	横向调用
commons	✅ products, features	❌ 无	❌ 否
features	✅ products, features	✅ commons	✅ 是
products	❌ 无	✅ features, commons	❌ 否

三层架构的优势

1. 代码复用性强

• commons层的公共能力可以被多处复用
• 避免重复造轮子，提升开发效率

2. 职责清晰

• 每一层都有明确的职责边界
• 降低了代码的理解和维护成本

3. 灵活部署

• features层可以按需编译为HAP或HAR/HSP
• 支持功能的独立部署和动态加载

4. 团队协作友好

• 不同团队可以负责不同的feature模块
• 降低了代码冲突的风险

5. 易于测试

• 各层独立，便于单元测试和集成测试
• 依赖关系清晰，mock更简单

实践建议

1. 合理划分层级

• 不要将所有代码都放在commons层，避免过度抽象
• features层应保持相对独立，避免强耦合

2. 依赖管理

• 严格遵循单向依赖原则
• 避免循环依赖

3. 模块化设计

• 每个feature应该是一个完整的功能单元
• 考虑功能的可重用性和可扩展性

4. 接口设计

• commons层提供稳定的基础能力接口
• features层通过接口与commons交互

总结

鸿蒙应用的三层工程结构是一种经过实践验证的架构模式，通过合理的分层和依赖管理，能够帮助开发者构建高质量、易维护的应用程序。在实际开发中，应该根据项目特点和团队规模，灵活运用这一架构模式，充分发挥其优势。