HarmonyOS掌上记账APP开发实践第52篇：鸿蒙 HAR 多模块工程实战：21 个模块的依赖治理之道

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 图可以直观展示Layer 1: CommonLayer 2: ComponentLayer 3: FeatureLayer 4: Entryentry - 应用入口feature_billfeature_assetfeature_statisticsfeature_settingsfeature_feedbackfeature_membershipfeature_logincomponent_bill_cardcomponent_asset_cardcomponent_chart_widgetcomponent_formlib_networklib_routerlib_utilslib_storagelib_loggerlib_configlib_analyticslib_i18nbill_baseasset_base依赖方向严格遵循entry → feature → component → commoncommon 层的 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这样修改单个模块后只需重新编译该模块及其直接依赖避免全量重编。常见问题模块引用不到的问题排查当遇到模块引用不到的问题时可以按以下步骤排查检查命名空间确保引用路径与oh-package.json5中name字段一致例如moneytrack/bill-base而非相对路径。检查依赖声明确认当前模块的oh-package.json5的dependencies中已声明目标模块。检查模块注册确认build-profile.json5的modules数组中已注册目标模块且其srcPath路径正确。检查目录结构确认模块的src/main/ets目录下存在index.ets导出入口文件。重新同步依赖执行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 依赖管理文档