HarmonyOS Developer 应用程序包基础知识

应用程序包概述

用户应用程序泛指运行在设备的操作系统之上，为用户提供特定服务的程序，简称“应用”。一个应用所对应的软件包文件，称为“应用程序包”。

HarmonyOS提供了应用程序包开发、安装、查询、更新、卸载的管理机制，方便开发者开发和管理HarmonyOS应用，具体如下：

• 应用软件所涉及的文件多种多样，开发者可通过HarmonyOS提供的集成开发工具将其开发的可执行代码、资源、三方库等文件整合到一起制作成HarmonyOS应用程序包，便于开发者对应用程序的部署。
• 应用软件所涉及的设备类型多种多样，开发者可通过HarmonyOS提供的应用程序包配置文件指定其应用程序包的分发设备类型，便于应用市场对应用程序包的分发管理。
• 应用软件所包含的功能多种多样，将不同的功能特性按模块来划分和管理是一种良好的设计方式。HarmonyOS提供了同一应用程序的多包管理的机制，开发者可以将不同的功能特性聚合到不同的包中，方便后续的维护与扩展。
• 应用软件涉及的芯片平台多种多样，有x86、ARM等，还有32位、64位之分，HarmonyOS为应用程序包屏蔽了芯片平台的差异，使应用程序包在不同的芯片平台都能够安装运行。
• 应用软件涉及的软件信息多种多样，有应用版本、应用名称、组件、申请权限等的信息，HarmonyOS包管理为开发者提供了这些信息的查询接口，方便开发者在程序中查询所需要的包信息。
• 应用软件涉及的资源多种多样，有媒体资源、原生资源、字符资源以及国际化的资源等，HarmonyOS包管理将不同的资源归档到不同的目录中，并集成资源索引文件，方便应用对资源的查找和使用。

应用程序包结构

Stage模型应用程序包结构

基于​​Stage模型​​开发的应用，经编译打包后，其应用程序包结构如下图应用程序包结构（Stage模型）所示。开发者需要熟悉应用程序包结构相关的基本概念。

• 在开发态，一个应用包含一个或者多个Module，可以在​​DevEco Studio​​​工程中​​创建一个或者多个Module​​​。Module是HarmonyOS应用/服务的基本功能单元，包含了源代码、资源文件、第三方库及应用/服务配置文件，每一个Module都可以独立进行编译和运行。Module分为“Ability”和“Library”两种类型，“Ability”类型的Module对应于编译后的HAP（Harmony Ability Package）；“Library”类型的Module对应于​​HAR​​​（Harmony Ability Resources）包，即编译后的.tgz文件。
  一个Module可以包含一个或多个​​​UIAbility​​​组件，如下图所示。
  图1Module与UIAbility组件关系示意图

全文中介绍到的Module默认指的是“Ability”类型的Module。

• 开发者通过DevEco Studio把应用程序编译为一个或者多个.hap后缀的文件，即HAP。HAP是HarmonyOS应用安装的基本单位，包含了编译后的代码、资源、三方库及配置文件。HAP可分为Entry和Feature两种类型。

    ○ Entry类型的HAP：是应用的主模块，在​​module.json5配置文件​​中的type标签配置为“entry”类型。在同一个应用中，同一设备类型只支持一个Entry类型的HAP，通常用于实现应用的入口界面、入口图标、主特性功能等。

    ○ Feature类型的HAP：是应用的动态特性模块，在​​module.json5配置文件​​​中的type标签配置为“feature”类型。一个应用程序包可以包含一个或多个Feature类型的HAP，也可以不包含；Feature类型的HAP通常用于实现应用的特性功能，可以配置成按需下载安装，也可以配置成随Entry类型的HAP一起下载安装（请参见​​module对象内部结构​​中的“deliveryWithInstall”）。

• 每个HarmonyOS应用可以包含多个.hap文件，一个应用中的.hap文件合在一起称为一个Bundle，而bundleName就是应用的唯一标识（请参见​​app.json5配置文件​​中的bundleName标签）。需要特别说明的是：在应用上架到应用市场时，需要把应用包含的所有.hap文件（即Bundle）打包为一个.app后缀的文件用于上架，这个.app文件称为App Pack（Application Package），其中同时包含了描述App Pack属性的pack.info文件；在云端分发和端侧安装时，都是以HAP为单位进行分发和安装的。
• 打包后的HAP包结构包括ets、libs、resources等文件夹和resources.index、module.json、pack.info等文件。

    ○ ets目录用于存放应用代码编译后的字节码文件。

    ○ libs目录用于存放库文件。库文件是HarmonyOS应用依赖的第三方代码（例如.so、.jar、.bin、.har等二进制文件）。

    ○ resources目录用于存放应用的资源文件（字符串、图片等），便于开发者使用和维护，详见​​资源文件的使用​​。

    ○ resources.index是资源索引表，由IDE编译工程时生成。

    ○ module.json是HAP的配置文件，内容由工程配置中的module.json5和app.json5组成，该文件是HAP中必不可少的文件。IDE会自动生成一部分默认配置，开发者按需修改其中的配置。详细字段请参见​​应用配置文件​​。

    ○ pack.info是Bundle中用于描述每个HAP属性的文件，例如app中的bundleName和versionCode信息、module中的name、type和abilities等信息，由IDE工具生成Bundle包时自动生成。

图2 应用程序包结构（Stage模型）

FA模型应用程序包结构

基于​​FA模型​​开发的应用，其应用程序包结构如下图应用程序包结构（FA模型）所示。开发者需要熟悉应用程序包结构相关的基本概念。

FA模型与Stage模型不同之处在于HAP内部文件存放位置不同，FA模型将所有的资源文件、库文件和代码文件都放在assets文件夹中，在文件夹内部进一步区分。

• config.json是应用配置文件，IDE会自动生成一部分模块代码，开发者按需修改其中的配置。详细字段请参见​​应用配置文件​​。
• assets是HAP所有的资源文件、库文件和代码文件的集合，内部可以分为entry和js文件夹。entry文件夹中存放的是resources目录和resources.index文件。
• resources目录用于存放应用的资源文件（字符串、图片等），便于开发者使用和维护，详见​​资源文件的使用​​。
• resources.index是资源索引表，由IDE调用SDK工具生成。
• js文件夹中存放的是编译后的代码文件。
• pack.info是Bundle中用于描述每个HAP属性的文件，例如app中的bundleName和versionCode信息、module中的name、type和abilities等信息，由IDE工具生成Bundle包时自动生成。

图1 应用程序包结构（FA模型）

HAR包结构

HAR（Harmony Ability Resources）包用于实现多个模块或多个工程间的代码共享。HAR包不同于HAP，不能独立安装运行在设备上，只能作为应用模块的依赖项被引用。

HAR包对应DevEco Studio工程中的“Library”类型的​​Module​​。

HarmonyOS的HAR包复用标准的​​npm包​​发布方式，会打包成tar包（后缀为.tgz）。打包后的HAR包中包含源代码、资源文件、module.json文件（Stage模型）或config.json文件（FA模型）等。

应用程序包多HAP机制

多HAP机制设计目标

• 方便开发者模块化的管理应用，好的应用一般都是模块化管理，模块之间属于松耦合关系。多HAP方便了开发者将业务划分成多个模块，每个模块放到独立的HAP中。例如支付类应用，有统一的主界面，主界面管理“扫一扫”、“收付款”、“消息”、“理财”等各个模块。其中主界面管理其他模块的逻辑在Entry包中实现，而“扫一扫”、“收付款”、“消息”和“理财”等模块在不同的Feature包中实现。可以同时开发多个Feature包，能够实现Feature包单独的开发测试，最终由Entry包统一集成Feature包的特性。
• 方便开发者将多HAP合理地组合并部署到不同的设备上。例如应用程序包含一个Entry包和两个Featrue包（Feature1和Feature2）。其中Entry包可以部署到设备A和设备B，Feature1只能部署到设备A，Feature2包只部署到设备B上，那么开发者就可以方便的组合Entry和Feature1部署到设备A上，组合Entry和Feature2部署到设备B上。
• 方便开发者按需加载所需模块，减少包大小。开发者可以将一个应用的某些HAP配置成按需加载。应用在启动阶段初始用不到的特性，可以配置暂不加载，当用户用到这些特性的时候，可由应用自动下载这些特性HAP，一定程度上减少应用包的大小。
• 方便应用资源共享，减少程序包大小。多个HAP都需要用到的资源（包括公共资源文件、公共页面等）以及so（shared object）文件可以放到单独的HAP中，其他HAP可以到该HAP中访问资源和so文件，也一定程度上可以减少应用程序包大小。

多HAP构建视图

IDE支持在一个应用工程中进行多个HAP的开发与构建，如下图所示。

图1 多HAP构建视图

1. IDE开发态视图

• AppScope目录

   ○ ​​app.json5​​：配置应用全局描述信息，例如应用包名、版本号、应用图标、应用名称和依赖的SDK版本号等。

    ○ resources目录：放置应用的图标资源和应用名称字符串资源。
说明：

         ◊ 该目录由IDE自动生成，名称不可更改。

         ◊ AppScope目录下面的文件名与Entry、Feature模块下面的文件名不能重复，否则IDE会报错。

• entry或者featrue目录（名称可由开发者自定义）

    ○由IDE引导开发者创建的Module，在该Module中实现应用的业务逻辑；可以创建多个Module，图中entry和featrue即是创建的两个Module。

    ○ resources目录：放置该Module中所使用到的资源。

    ○ ets目录：开发者的业务逻辑。

    ○ ​​module.json5​​：配置该Module的描述信息，如：Module的名称、Module的入口代码路径、包含的组件信息等。

2. 编译打包后的视图

• 一个开发态的Module编译后生成一个部署态的HAP，Module和HAP一一对应。
• HAP中的module.json由开发视图中的app.json5和module.json5合成。
• 所有的HAP最终会编译到一个App Pack中（以.app为后缀的包文件），用于发布到应用市场。

多HAP的开发调试与发布部署流程

多HAP的开发调试与发布部署流程如下图所示。

图1 多HAP的开发调试与发布部署流程

开发

开发者通过​​DevEco Studio​​工具按照业务的需要创建多个Module，在相应的Module中完成自身业务的开发。

调试

通过DevEco Studio编译打包，生成单个或多个HAP包，即可基于HAP包进行调试。

• 使用DevEco Studio进行调试调试指导可参考​​应用程序包调试方法​​，其中提供了进行单HAP、多HAP安装调试的方法。
• 使用hdc_std工具（可通过OS SDK获取，在toolchains目录下）进行调试
  通过hdc_std安装HAP时，HAP的路径为开发平台上的文件路径，以Windows开发平台为例，命令参考如下：

// 安装、更新，多HAP可以指定多个文件路径
hdc_std install C:\entry.hap C:\feature.hap
// 执行结果
install bundle successfully.
// 卸载
hdc_std uninstall com.example.myapplication
// 执行结果
uninstall bundle successfully.

• 使用bm工具进行调试

通过bm工具安装、更新HAP时，传入的文件路径为真机上的文件路径，命令参考如下：

// 安装、更新，多HAP可以指定多个文件路径
bm install -p /data/app/entry.hap /data/app/feature.hap
// 执行结果
install bundle successfully.
// 卸载
bm uninstall -n com.example.myapplication
// 执行结果
uninstall bundle successfully.

发布

当开发的程序包满足发布要求时，可以在工具中打包编译生成App包。将该App包上架到应用市场云端，应用市场会对上架的App包校验签名，校验签名通过后会将App包中的HAP拆分出来，同时对拆分出的HAP重新添加签名，然后对HAP进行分发。

部署

用户在设备上的应用市场客户端能够看到各种各样的应用，这些应用均由云端分发而来，有些是多HAP应用，有些是单HAP应用。用户选择某个应用后，应用市场将下载应用包含的全部HAP。

应用在终端设备上的安装

下载完成后，应用市场客户端再调用系统中包管理服务的安装接口安装下载的HAP，包管理服务以应用为单位将其中所有HAP部署到指定目录下，以完成应用的安装。

多HAP使用规则

• App Pack包不能直接安装到设备上，只是上架应用市场的单元。
• App Pack包中所有HAP的配置文件中的bundleName标签必须一致。
• App Pack包中所有HAP的配置文件中的versionCode标签必须一致。
• App Pack包中同一设备类型的所有HAP中必须有且只有一个entry类型的HAP，featrue类型的HAP可以有一个或者多个，也可以没有。
• App Pack包中的每个HAP必须配置moduleName标签，同一设备类型的所有HAP对应的moduleName标签必须唯一。
• 同一应用的所有HAP签名证书要保持一致。上架应用市场是以App Pack的形式上架，并对其进行了签名。应用市场分发时会将所有HAP从App Pack中拆分出来，同时对其中的所有HAP进行重签名，这样保证了所有HAP签名证书的一致性。在调试阶段，开发者通过命令行或IDE将HAP安装到设备上时要保证所有HAP签名证书一致，否则会出现安装失败的问题。

多HAP运行机制及数据通信方式

多HAP机制主要是为方便开发者进行模块化管理。HAP和应用运行时的进程并不是一一对应的，具体运行机制如下：

• 默认情况下，应用中（同一包名）的所有UIAbility、ServiceExtensionAbility、DataShareExtensionAbility运行在同一个独立进程中，其他同类型ExtensionAbility分别运行在单独的进程。
• HAP支持在module.json5（Stage模型）或者config.json（FA模型）中通过process标签配置单独的进程（仅系统应用支持，三方应用不支持）。配置了process的HAP，其组件运行在单独的process进程中，多个HAP可以配置相同的process，则这些HAP运行在相同进程中，process配置的详细说明请参见​​module.json5配置文件​​。
• 应用运行时，同一进程中的UIAbility组件被启动时，才加载对应HAP的资源和代码。

基于上述机制，多HAP数据通信方式如下：

• 同一进程内的数据通信，请参见​​线程间通信​​。
• 跨进程的数据通信，请参见​​进程间通信​​。。
• 多HAP如果运行在同一进程，则多HAP间组件的通信方式与同一HAP内组件的通信方式相同。

应用程序包安装和卸载流程

开发者

开发者可以通过调试命令进行应用的安装和卸载，可参考​​多HAP的调试流程​​。

图1 应用程序包安装和卸载流程（开发者）

终端设备用户

开发者将应用上架应用市场后，终端设备用户可以在终端设备上使用应用市场进行应用的安装和卸载。

图2 应用程序包安装和卸载流程（终端设备用户）

文章转载自：​​https://developer.harmonyos.com/cn/docs/documentation/doc-guides-V3/application-package-overview-0000001478181125-V3?catalogVersion=V3​​