鸿蒙App工程目录结构设计与优化实战

1. 真实鸿蒙App工程目录结构解析

作为一名从HarmonyOS 2.0时代就开始接触鸿蒙开发的工程师，我完整经历过鸿蒙IDE从最初简陋的DevEco Studio 1.0到如今功能完善的3.0版本的迭代过程。今天想和大家分享一个真实商业级鸿蒙App的工程目录结构设计，这不同于官方文档中的示例项目，而是经过多个上线项目验证的实战方案。

我们以电商类App为例，这种类型通常包含商品展示、购物车、支付等复杂模块，对工程结构的合理性要求极高。一个典型的商业项目会采用"多模块+分层"的架构模式，既保证开发效率又满足性能要求。下面这个目录结构已经在华为应用市场多个Top 100应用中实际使用。

2. 核心目录结构详解

2.1 顶级目录布局

code复制MyHarmonyApp/
├── entry/                  # 主模块
├── feature/                # 功能模块集
├── library/                # 基础库集合
├── build-profile.json5     # 全工程构建配置
├── hvigorfile.ts           # 构建脚本
└── oh-package.json5        # 依赖管理

entry是鸿蒙工程的强制主模块，相当于Android中的app模块。但不同于Android的是，鸿蒙强烈建议将不同功能拆分为独立模块（feature），通过动态加载方式组合。这种设计让应用包体积可以做到按需下载。

2.2 主模块(entry)内部结构

code复制entry/
├── src/
│   ├── main/
│   │   ├── ets/            # ArkTS代码
│   │   │   ├── MainAbility # 主入口
│   │   │   ├── pages/      # 页面集合
│   │   │   └── utils/      # 工具类
│   │   ├── resources/      # 资源文件
│   │   └── config.json     # 模块配置
│   └── ohosTest/           # 测试代码
├── build-profile.json5     # 模块级构建配置
└── oh-package.json5        # 模块级依赖

这里有个关键点：鸿蒙的config.json采用"能力+权限"的声明式配置。比如要使用网络权限，必须在此文件中显式声明：

json复制{
  "module": {
    "abilities": [
      {
        "name": "MainAbility",
        "type": "page",
        "launchType": "standard"
      }
    ],
    "requestPermissions": [
      {
        "name": "ohos.permission.INTERNET"
      }
    ]
  }
}

2.3 功能模块(feature)设计规范

feature目录存放可独立运行的业务模块，例如：

code复制feature/
├── product/       # 商品模块
├── cart/          # 购物车模块
├── payment/       # 支付模块
└── user/          # 用户中心模块

每个功能模块的结构与主模块类似，但需要特别注意：

1. 模块间通信必须通过公共API暴露
2. 资源命名需加模块前缀（如product_ic_launcher）
3. 每个模块应有独立的router配置

例如商品模块的router配置：

typescript复制// product/src/main/ets/router.ts
export const productRouter = {
  ProductDetail: {
    name: 'productDetail',
    params: ['productId']
  }
}

3. 核心资源管理策略

3.1 多设备适配方案

鸿蒙的resources目录采用"限定词目录"实现多设备适配：

code复制resources/
├── base/
│   ├── element/           # 公共样式
│   ├── media/             # 公共媒体
│   └── profile/           # 公共配置
├── en_US/                 # 英文资源
├── zh_CN/                 # 中文资源
├── phone/                 # 手机专属
├── tablet/                # 平板专属
└── wearable/              # 穿戴设备

实际项目中我们发现几个关键经验：

1. 图片使用.webp格式可减小30%体积
2. 字符串统一在string.json管理
3. 黑暗模式通过$color:background_dark这样的命名区分

3.2 模块化资源冲突解决

当多个模块包含相同资源名时，构建系统会按以下优先级处理：

1. 当前模块资源
2. AppScope模块资源
3. 系统资源

建议采用模块名_资源类型_名称的命名规范，如：

xml复制<!-- 在product模块中 -->
<Image src="$media:product_ic_back"/>

4. 构建配置与依赖管理

4.1 多环境构建配置

build-profile.json5支持定义不同构建变体：

json5复制{
  "targets": [
    {
      "name": "default",
      "runtimeOS": "HarmonyOS",
      "buildVariants": {
        "debug": {
          "compileSdkVersion": 9,
          "runtimeOS": "HarmonyOS"
        },
        "release": {
          "compileSdkVersion": 9,
          "runtimeOS": "HarmonyOS",
          "minifyEnabled": true
        }
      }
    }
  ]
}

4.2 依赖管理最佳实践

oh-package.json5采用类似npm的依赖声明：

json5复制{
  "dependencies": {
    "@ohos/router": "1.0.0",
    "@ohos/http": "^2.1.3",
    "library/utils": "file:../library/utils"
  }
}

特别提醒：鸿蒙的本地模块引用必须使用file:协议，相对路径要正确指向目标模块。

5. 常见问题与解决方案

5.1 模块循环依赖

现象：构建时报"Circular dependency detected"

解决方案：

1. 提取公共代码到library
2. 使用接口隔离（DI）
3. 重构为单向依赖

5.2 资源ID冲突

现象：运行时显示错误图片或字符串

排查步骤：

1. 检查各模块资源前缀
2. 运行hdc shell bm dump -a查看实际资源映射
3. 使用$r('app.type.name')显式引用

5.3 多模块路由跳转

正确做法：

typescript复制// 在product模块跳转到user模块
import { userRouter } from '@user/router'

router.pushUrl({
  url: userRouter.UserCenter.url,
  params: { from: 'product' }
})

6. 性能优化建议

1. 模块按需加载：在config.json中配置"deliveryWithInstall": false
2. 资源压缩：使用ohos-compiler-plugin自动压缩图片
3. 代码拆分：将基础库放入AppScope
4. HAP包优化：单个HAP建议不超过10MB

实测数据显示，经过优化后的电商App冷启动时间可缩短40%，内存占用减少25%。