摘要

前文已完成全套底层工具、通用 UI 组件、业务能力封装：网络、数据库、存储、路由、弹窗、权限、图片、文件、日志、状态管理、主题、列表分页、空状态组件。本章整合所有模块，输出一套可直接用于课程设计、毕业设计、商用 APP 的标准分层工程架构，明确 entry、基础 HAR、业务 HAR、动态 HSP 分包依赖规则、目录划分、模块职责、编译约束、团队协作规范、打包发布流程，解决多模块循环依赖、资源冲突、分包体积过大、代码复用混乱、多人开发合并冲突等核心工程问题。

关键词

OpenHarmony；API23；工程分层；HAR；HSP；模块化；架构规范；多模块协作

一、整体架构分层（四层单向依赖，禁止反向 / 循环依赖）

依赖流向规则（强制单向）

页面 / HSP → 业务 HAR → 底层基础 har_base → 无依赖

1. 第一层：entry（主应用入口模块，唯一可安装运行）
   • 职责：应用生命周期、全局初始化、首页 / 登录 / 设置常驻页面、路由拦截、全局状态初始化、HSP 加载调度、APP 退出逻辑
   • 禁止：复杂业务逻辑、大量独立页面、数据库封装、网络工具
2. 第二层：基础静态 HAR har_base（全局公共底层库，所有模块共享）
   • 职责：全部通用工具、全局类型、主题常量、通用 UI 基础组件、全局模型定义
   • 依赖：无任何其他 HAR/HSP，纯净底层
   • 包含前文所有工具：HttpUtil、RdbUtil、PrefUtil、RouterUtil、DialogUtil、PermissionUtil、ImagePickerUtil、FileUtil、LogUtil、GlobalStore、ThemeUtil
   • 通用组件：StateView、RefreshListView、基础弹窗、通用按钮 / 卡片 Builder
3. 第三层：业务静态 HAR（har_xxx，独立业务静态复用模块）
   • 示例：har_user（用户相关）、har_note（笔记业务）、har_message（消息）
   • 职责：独立业务数据库封装、业务实体、业务专用组件、业务 CRUD 逻辑
   • 仅允许依赖：har_base，业务 HAR 之间禁止互相依赖
4. 第四层：动态分包 HSP（hsp_xxx，低频大业务按需加载）
   • 示例：hsp_album 相册、hsp_editor 笔记编辑器、hsp_mall 商城
   • 职责：低频、体积大、非核心业务完整页面与业务逻辑
   • 仅允许依赖：har_base + 对应业务 HAR；HSP 之间禁止互相依赖、禁止静态 import 导入 HSP 内部代码

完整工程目录树

plaintext

ProjectRoot
├─ entry（主应用层）
│  └─ src/main/ets
│     ├─ pages          # 常驻页面：首页、登录、设置、个人中心
│     ├─ entryability   # 全局初始化入口
│     ├─ utils          # entry专属工具：Hsp加载封装、启动逻辑
│     └─ resources      # 全局公共图片、字体、静态资源
├─ har_base（底层公共静态库，核心基础层）
│  └─ src/main/ets
│     ├─ utils          # 全套底层工具类
│     ├─ model          # 全局类型、常量、路由key、主题定义
│     ├─ components     # 全局通用UI组件 StateView/RefreshListView等
│     └─ resources      # 通用图标、配色资源
├─ har_note（笔记业务静态HAR）
│  └─ src/main/ets
│     ├─ model          # 笔记业务实体
│     ├─ db             # 笔记RDB数据库操作
│     ├─ components     # 笔记专用卡片、条目组件
│     └─ logic          # 笔记业务逻辑
├─ har_user（用户业务静态HAR）
│  └─ src/main/ets
│     ├─ model
│     ├─ logic          # 登录、用户信息、头像上传逻辑
│     └─ components
├─ hsp_note_editor（笔记编辑器动态分包）
│  └─ src/main/ets
│     ├─ pages          # 编辑器完整页面
│     ├─ logic          # 富文本编辑业务逻辑
│     └─ components     # 编辑器专属UI
└─ build-profile.json5  # 模块依赖配置、打包配置

二、各模块详细职责边界规范

2.1 entry 主模块规范

允许存放

1. EntryAbility 应用全局初始化：工具上下文注入、日志等级、持久化状态绑定
2. 核心常驻页面：首页、登录、设置、个人中心（必须登录才能进入的基础页面）
3. HSP 动态加载调度工具、路由入口拦截逻辑
4. APP 全局生命周期：前后台切换、退出清理缓存、释放数据库 / 文件句柄
5. 应用全局资源：启动页图片、应用 logo、全局字体

严格禁止

1. 封装网络、数据库、文件等底层工具（统一放入 har_base）
2. 独立完整业务页面（编辑器、相册、笔记详情拆分至 HSP / 业务 HAR）
3. 业务数据库 CRUD、复杂业务逻辑（下沉至对应 har_xxx 业务库）
4. 自定义通用基础组件（StateView、弹窗等统一 har_base/components）

2.2 har_base 基础公共库规范

允许存放

1. 全部底层工具类（前文所有 utils 工具集合）
2. 全局通用 interface、类型定义、常量、路由地址、全局状态 key、主题色值
3. 无业务耦合的通用 UI 组件：加载视图、空页面、下拉分页列表、通用弹窗、权限弹窗
4. 全局基础资源：通用空白图标、失败图标、通用按钮样式

严格禁止

1. 任何业务相关代码：笔记、用户、商城等业务实体、业务数据库
2. 页面 pages 注册（HAR 不支持页面路由）
3. 业务专属组件：笔记条目、用户头像卡片（放入对应业务 HAR）

2.3 har_xxx 业务静态 HAR 规范

允许存放

1. 单一业务域数据模型、数据表建表 SQL、RDB 封装
2. 该业务专属 UI 组件（笔记列表项、用户信息卡片）
3. 该业务独立接口请求封装、业务专属工具方法
4. 业务专用资源：笔记图标、头像相关素材

严格禁止

1. 页面 pages 页面（页面统一放 entry 或 HSP）
2. 跨业务逻辑（用户 HAR 禁止操作笔记数据库）
3. 依赖其他业务 HAR（仅允许依赖 har_base）

2.4 hsp_xxx 动态分包规范

允许存放

1. 低频大体积完整业务页面
2. 该分包专属复杂业务逻辑、重型组件（富文本、图片编辑）
3. 分包私有资源，不与全局共用

严格禁止

1. 全局底层工具、通用基础组件（统一引用 har_base）
2. 其他 HSP 模块导入、依赖
3. 核心高频页面（首页、登录不允许拆 HSP）
4. 直接 import 其他 HSP 内部 ets 代码，必须使用 hspManager 动态加载跳转

三、模块依赖配置标准模板 module.json5

3.1 har_base（无任何依赖）

json

{
  "module": {
    "name": "har_base",
    "type": "har",
    "description": "全局底层公共工具与通用组件",
    "deviceTypes": ["phone"],
    "deliveryWithInstall": false
  },
  "dependencies": []
}

3.2 业务 HAR har_note（仅依赖 har_base）

json

"dependencies": [
  {
    "name": "har_base",
    "version": "1.0.0",
    "scope": "shared"
  }
]

3.3 HSP 动态分包 hsp_note_editor（依赖 har_base+har_note）

json

"dependencies": [
  {
    "name": "har_base",
    "version": "1.0.0",
    "scope": "shared"
  },
  {
    "name": "har_note",
    "version": "1.0.0",
    "scope": "shared"
  }
]

3.4 entry 主模块（依赖所有 HAR、HSP）

json

"dependencies": [
  {"name":"har_base","version":"1.0.0","scope":"shared"},
  {"name":"har_note","version":"1.0.0","scope":"shared"},
  {"name":"har_user","version":"1.0.0","scope":"shared"},
  {"name":"hsp_note_editor","version":"1.0.0","scope":"shared"}
]

四、跨模块导入标准写法规范

4.1 entry / HAR 导入 har_base 工具 / 组件

ets

// 导入工具
import HttpUtil from '@ohos:har_base/utils/http_util'
// 导入全局类型
import { PAGE_ROUTE } from '@ohos:har_base/model/Constant'
// 导入通用组件
import StateView, { PageState } from '@ohos:har_base/components/common/StateView'

4.2 HSP 导入业务 HAR 笔记数据库工具

ets

import RdbUtil from '@ohos:har_note/db/rdb_util'

4.3 HSP 页面跳转（entry 调用动态分包页面，禁止直接 import）

ets

// 使用RouterUtil内置pushHsp方法
RouterUtil.pushHsp("hsp_note_editor","src/main/ets/pages/EditorPage",{id:1001})

五、资源管理规范（避免多模块资源覆盖冲突）

1. har_base 通用资源：资源文件名统一前缀common_，如common_empty.png
2. 业务 HAR 资源：增加业务前缀，笔记模块note_item.png，用户模块user_avatar.png
3. HSP 私有资源：仅分包内部使用，不对外暴露，无需全局统一前缀
4. 禁止不同模块同名无前缀资源，打包会发生资源覆盖、图片显示错乱

六、循环依赖检测与规避方案

典型错误循环依赖示例

har_note 依赖 har_user，同时 har_user 依赖 har_note → 编译报错 cyclic dependency

规避方案

1. 业务 HAR 只单向依赖底层 har_base，业务之间互不引用
2. 跨业务数据传递通过 entry 页面中转，不在 HAR 内部互相调用
3. 公共抽取至 har_base：若用户、笔记都需要同一实体 / 工具，下沉至底层公共库

七、编译与打包性能优化规范

1. 稳定底层 har_base：几乎不改动，编译缓存永久生效，修改业务模块仅增量编译对应 har/hsp
2. 大型低频业务拆分 HSP：编辑器、相册、商城拆分为动态包，减小主包体积、加快冷启动
3. 单个 HSP 体积控制在 10MB 以内，超大业务继续拆分多个 HSP
4. 开发调试可临时注释未开发完成的 HSP 依赖，大幅缩短编译时间
5. 上线打包开启分包分离，deliveryWithInstall:true（HSP 默认配置）

八、多人团队协作开发规范

1. 分工按模块划分：
   • 底层负责人：维护 har_base 全套工具、通用组件、主题、全局类型
   • 业务开发 A：har_note + hsp_note_editor 笔记相关全模块
   • 业务开发 B：har_user 用户模块
   • 入口负责人：entry 首页、登录、全局初始化、路由、打包配置
2. 公共底层修改统一提交 har_base，所有人同步更新工程依赖
3. 各业务模块代码隔离，减少 git 合并冲突
4. 对外暴露 API 统一在模块根目录导出，禁止跨模块引用内部私有文件

九、完整工程启动初始化流程（EntryAbility 执行顺序）

1. 获取全局 UIAbility 上下文 context
2. 依次为所有底层工具注入上下文：FileUtil、LogUtil、PermissionUtil 等
3. 生产环境设置日志等级 LogLevel.INFO，屏蔽 DEBUG 调试日志
4. GlobalStore.initPersistentBind () 初始化全局持久化状态绑定
5. 初始化网络请求基础域名、全局请求头配置
6. 监听 APP 前后台切换生命周期，后台清理缓存、暂停定时器
7. 应用退出 onDestroy：释放数据库、文件句柄、清空全部全局监听、销毁弹窗控制器

十、全架构配套代码使用流程示例（新建笔记完整链路）

1. entry 首页点击「新建笔记」按钮
2. 路由判断登录状态（GlobalStore 读取 isLogin，未登录弹窗跳转登录）
3. 调用 HspLoadUtil 动态加载 hsp_note_editor 分包
4. RouterUtil.pushHsp 跳转编辑器页面，传递笔记 ID 参数
5. HSP 编辑器页面自动导入 har_base 弹窗、状态组件、主题工具
6. HSP 页面引入 har_note 的 Rdb 数据库工具完成新增笔记写入
7. 操作完成通过路由返回列表页面，调用 hspManager.unloadPackage 释放动态分包内存
8. 列表页面 RefreshListView 下拉刷新，RdbUtil 查询最新笔记数据渲染
9. 页面退出 aboutToDisappear 关闭数据库、弹窗、解绑全局状态监听

十一、架构常见问题与解决方案

问题 1：修改通用组件后全工程重新编译，速度很慢 解决：底层 har_base 尽量少改动，业务拆分独立 HAR，仅修改对应业务模块只会增量编译自身。

问题 2：打包后主包体积巨大，安装缓慢 解决：低频重型页面拆分 HSP 动态分包，运行时按需加载，主包仅保留核心常驻页面与底层工具。

问题 3：编译提示循环依赖 cyclic dependency 解决：调整分层，业务 HAR 只依赖 har_base，业务之间禁止互相导入。

问题 4：多模块同名图片渲染错乱、显示错误图标 解决：所有资源文件增加模块专属前缀，区分 base / 笔记 / 用户 / HSP 私有资源。

问题 5：HSP 页面跳转提示页面不存在 解决：统一使用 RouterUtil.pushHsp 拼接标准 hsp 包名路径，核对 module.json5 pages 注册路径。

问题 6：页面退出内存持续上涨，APP 卡顿耗电 解决：严格遵守生命周期规范：页面销毁关闭 RDB、释放文件、关闭弹窗、解绑 GlobalStore 监听、卸载 HSP 分包。

十二、架构总结

本套四层单向分层架构整合前文全部工具、UI 组件、业务能力，严格划分 entry、底层 HAR、业务 HAR、动态 HSP 四层职责，强制单向依赖杜绝循环耦合，统一跨模块导入、资源、打包、协作规范。 架构优势：

1. 代码高度复用，底层工具、通用组件全局一次开发全项目复用
2. 业务解耦，新增功能仅新增对应 HAR/HSP，不污染主入口代码
3. 分包优化安装包体积、冷启动速度、内存占用
4. 分层清晰，分工明确，适合单人毕设、多人团队协同开发
5. 完全适配 OpenHarmony API23 / HarmonyOS NEXT，所有前文工具可直接集成进该工程架构，形成一套完整可交付的标准化鸿蒙应用工程。