鸿蒙开发从入门到入土：1-初识鸿蒙

0 引子

最初接触鸿蒙是在2021年，当时鸿蒙2.0刚刚推出，当时公司所在团队受邀做OTA升级预装，于是主动接了这个任务。2.0/3.0时代，鸿蒙还是使用的Java语言，布局文件也跟 Android layout 的类似，只不过是前缀不再是 android 而是ohos，当时的系统模型称作 FA，跟现在的 stage 模型相差还是挺大的。既然有区别，那我们就来看看现在 Stage 模型是个什么样子吧

1 应用程序包概述

1.1 应用程序包结构

在开始学习 Stage 模型之前，我们先看看应用程序包的结构是什么样子的 从上图可以看到一个应用包含一个或者多个Module，那什么是 Module 呢？其实 Module 是应用或者服务的基本功能单元，包含了源代码、资源文件、第三方库及应用或者服务的配置文件，每一个 Module 都可以独立进行编译和运行。
Module 分为Ability和Library两种类型，Ability类型的 Modul e对应于编译后的HAP（Harmony Ability Package）；Library类型的 Module 对应于HAR（Harmony Archive）

1.2 应用程序包多 HAP 机制

前面说到，Module 分为Ability和Library两种类型，而Ability类型才会被编译成HAP，因此多 HAP 机制也是针对Ability这种 Module 来说的。聪明的你一定猜到了，既然时多 HAP 机制，那么Ability这种类型的 Module 一定也是有多种类型的，不错，Ability类型的 Module 又可以分为两类，它们是：

1. Entry类型的 Module：是应用的主模块，在module.json5配置文件中的 type 标签配置为 "entry" 类型。在同一个应用中，同一设备类型只支持一个Entry类型的 Module，通常用于实现应用的入口界面、入口图标、主特性功能等。
2. Feature类型的 Module：是应用的动态特性模块，在module.json5配置文件中的 type 标签配置为"feature" 类型。一个应用程序包可以包含一个或多个Feature类型的 Module，也可以不包含Feature类型的 Module。

因此，实际上多 HAP 机制，就是将一个项目拆分成多个 Module，这其中包含一个 EntryModuel，0~N个FeatureModule，这样经过编译打包后，就会生成1个或多个 HAP 包，从而实现了应用程序的多 HAP 机制（见下图）

2 Stage模型应用程序包结构

2.1 开发态包结构

下图是通过 DevEco-Studio 所创建的项目的工程结构
其主要包含的文件类型及用途如下：

说明

• AppScope目录由DevEco Studio自动生成，不可更改。
• Module目录名称可以由DevEco Studio自动生成（比如entry、library等），也可以自定义。为了便于说明，下表中统一采用Module_name表示。

文件类型	说明
配置文件	包括应用级配置信息、以及Module级配置信息： - AppScope > app.json5：app.json5配置文件，用于声明应用的全局配置信息，比如应用Bundle名称、应用名称、应用图标、应用版本号等。 - Module_name > src > main > module.json5：module.json5配置文件，用于声明Module基本信息、支持的设备类型、所含的组件信息、运行所需申请的权限等。
ArkTS源码文件	Module_name > src > main > ets：用于存放Module的ArkTS源码文件（.ets文件）。
资源文件	包括应用级资源文件、以及Module级资源文件，支持图形、多媒体、字符串、布局文件等，详见资源分类与访问。 - AppScope >者resources ：用于存放应用需要用到的资源文件。 - Module_name > src > main > resources ：用于存放该Module需要用到的资源文件。
其他配置文件	用于编译构建，包括构建配置文件、编译构建任务脚本、混淆规则文件、依赖的共享包信息等。 - build-profile.json5：工程级或Module级的构建配置文件，包括应用签名、产品配置等。 - hvigorfile.ts：应用级或Module级的编译构建任务脚本，开发者可以自定义编译构建工具版本、控制构建行为的配置参数。 - obfuscation-rules.txt：混淆规则文件。混淆开启后，在使用Release模式进行编译时，会对代码进行编译、混淆及压缩处理，保护代码资产。 - oh-package.json5：用于存放依赖库的信息，包括所依赖的三方库和共享包。

2.2 编译态包结构

不同类型的Module编译后会生成对应的HAP、HAR、HSP等文件，开发态视图与编译态视图的对照关系如下： 从开发态到编译态，Module中的文件会发生如下变更：

• ets目录：ArkTS源码编译生成.abc文件。
• resources目录：AppScope目录下的资源文件会合入到Module下面资源目录中，如果两个目录下的存在重名文件，编译打包后只会保留AppScope目录下的资源文件。
• module配置文件：AppScope目录下的app.json5文件字段会合入到Module下面的module.json5文件之中，编译后生成HAP或HSP最终的module.json文件。

需要注意的是

在编译 HAP 和 HSP 时，会把他们所依赖的HAR直接编译到 HAP 和 HSP 中。

2.3 选择合适的包类型

Module类型	包类型	说明
Ability	HAP	应用的功能模块，可以独立安装和运行，必须包含一个entry类型的HAP，可选包含一个或多个feature类型的HAP。
Static Library	HAR	静态共享包，编译态复用。- 支持应用内共享，也可以发布后供其他应用使用。- 作为二方库，发布到OHPM私仓，供公司内部其他应用使用。- 作为三方库，发布到OHPM中心仓，供其他应用使用。- 多包（HAP/HSP）引用相同的HAR时，会造成多包间代码和资源的重复拷贝，从而导致应用包膨大。
Shared Library	HSP	动态共享包，运行时复用。- 当前仅支持应用内共享。- 当多包（HAP/HSP）同时引用同一个共享包时，采用HSP替代HAR，可以避免HAR造成的多包间代码和资源的重复拷贝，从而减小应用包大小。

HAP、HSP、HAR支持的规格对比如下：

规格	HAP	HAR	HSP
支持在配置文件中声明UIAbility组件与 ExtensionAbility组件	√	×	×
支持在配置文件中声明pages页面	√	×	√
支持包含资源文件与.so文件	√	√	√
支持依赖其他HAR文件	√	√	√
支持依赖其他HSP文件	√	√	√
支持在设备上独立安装运行	√	×	×

说明

• HAR虽然不支持在配置文件中声明pages页面，但是可以包含pages页面，并通过命名路由的方式进行跳转。
• 由于HSP仅支持应用内共享，如果HAR依赖了HSP，则该HAR文件仅支持应用内共享，不支持发布到二方仓或三方仓供其他应用使用，否则会导致编译失败。
• HAR和HSP均不支持循环依赖，也不支持依赖传递。

2.4 发布态包结构

每个应用中至少包含一个.hap文件，可能包含若干个.hsp文件、也可能不含，一个应用中的所有.hap与.hsp文件合在一起称为Bundle，其对应的bundleName是应用的唯一标识（详见app.json5配置文件中的bundleName标签）。

当应用发布上架到应用市场时，需要将Bundle打包为一个.app后缀的文件用于上架，这个.app文件称为App Pack（Application Package），与此同时，DevEco Studio工具自动会生成一个pack.info文件。pack.info文件描述了App Pack中每个HAP和HSP的属性，包含APP中的bundleName和versionCode信息、以及Module中的name、type和abilities等信息。

上图是编译发布与上架部署流程图，需要特别说明的是：

• App Pack是发布上架到应用市场的基本单元，但是不能在设备上直接安装和运行。
• 用户在鸿蒙应用市场下载安装APP时，会先将APP Pack下载下来，然后再拆分成若干个 .hap / .hsp文件，并对它们逐个进行签名，然后再逐个安装到手机上。

3 题外话

在 HarmonyOS 2.0 / 3.0 时代，编译好的 release 包，即上文提到的 APP Pack 是无法直接通过 DevEco-Studio 安装测试机上，需要对这个 APP Pack 进行拆包，拆成若干个 .hap / .hsp 文件后，再通过命令行^[1]将这些文件按照先后顺序安装到测试机上，不知道在 Next 版本上这一点是否有所改进，如果有知道的小伙伴，可以留言告诉笔者，在这里也留个坑，等后续项目准备上线了，我也自己试验下，看看能不能直接在测试机上安装 .app 文件

参考资料

1. 部分内容截取自鸿蒙官方开发文档 Stage模型应用程序包结构

备注

[1]： 将APP拆分为HAP