OpenHarmony 完整项目工程整合规范 + 模块化分层架构（API23+ 标准企业级结构）

摘要前面系列教程覆盖了 ArkUI 组件、路由、生命周期、本地存储、网络请求、Ability 底层全套基础能力本篇统一梳理标准工程目录分层、模块化拆分、代码复用规范、全局工具统一管理、项目打包权限配置、常见工程报错统一解决方案形成可直接用于课程设计、实训、小型商业项目的标准化架构解决新手代码杂乱、工具类分散、状态管理混乱、资源无统一管理等问题。API23 对工程模块导入、上下文传递、文件引用路径有严格校验不规范目录会出现编译爆红、上下文丢失、存储初始化失败等问题。本文给出固定目录结构、分层职责、统一导入规范、全局初始化流程、完整 module.json5 配置模板实现低耦合、易维护的鸿蒙应用工程架构。关键词OpenHarmonyAPI23工程架构模块化分层目录规范工具类统一管理项目整合module.json5 配置一、标准工程整体分层思想四层架构四层分层职责底层工具层 utils网络、数据库、本地存储、路由、弹窗工具纯逻辑无 UI全局复用数据管理层 model数据实体类、接口返回类型、全局状态常量、枚举定义组件公共层 components自定义通用 UI 组件弹窗、输入框、列表项、加载框业务页面层 pages各功能业务页面仅负责 UI 渲染与调用上层工具不写底层原生 API分层核心原则单向依赖pages → components → model → utils 禁止反向依赖工具类不能导入页面、组件避免循环导入编译报错。二、API23 标准完整目录结构entry 模块plaintextentry/src/main/ets ├─ entryability # 应用入口UIAbility全局生命周期、初始化 │ └─ EntryAbility.ets ├─ pages # 所有业务页面按功能分文件夹 │ ├─ index # 首页 │ │ └─ Index.ets │ ├─ login # 登录页 │ │ └─ Login.ets │ ├─ mine # 个人中心 │ │ └─ Mine.ets │ ├─ note # 笔记管理 │ │ └─ NoteList.ets │ └─ setting # 设置页 │ └─ Setting.ets ├─ components # 全局通用自定义组件 │ ├─ LoadingDialog.ets # 全局加载弹窗 │ ├─ InputDialog.ets # 输入弹窗 │ └─ NoteItem.ets # 笔记列表条目组件 ├─ model # 数据模型、类型、常量、枚举 │ ├─ Constant.ets # 全局常量域名、key、页面路由地址 │ ├─ NoteModel.ets # 笔记实体类 │ └─ UserModel.ets # 用户信息实体 ├─ utils # 底层工具类全局单例 │ ├─ http_util.ets # 网络请求封装 │ ├─ preference_utils.ets # Preferences持久化 │ ├─ rdb_util.ets # RDB数据库工具 │ └─ router_util.ets # 路由跳转工具 └─ resources # 图片、字符串、颜色资源三、各分层完整代码模板整合3.1 model 全局常量 Constant.ets统一管理地址、存储 keyets// 接口基础域名 export const BASE_URL https://jsonplaceholder.typicode.com // AppStorage全局key常量避免字符串硬编码 export const STORAGE_KEY { DARK_MODE: darkMode, IS_LOGIN: isLogin, USER_NAME: userName, TOKEN: token } // Preferences本地存储key export const PREF_KEY { DARK_MODE: dark_mode, LOGIN_ACCOUNT: login_account, SEARCH_HISTORY: search_history } // 页面路由地址统一常量 export const PAGE_ROUTE { INDEX: pages/index/index, LOGIN: pages/login/login, MINE: pages/mine/mine, NOTE_LIST: pages/note/NoteList }3.2 model 实体类 NoteModel.etsetsexport interface NoteItem { id: number title: string content: string create_time: number }3.3 utils 全部工具类前文整合单例统一导出无循环依赖不再重复粘贴统一调用规则ets// 页面统一导入方式 import HttpUtil from ../utils/http_util import PrefUtil from ../utils/preference_utils import RdbUtil from ../utils/rdb_util import RouterUtil from ../utils/router_util import { PAGE_ROUTE, STORAGE_KEY } from ../model/Constant3.4 components 通用弹窗 / 条目组件所有自定义弹窗、复用组件统一放此目录页面直接导入使用减少页面冗余代码。3.5 entryability EntryAbility.ets全局唯一初始化入口整合全套初始化逻辑应用创建初始化 AppStorage 默认值窗口创建获取全局上下文初始化 Preferences、RDB前后台自动保存配置、启停全局定时器窗口销毁统一关闭数据库、清除定时资源完整模板见上一篇 Ability 文档直接复制使用。3.6 pages 业务页面标准模板统一规范所有页面固定四段式结构顶部导入工具、模型、组件、常量State 页面私有状态生命周期aboutToAppear 加载数据aboutToDisappear 释放页面资源build 仅 UI 渲染无业务逻辑、网络请求示例标准页面骨架etsimport HttpUtil from ../utils/http_util import RdbUtil from ../utils/rdb_util import { NoteItem } from ../model/NoteModel import NoteItem from ../components/NoteItem Entry Component struct NoteList { State noteList: NoteItem[] [] timer: number | null null requestCancel: boolean false async aboutToAppear() { this.requestCancel false await RdbUtil.init(getContext(this)) await this.loadData() // 页面局部定时器 this.timer setInterval((){}, 10000) } // 业务方法仅调用工具层不写原生API async loadData() { const list await RdbUtil.queryNoteList(0,10) if(!this.requestCancel) this.noteList list } build() { List({space:12}) { ForEach(this.noteList, item { ListItem() { NoteItem({data: item}) } }) } } aboutToDisappear() { // 页面资源释放 this.requestCancel true if(this.timer) clearInterval(this.timer) RdbUtil.closeDB() } }四、全局统一初始化完整流程应用启动全链路冷启动点击桌面图标 → EntryAbility.onCreate初始化 AppStorage 全部全局默认 keyonWindowStageCreate获取全局上下文 context传入 Pref、RDB 工具初始化读取本地 Preferences 配置覆盖 AppStorage 全局状态loadContent 加载首页 pages/index首页 Index 页面 aboutToAppear按需拉取首页网络数据、加载列表切后台 onBackground暂停全局定时器将 AppStorage 配置同步写入 Preferences切前台 onForeground重启全局定时轮询刷新首页数据退出应用 / 全部页面关闭 onWindowStageDestroy清除全局定时器、关闭 RDB 数据库释放全部重量级资源五、module.json5 全套基础配置API23 必备5.1 网络权限、页面注册、窗口配置json{ module: { name: entry, type: entry, description: $string:module_desc, main: entryability/EntryAbility, deviceTypes: [phone], deliveryWithInstall: true, installationFree: false, pages: [ pages/index/index, pages/login/login, pages/mine/mine, pages/note/NoteList, pages/setting/Setting ], requestPermissions: [ { name: ohos.permission.INTERNET } ], window: { designWidth: 720, autoDesignWidth: true } } }5.2 明文 HTTP 白名单配置仅测试使用项目目录entry/ohos.security.json5json{ network: { cleartextTraffic: true } }六、API23 工程开发强制编码规范6.1 导入与路径规范全部使用相对路径../导入禁止绝对路径工具类统一单例导出export default xxxUtil常量、类型使用命名导出export const / export interface禁止页面之间互相导入页面跳转只用 router不直接引入页面组件6.2 状态分层规范全局共享数据AppStorage Preferences 持久化页面独立临时数据页面内部 State弹窗临时数据弹窗内部 State常量、接口地址统一放入 model/Constant禁止页面写死字符串6.3 资源释放统一规范应用全局资源数据库、全局定时器EntryAbility 生命周期销毁页面局部定时器、网络请求页面 aboutToDisappear 销毁弹窗临时资源CustomDialog 自身 aboutToDisappear 销毁6.4 网络、存储调用规范禁止页面直接导入原生 http /preferences/relationalStore所有读写操作统一调用 utils 封装工具类统一拦截错误、加载弹窗数据库操作统一单例工具避免多实例文件占用报错6.5 UI 组件复用规范重复列表条目、弹窗、按钮卡片抽取至 components页面仅组装业务复杂 UI 拆分自定义组件降低页面代码量七、API23 工程高频编译报错与一次性解决方案循环导入报错原因页面导入组件组件又导入页面工具类导入页面 解决严格单向分层utils、model 不导入页面与 componentsPreferences/RDB 初始化上下文为空原因页面过早调用工具 init未等 Ability 创建窗口 解决统一在 EntryAbility.onWindowStageCreate 传入全局 context 初始化http 明文接口 404 / 请求无响应解决配置 ohos.security.json5 开启 cleartextTraffic线上全部替换 https页面跳转 getParams 读取参数为空解决使用 RouterUtil 标准封装 pushUrl完整传入 params 对象不简写 url 字符串数据库文件被占用多次进出页面报错解决页面 aboutToDisappear 调用 RdbUtil.closeDB全局单例复用页面退出后网络请求回调修改状态控制台报错解决页面增加 requestCancel 标记aboutToDisappear 置 true回调赋值前判断弹窗多次打开保留上次输入内容解决弹窗 aboutToAppear 重置内部 State 输入变量八、完整项目开发执行流程课程设计 / 毕设标准步骤搭建标准四层目录结构utils/model/components/pages/entryability编写 model 常量、实体类型统一管理路由、存储 key、接口域名封装全套 utils 工具http、preference、rdb、router编写通用 components 弹窗、列表条目组件完善 EntryAbility 全局初始化、前后台资源管控逻辑按业务开发 pages 页面遵循标准页面模板配置 module.json5 页面、网络权限、窗口适配联调登录持久化、全局主题、笔记数据库增删改查、页面路由跳转统一处理加载弹窗、异常 Toast、资源释放、退出清空登录态测试多页面切换、后台驻留、重启应用数据持久化校验九、整套系列教程完整汇总目录ArkUI 基础布局Row、Column、Stack、List基础 UI 组件Text、Image、Button、TextInput选择交互控件Toggle、Radio、Checkbox、Slider自定义弹窗 CustomDialog全局状态 AppStorage本地轻量持久化 Preferences关系型数据库 RDB海量结构化数据Router 页面路由与跨页面传参页面 组件生命周期 aboutToAppear/aboutToDisappearHttp 网络请求全局封装UIAbility 应用底层生命周期本篇API23 标准模块化工程整合架构