⭐本期内容：【HarmonyOS5】Stage 模型应用程序包结构详解
🏆系列专栏：鸿蒙 HarmonyOS：探索未来智能生态新纪元
Stage 模型应用程序包结构概述
HarmonyOS 5 采用 Stage 模型作为应用程序框架的核心架构。相比于早期的 FA（Feature Ability）模型，Stage 模型提供了更清晰的应用生命周期管理和更灵活的 UI 构建方式。Stage 模型基于模块化设计理念，将应用程序拆分为多个独立的模块，每个模块都有自己的生命周期和功能职责。
Stage 模型的核心优势在于其分层架构设计，它将应用程序分为应用层（Application）、模块层（Module）和组件层（Component）。不仅提高了代码的可维护性，还为应用的按需加载和动态更新提供了技术基础。同时，Stage 模型还引入了更加灵活的 Ability 概念，包括UIAbility和ExtensionAbility，为不同类型的应用场景提供了专门的解决方案。
开发态包结构
开发态是指应用程序正在开发过程中的状态。在这个阶段，代码结构主要关注开发效率和模块化组织。Stage 模型在开发态采用了清晰的目录层次结构，每个模块都有自己独立的代码空间和资源管理。AppScope目录包含了应用级别的配置和资源，这些资源可以被所有模块共享使用。每个功能模块都有完整的代码结构，包括 Ability、页面、服务等组件。
开发态的目录结构设计考虑了以下几个重要因素：
Stage 模型应用在开发态的目录结构如下：
MyHarmonyApp/├── AppScope/ // 应用级资源目录│ ├── app.json5 // 应用级配置文件│ └── resources/ // 应用级资源文件│ ├── base/ // 基础资源│ │ ├── element/ // 基础元素资源│ │ ├── media/ // 媒体资源│ │ └── profile/ // 配置文件资源│ └── en_US/ // 英文资源├── entry/ // 入口模块│ ├── src/│ │ ├── main/│ │ │ ├── ets/ // ArkTS代码目录│ │ │ │ ├── entryability/ │ │ │ │ │ └── EntryAbility.ts // 入口Ability│ │ │ │ ├── pages/ // 页面组件│ │ │ │ │ ├── Index.ets│ │ │ │ │ └── Detail.ets│ │ │ │ ├── common/ // 公共代码│ │ │ │ │ ├── utils.ts│ │ │ │ │ ├── constants.ts│ │ │ │ │ └── types.ts│ │ │ │ └── components/ // 自定义组件│ │ │ │ ├── CustomButton.ets│ │ │ │ └── CustomDialog.ets│ │ │ ├── resources/ // 模块资源│ │ │ │ ├── base/│ │ │ │ │ ├── element/│ │ │ │ │ ├── media/│ │ │ │ │ └── profile/│ │ │ │ ├── en_US/│ │ │ │ └── zh_CN/│ │ │ └── module.json5 // 模块配置│ │ └── ohosTest/ // 测试代码│ │ └── ets/│ │ └── test/│ │ └── Ability.test.ets│ ├── build-profile.json5 // 构建配置│ └── hvigorfile.ts // 构建脚本├── payment/ // 支付功能模块│ ├── src/│ │ └── main/│ │ ├── ets/│ │ │ ├── paymentability/│ │ │ │ └── PaymentAbility.ts│ │ │ ├── pages/│ │ │ │ ├── PaymentPage.ets│ │ │ │ └── PaymentResult.ets│ │ │ └── services/│ │ │ └── PaymentService.ts│ │ ├── resources/│ │ └── module.json5├── common/ // 共享库模块│ ├── src/│ │ └── main/│ │ ├── ets/│ │ │ ├── utils/│ │ │ │ ├── HttpUtil.ts│ │ │ │ ├── LogUtil.ts│ │ │ │ └── PreferenceUtil.ts│ │ │ ├── models/│ │ │ │ ├── UserModel.ts│ │ │ │ └── BaseResponse.ts│ │ │ └── constants/│ │ │ └── CommonConstants.ts│ │ └── module.json5├── build-profile.json5 // 应用构建配置├── hvigorfile.ts // 应用构建脚本├── app.json5 // 应用配置文件└── oh-package.json5 // 包管理配置
复制代码
编译态包结构
编译态是指应用程序代码被编译处理的阶段。在 HarmonyOS 开发中，编译过程会将 ArkTS 代码转换为可执行的字节码，并处理资源文件。编译过程是一个复杂的转换过程，涉及代码转换、资源处理、依赖解析和包打包等多个步骤。
编译后的目录结构如下：
build/├── default/│ ├── cache/ // 缓存文件│ │ ├── entry/│ │ ├── payment/│ │ └── common/│ ├── intermediates/ // 中间产物│ │ ├── entry/│ │ │ ├── js/ // 编译后的JS代码│ │ │ │ ├── entryability/│ │ │ │ │ └── EntryAbility.js│ │ │ │ ├── pages/│ │ │ │ │ ├── Index.js│ │ │ │ │ └── Detail.js│ │ │ │ └── common/│ │ │ │ └── utils.js│ │ │ ├── res/ // 处理后的资源│ │ │ │ ├── base/│ │ │ │ ├── en_US/│ │ │ │ └── zh_CN/│ │ │ ├── assets/ // 静态资源│ │ │ └── manifest/ // 清单文件│ │ ├── payment/│ │ │ ├── js/│ │ │ ├── res/│ │ │ └── assets/│ │ └── common/│ │ ├── js/│ │ └── res/│ ├── outputs/ // 最终输出│ │ ├── entry/│ │ │ └── entry.hap // 入口模块HAP包│ │ ├── payment/│ │ │ └── payment.hap // 支付模块HAP包│ │ ├── common/│ │ │ └── common.hap // 共享模块HAP包│ │ └── app.app // 应用APP包│ └── temp/ // 临时文件└── release/ // 发布版本构建产物
复制代码
在编译阶段，系统会执行以下关键操作：
代码编译转换：将 ArkTS 代码编译为 JavaScript 代码，然后进一步转换为字节码。
资源处理和索引生成：系统会处理各种资源文件，包括图片、音频、视频、字符串等，并生成资源索引表。
依赖解析和打包：系统会分析模块间的依赖关系，解析第三方库的依赖，并将所有相关文件打包到对应的 HAP 文件中。
签名和验证：生成的 HAP 文件会进行数字签名，确保应用的完整性和安全性。
编译过程可以通过 DevEco Studio 界面或命令行工具触发：
# 使用hvigor命令行工具编译hvigor --mode module -p product=default
# 编译特定模块hvigor assembleHap --mode module -p module=entry
# 清理并重新编译hvigor cleanhvigor assembleHap
复制代码
发布态包结构
发布态是指应用程序准备发布到应用市场的最终状态。在这个阶段，应用程序被打包成HAP包和APP包，便于分发和安装。发布态的包结构是用户最终接触到的形式，也是应用在设备上运行的基础。
APP 包结构
APP包是应用的分发单元，实际上是一个 ZIP 格式的压缩文件。APP 包包含了应用的所有模块和相关配置信息，是应用分发的最小单位。每个 HAP 文件代表一个功能模块，可以独立加载和运行。
MyHarmonyApp.app/ (ZIP格式)├── app.json5 // 应用配置文件├── entry.hap // 入口模块HAP包├── payment.hap // 支付模块HAP包├── common.hap // 共享模块HAP包├── pack.info // 包信息文件├── META-INF/ // 签名信息│ ├── MANIFEST.MF // 清单文件│ ├── CERT.SF // 证书签名文件│ └── CERT.RSA // 证书文件└── resources.index // 全局资源索引（如果有）
复制代码
HAP 包结构
每个HAP包是一个ZIP格式的压缩文件，包含了一个模块的完整功能实现。HAP 包是 HarmonyOS 应用的基本运行单元，每个 HAP 包都可以独立运行。HAP 包的内部结构设计充分考虑了运行时的性能需求。编译后的字节码文件（.abc 文件）经过了优化，可以快速加载和执行。资源文件按照类型和语言进行分类存储，支持国际化和本地化需求。
entry.hap/ (ZIP格式)├── module.json5 // 模块配置文件├── resources.index // 资源索引表├── resources/ // 模块资源│ ├── base/│ │ ├── element/ // 基础元素│ │ ├── media/ // 媒体文件│ │ └── profile/ // 配置文件│ ├── en_US/ // 英文资源│ └── zh_CN/ // 中文资源├── ets/ // 编译后的代码│ ├── entryability/│ │ └── EntryAbility.abc // 字节码文件│ ├── pages/│ │ ├── Index.abc│ │ └── Detail.abc│ └── common/│ └── utils.abc├── libs/ // 原生库（如果有）│ ├── arm64-v8a/│ └── armeabi-v7a/├── assets/ // 静态资源文件└── pack.info // 包信息
复制代码
以下是一个 app.json5 文件示例：
{ "app": { "bundleName": "com.example.myharmonyapp", "vendor": "example", "versionCode": 10001, "versionName": "1.0.0", "minAPIVersion": 10, "targetAPIVersion": 12, "apiReleaseType": "Release", "compileSdkVersion": 12, "compileSdkType": "HarmonyOS", "debug": false }, "modules": [ { "name": "entry", "type": "entry", "srcPath": "./entry", "description": "入口模块，包含应用主界面和核心功能", "mainElement": "EntryAbility", "deviceTypes": [ "phone", "tablet" ], "deliveryWithInstall": true }, { "name": "payment", "type": "feature", "srcPath": "./payment", "description": "支付功能模块，提供支付相关服务", "deviceTypes": [ "phone", "tablet" ], "deliveryWithInstall": false, "installationFree": true }, { "name": "common", "type": "shared", "srcPath": "./common", "description": "公共模块，提供共享的工具类和组件", "deviceTypes": [ "phone", "tablet" ], "deliveryWithInstall": true } ]}
复制代码
选择合适的包类型
在 HarmonyOS 5 开发中，选择合适的包类型是应用架构设计的重要环节。不同的包类型适用于不同的应用场景和业务需求，正确的选择可以显著提高开发效率和应用性能。
单 HAP 包应用
单HAP包应用适用于功能简单的小型应用，所有功能都集中在一个Entry Module中。这种架构模式简单直接，适合快速开发和原型验证。
多 HAP 包应用
多HAP包应用适用于功能复杂、需要模块化的大型应用。将不同的功能拆分到Feature Module中，可以提高开发效率和应用的可维护性。
包含共享模块的应用
包含共享模块的应用适用于需要在多个模块间共享代码和资源的应用。共享模块可以提供通用的工具类、UI组件、业务逻辑等。
在实际开发中，可以根据以下因素选择合适的包类型：
应用规模考量：小型应用适合单 HAP 包，中大型应用适合多 HAP 包结构。应用规模不仅包括功能数量，还包括代码复杂度、团队规模等因素。
团队结构匹配：单人或小团队开发适合单 HAP 包，多团队并行开发适合多 HAP 包结构。团队的技术水平和协作经验也是重要考虑因素。
功能复杂度评估：功能相对独立、复杂度高的应用适合模块化的多 HAP 包结构。需要考虑功能间的耦合度和依赖关系。
按需加载需求：如果应用有明确的按需加载需求，必须采用多 HAP 包结构。这对于大型应用的用户体验优化很重要。
维护和更新策略：考虑应用后期的维护频率和更新策略。如果需要频繁更新特定功能，模块化结构更有优势。
总结
感谢您的阅读！如有任何疑问，欢迎随时私信交流。
评论