一、前言：为什么不要再写单模块鸿蒙项目？

很多鸿蒙初学者、在校毕设项目、小型Demo 全部采用 单 Entry 单体开发，看似写得快，实则隐患极大：

• 所有工具、页面、业务逻辑全部堆在 entry，代码极度混乱

• 无分层、无规范，复用性为 0，换项目必须重写

• 页面不做资源回收，极易出现内存泄漏、页面卡顿

• 全部页面打包入主包，安装包体积臃肿、冷启动慢

• 多人开发冲突严重，完全不具备工程化能力

为此本文基于 OpenHarmony API23 搭建一套四层单向依赖架构，结合 HAR 静态复用 + HSP 动态分包，打造一套可直接商用、可复用、可做毕设的标准鸿蒙项目模板。

---

二、整体架构设计（核心核心！）

本项目采用业界标准 四层单向依赖架构，严格禁止循环依赖、反向依赖，完全贴合鸿蒙商用开发规范。

分层结构

HSP动态页面 → 业务HAR → 基础HAR → 无依赖

1. Entry 入口层：应用生命周期、全局初始化、常驻页面、路由拦截、HSP调度

2. har_base 底层公共层：全局工具、通用组件、主题、常量（纯底层、无业务）

3. 业务HAR层：用户、笔记等独立业务模块，各自解耦互不干扰

4. HSP动态分包层：重型、低频页面按需加载，减小主包体积

架构优势

• ✅ 业务完全解耦，新增功能只新增模块，不动老代码

• ✅ 底层工具全局复用，一次开发、全项目通用

• ✅ 动态分包优化启动速度、优化内存、瘦身安装包

• ✅ 规范统一，无硬编码、无资源冲突、无循环依赖

---

三、底层HAR通用能力封装（项目核心壁垒）

本项目最大亮点：全套企业级工具封装，开箱即用，彻底告别原生 API 裸写。

1. 十大基础工具类全覆盖

• HttpUtil：统一请求拦截、自动Token、全局Loading、页面销毁自动中断请求

• RdbUtil：数据库单例封装、分页查询、模糊搜索、事务、自动关闭游标

• PrefUtil：轻量键值存储，用户配置、登录状态持久化

• RouterUtil：统一路由、登录拦截、HSP专属跳转、路由栈管理

• DialogUtil：全局弹窗统一管理，页面销毁批量关闭防残留

• PermissionUtil：动态权限申请、永久拒绝跳转系统设置

• ImagePickerUtil：相册单选多选、图片压缩、预览、权限自动校验

• FileUtil：缓存计算、文件读写、一键清理缓存

• LogUtil：分级日志、敏感脱敏、日志文件自动清理

• GlobalStore：全局响应式状态管理，持久化存储登录、深色模式

2. 全局主题体系（彻底消灭硬编码）

项目所有颜色、字号、间距、圆角、阴影全部统一管理，内置 浅色/深色双主题：

• 全局一键切换暗黑模式

• 所有页面自动适配，无需逐个改样式

• 产品改版只改一处配置，全局生效

3. 两大高复用通用UI组件

• StateView 页面状态组件：自动适配加载中、空数据、错误重试、正常内容四种状态

• RefreshListView 高性能分页列表：自带下拉刷新、上拉加载、防重复请求锁、无更多兜底

---

四、业务模块设计（完全解耦）

1. 业务HAR模块

将用户、笔记业务单独抽离为静态HAR：

• 业务实体模型统一管理

• 数据库CRUD、业务逻辑内聚

• 业务组件独立封装，不污染全局

• 业务模块之间零依赖，彻底杜绝循环依赖报错

2. HSP动态分包优化

将体积大、使用频率低的笔记编辑器拆分为独立HSP：

• 应用冷启动不加载分包代码，启动速度大幅提升

• 按需加载，用完卸载，释放内存资源

• 主包体积大幅缩小，安装更轻快

---

五、核心业务功能实现

基于整套架构，实现完整闭环笔记APP功能：

• 用户登录、本地账号缓存、登录状态持久化、退出登录

• 笔记新增、编辑、删除、模糊搜索、分页加载

• 相册图片选择、自动压缩、图片预览

• 全局深色/浅色主题切换，配置永久保存

• 缓存大小统计、一键清理缓存

• 路由登录拦截、权限异常兜底、网络异常兜底

---

六、性能优化与内存治理（重点干货）

本项目解决了鸿蒙开发最常见的 内存泄漏、页面卡顿、资源残留 问题：

• 页面销毁自动中断所有网络请求，杜绝无效回调

• 页面销毁批量关闭弹窗，杜绝遮罩残留

• 页面销毁解绑全局状态监听、终止循环动画

• RDB、文件句柄、图片资源主动 release 释放

• HSP页面退出主动卸载分包，释放大量内存

• 列表双层锁机制，彻底杜绝重复请求、重复数据

---

七、开发踩坑总结（新手必看）

• 循环依赖报错：业务HAR禁止互相依赖，只允许依赖底层har_base

• 深色模式局部不刷新：禁止缓存主题色值，渲染时实时获取

• HSP内存暴涨：页面退出必须unloadPackage卸载分包

• 资源图片错乱：所有模块资源加专属前缀，避免打包覆盖

• 弹窗残留卡死页面：页面销毁统一关闭全部弹窗

---

八、项目总结 & 复用价值

这不仅仅是一个笔记Demo，而是一套 可复用、可落地、可商用的 OpenHarmony 工程脚手架。

无论你是做课程设计、毕业设计、个人练手、企业项目初始化，这套架构都可以直接套用：

• 规范完整、分层清晰、无耦合

• 工具齐全、组件通用、主题统一

• 性能优秀、内存稳定、适配API23最新规范

后续开发任何鸿蒙应用（资讯、商城、工具、备忘录），只需替换业务层代码，底层架构完全不用动。