企业官网建设流程全解析

052 — 鸿蒙 HAR 多模块工程实战：21 个模块的依赖治理之道

简介

随着业务规模的增长，将代码拆分到独立模块是保持项目可维护性的关键手段。MoneyTrack 工程由多达 21 个 HAR 模块组成，分为 common（通用工具层）、component（业务组件层）、feature（功能特性层）和 entry（应用入口层）四个层级。这套多模块架构的核心挑战在于依赖治理——如何避免循环依赖、如何控制依赖方向、如何确保各模块的独立可编译性。本章深入分析全模块的依赖关系拓扑和设计原则。

核心知识点

1. 模块命名规范

在大型多模块工程中，统一的命名规范是模块治理的第一步。MoneyTrack 遵循@moneytrack/<module-name>的命名格式：

• 通用模块：@moneytrack/lib-network、@moneytrack/lib-router、@moneytrack/lib-utils
• 领域模块：@moneytrack/bill-base、@moneytrack/asset-base
• 组件模块：@moneytrack/bill-card、@moneytrack/asset-card、@moneytrack/chart-widget
• 功能模块：@moneytrack/feature-bill、@moneytrack/feature-asset、@moneytrack/feature-statistics

命名规范遵循"范围 + 功能"的原则，既保证了全局唯一性，又让开发者一眼看出模块的职责归属。

2. 四层依赖拓扑

MoneyTrack 的 21 个模块严格遵循四层单向依赖架构，使用 mermaid 图可以直观展示：

依赖方向严格遵循entry → feature → component → common，common 层的 lib_utils 和 lib_config 处于最底层，不依赖任何其他模块。

3. HAR 创建与依赖配置

每个 HAR 模块通过oh-package.json5声明自身信息及其依赖：

{ "name": "@moneytrack/bill-base", "version": "1.0.0", "description": "账单位领域基础包，包含枚举、类型定义与数据模型", "main": "index.ets", "dependencies": { "@moneytrack/lib-utils": "^1.0.0", "@moneytrack/lib-config": "^1.0.0" } }

组件模块的依赖配置示例：

{ "name": "@moneytrack/bill-card", "version": "1.2.0", "description": "账单卡片组件库", "main": "index.ets", "dependencies": { "@moneytrack/bill-base": "^1.0.0", "@moneytrack/lib-network": "^2.0.0", "@moneytrack/lib-router": "^1.0.0", "@ohos/axios": "^2.0.0" } }

4. 循环依赖避免

多模块工程最大的敌人是循环依赖。MoneyTrack 的依赖准则是：

• 单向依赖：依赖方向严格从 entry → feature → component → common。
• common 层零依赖：所有 common 模块不依赖任何其他 HAR 包。
• 接口隔离：feature 层之间通过接口而非直接模块引用通信。
• 领域包下沉：bill_base 和 asset_base 放在 common 层，供上层的 UI 组件引用。

5. 构建配置优化

为了加速多模块的编译过程，可以在hvigor-config.json5中配置并行编译：

{ "parallel": { "enable": true, "maxCount": 4 }, "compile": { "incremental": true, "transform": { "parallel": true } } }

并行编译可以充分利用多核 CPU 的性能。在 21 个模块的工程中，合理配置 parallel 参数可以将全量编译时间缩短 40%~60%。此外，推荐开启增量编译（incremental），这样修改单个模块后只需重新编译该模块及其直接依赖，避免全量重编。

常见问题：模块引用不到的问题排查

当遇到模块引用不到的问题时，可以按以下步骤排查：

1. 检查命名空间：确保引用路径与oh-package.json5中name字段一致，例如@moneytrack/bill-base而非相对路径。
2. 检查依赖声明：确认当前模块的oh-package.json5的dependencies中已声明目标模块。
3. 检查模块注册：确认build-profile.json5的modules数组中已注册目标模块，且其srcPath路径正确。
4. 检查目录结构：确认模块的src/main/ets目录下存在index.ets导出入口文件。
5. 重新同步依赖：执行ohpm install重新同步依赖关系，然后清理构建缓存（删除build目录）重试。

项目代码案例

文件路径：build-profile.json5（模块注册）

{ "modules": [ { "name": "entry", "srcPath": "./entry", "targets": ["hap"] }, { "name": "lib_network", "srcPath": "./lib_network", "targets": ["har"] }, { "name": "lib_router", "srcPath": "./lib_router", "targets": ["har"] }, { "name": "bill_base", "srcPath": "./bill_base", "targets": ["har"] }, { "name": "asset_base", "srcPath": "./asset_base", "targets": ["har"] }, { "name": "component_bill_card", "srcPath": "./component_bill_card", "targets": ["har"] }, { "name": "component_asset_card", "srcPath": "./component_asset_card", "targets": ["har"] }, { "name": "feature_bill", "srcPath": "./feature_bill", "targets": ["hap"] }, { "name": "feature_asset", "srcPath": "./feature_asset", "targets": ["hap"] } // ... 共 21 个模块 ] }

通过四层单向依赖拓扑、统一的命名规范和并行构建优化，MoneyTrack 的 21 个模块实现了高效可控的依赖治理，为持续迭代奠定了坚实的架构基础。

推荐参考文档

• HAR 包开发指南
• 多模块架构设计模式
• ohpm 依赖管理文档