应用程序包概述

应用与应用程序包

应用的多Module设计机制

• 支持模块化开发： 一个应用通常会包含多种功能，将不同的功能特性按模块来划分和管理是一种良好的设计方式。在开发过程中，我们可以将每个功能模块作为一个独立的Module进行开发，Module中可以包含源代码、资源文件、第三方库、配置文件等，每一个Module可以独立编译，实现特定的功能。这种模块化、松耦合的应用管理方式有助于应用的开发、维护与扩展。（考点）

• 支持多设备适配： 一个应用往往需要适配多种设备类型，在采用多Module设计的应用中，每个Module都会标注所支持的设备类型。有些Module支持全部类型的设备，有些Module只支持某一种或几种类型的设备（比如平板），那么在应用市场分发应用包时，也能够根据设备类型做精准的筛选和匹配，从而将不同的包合理的组合和部署到对应的设备上。

Module类型

• Ability类型的Module： 用于实现应用的功能和特性。每一个Ability类型的Module编译后，会生成一个以.hap为后缀的文件，我们称其为HAP（Harmony Ability Package）包。HAP包可以独立安装和运行，是应用安装的基本单位，一个应用中可以包含一个或多个HAP包，具体包含如下两种类型。
• entry类型的Module：应用的主模块，包含应用的入口界面、入口图标和主功能特性，编译后生成entry类型的HAP。每一个应用分发到同一类型的设备上的应用程序包，只能包含唯一一个entry类型的HAP。
• feature类型的Module：应用的动态特性模块，编译后生成feature类型的HAP。一个应用中可以包含一个或多个feature类型的HAP，也可以不包含。

• Library类型的Module： 用于实现代码和资源的共享。同一个Library类型的Module可以被其他的Module多次引用，合理地使用该类型的Module，能够降低开发和维护成本。Library类型的Module分为Static和Shared两种类型，编译后会生成共享包。（考点）
• Static Library：静态共享库。编译后会生成一个以.har为后缀的文件，即静态共享包HAR（Harmony Archive）。
• Shared Library：动态共享库。编译后会生成一个以.hsp为后缀的文件，即动态共享包HSP（Harmony Shared Package）。

实际上，Shared Library编译后除了会生成一个.hsp文件，还会生成一个.har文件。这个.har文件中包含了HSP对外导出的接口，应用中的其他模块需要通过.har文件来引用HSP的功能。为了表述方便，我们通常认为Shared Library编译后生成HSP。

Stage模型应用程序包结构

开发态包结构

项目工程结构示意图

• AppScope目录由DevEco Studio自动生成，不可更改。

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

Module与UIAbility组件关系示意图

编译态包结构

开发态与编译态的工程结构视图

• ets目录：ArkTS源码编译生成.abc文件。

• resources目录：AppScope目录下的资源文件会合入到Module下面资源目录中，如果两个目录下存在重名文件，编译打包后只会保留AppScope目录下的资源文件。

• module配置文件：AppScope目录下的app.json5文件字段会合入到Module下面的module.json5文件之中，编译后生成HAP或HSP最终的module.json文件。

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

发布态包结构

说明

• App Pack是发布上架到应用市场的基本单元，但是不能在设备上直接安装和运行。

• 在应用签名、云端分发、端侧安装时，都是以HAP/HSP为单位进行签名、分发和安装的。

编译发布与上架部署流程图

HAP

• entry：应用的主模块，作为应用的入口，提供了应用的基础功能。

• feature：应用的动态特性模块，作为应用能力的扩展，可以根据用户的需求和设备类型进行选择性安装。

适用场景

• 单HAP场景：如果只包含UIAbility组件，无需使用ExtensionAbility组件，优先采用单HAP（即一个entry包）来实现应用开发。虽然一个HAP中可以包含一个或多个UIAbility组件，为了避免不必要的资源加载，推荐采用“一个UIAbility+多个页面”的方式。

• 多HAP场景：如果应用的功能比较复杂，需要使用ExtensionAbility组件，可以采用多HAP（即一个entry包+多个feature包）来实现应用开发，每个HAP中包含一个UIAbility组件或者一个ExtensionAbility组件。在这种场景下，可能会存在多个HAP引用相同的库文件，导致重复打包的问题。

约束限制

• 不支持导出接口和ArkUI组件，给其他模块使用。

• 多HAP场景下，App Pack包中同一设备类型的所有HAP中必须有且只有一个Entry类型的HAP，Feature类型的HAP可以有一个或者多个，也可以没有。

• 多HAP场景下，同一应用中的所有HAP的配置文件中的bundleName、versionCode、versionName、minCompatibleVersionCode、debug、minAPIVersion、targetAPIVersion、apiReleaseType相同，同一设备类型的所有HAP对应的moduleName标签必须唯一。HAP打包生成App Pack包时，会对上述参数配置进行校验。

• 多HAP场景下，同一应用的所有HAP、HSP的签名证书要保持一致。上架应用市场是以App Pack形式上架，应用市场分发时会将所有HAP从App Pack中拆分出来，同时对其中的所有HAP进行重签名，这样保证了所有HAP签名证书的一致性。在调试阶段，开发者通过命令行或DevEco Studio将HAP安装到设备上时，要保证所有HAP签名证书一致，否则会出现安装失败的问题。

调试

• 方法一： 使用DevEco Studio进行调试，详见应用程序包调试方法。

• 方法二： 使用hdc工具(可通过HarmonyOS SDK获取，在SDK的toolchains目录下)进行调试。
在调试前，需要先安装或更新HAP，此处有两种方式：
• 直接使用hdc安装、更新HAP。
• 先执行hdc shell，再使用bm工具安装、更新HAP。

例题

共享

• HAR中的代码和资源跟随使用方编译，如果有多个使用方，它们的编译产物中会存在多份相同拷贝；

• HSP中的代码和资源可以独立编译，运行时在一个进程中代码也只会存在一份。

HAR与HSP两种共享包的主要区别（考点）

HAP、HAR、HSP三者的功能和使用场景总结对比

• HAR虽然不支持在配置文件中声明pages页面，但是可以包含pages页面，并通过命名路由的方式进行跳转。

• 由于HSP仅支持应用内共享，如果HAR依赖了HSP，则该HAR文件仅支持应用内共享，不支持发布到二方仓或三方仓供其他应用使用，否则会导致编译失败。

• HAR和HSP均不支持循环依赖，也不支持依赖传递。

HAR和HSP在APP包中的形态示意图

HSP

• 应用内HSP：在编译过程中与应用包名（bundleName）强耦合，只能给某个特定的应用使用。

• 集成态HSP：构建、发布过程中，不与特定的应用包名耦合；使用时，工具链支持自动将集成态HSP的包名替换成宿主应用包名。

• 多个HAP/HSP共用的代码和资源放在同一个HSP中，可以提高代码、资源的可重用性和可维护性，同时编译打包时也只保留一份HSP代码和资源，能够有效控制应用包大小。

• HSP在运行时按需加载，有助于提升应用性能。

• 同一个组织内部的多个应用之间，可以使用集成态HSP实现代码和资源的共享。

• 多个HAP引用相同的HAR，导致的APP包大小膨胀问题。

• 多个HAP引用相同的HAR，HAR中的一些状态变量无法共享的问题。

• HSP及其使用方都必须是Stage模型。

• HSP及其使用方都必须使用esmodule编译模式。

• HSP不支持在配置文件中声明ExtensionAbility组件，但支持UIAbility（除入口ability外）组件。

• HSP不支持在设备上单独安装/运行，需要与依赖该HSP的HAP一起安装/运行。HSP的版本号必须与HAP版本号一致。

• HSP可以依赖其他HAR或HSP，但不支持循环依赖，也不支持依赖传递。

HAR

• 支持应用内共享，也可以发布后供其他应用使用。

• 作为二方库，发布到OHPM私仓，供公司内部其他应用使用。

• 作为三方库，发布到OHPM中心仓，供其他应用使用。

• 多包（HAP/HSP）引用相同的HAR时，会造成多包间代码和资源的重复拷贝，从而导致应用包膨大。

• HAR不支持在设备上单独安装/运行，只能作为应用模块的依赖项被引用。

• HAR不支持在配置文件中声明UIAbility组件与ExtensionAbility组件。

• HAR不支持在配置文件中声明pages页面，但是可以包含pages页面，并通过命名路由的方式进行跳转。

• HAR不支持引用AppScope目录中的资源。在编译构建时，AppScope中的内容不会打包到HAR中，因此会导致HAR资源引用失败。

• HAR可以依赖其他HAR，但不支持循环依赖，也不支持依赖传递。

例题