Harmony NEXT开发实战：从工程目录到应用包结构的全面指南

工程目录

应用和应用包

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

当前系统提供了应用程序包开发、安装、查询、更新、卸载的管理机制，便于开发者开发和管理应用。同时，系统还屏蔽了不同的芯片平台的差异（包括x86/ARM，32位/64位等），应用程序包在不同的芯片平台都能够安装运行，这使得开发者可以聚焦于应用的功能实现

应用的多Module设计机制

• 支持模块化开发： 一个应用通常会包含多种功能，将不同的功能特性按模块来划分和管理是一种良好的设计方式。在开发过程中，我们可以将每个功能模块作为一个独立的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）

包的结构

开发态Stage（重点学习）

• AppScope > app.json5：应用的全局配置信息。
• entry：应用/服务模块，编译构建生成一个HAP。

• • src > main > ets：用于存放ArkTS源码。
  • src > main > ets > entryability：应用/服务的入口。
  • src > main > ets > pages：应用/服务包含的页面。
  • src > main > resources：用于存放应用/服务模块所用到的资源文件，如图形、多媒体、字符串、布局文件等。关于资源文件的详细说明请参考资源分类与访问。

• • src > main > module.json5：Stage模型模块配置文件，主要包含HAP的配置信息、应用在具体设备上的配置信息以及应用的全局配置信息。
  • entry > build-profile.json5：当前的模块信息、编译信息配置项，包括buildOption、targets配置等。
  • entry > hvigorfile.ts：模块级编译构建任务脚本。
  • entry >oh-package.json5：配置三方包声明文件的入口及包名。

• oh_modules：用于存放三方库依赖信息，包含应用/服务所依赖的第三方库文件。
• build-profile.json5：应用级配置信息，包括签名、产品配置等。
• hvigorfile.ts：应用级编译构建任务脚本。

编译态包结构：

从开发态到编译态，Module中的文件会发生如下变更：

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

发布态包结构：

每个应用中至少包含一个.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是发布上架到应用市场的基本单元，但是不能在设备上直接安装和运行。
• 在应用签名、云端分发、端侧安装时，都是以HAP/HSP为单位进行签名、分发和安装的。

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

FA模型（JS使用）（不做重点学习）

entry：应用/服务模块，编译构建生成一个HAP。

• src > main > js：用于存放js源码。
• src > main > js > MainAbility：应用/服务的入口。
• src > main > js > MainAbility > i18n：用于配置不同语言场景资源内容，比如应用文本词条、图片路径等资源。
• src > main > js > MainAbility > pages：MainAbility包含的页面。
• src > main > js > MainAbility > app.js：承载Ability生命周期。
• src > main > resources：用于存放应用/服务所用到的资源文件，如图形、多媒体、字符串、布局文件等。关于资源文件的详细说明请参考资源分类与访问。

• • src > main > config.json：模块配置文件，主要包含HAP的配置信息、应用在具体设备上的配置信息以及应用的全局配置信息。
  • entry > build-profile.json5：当前的模块信息、编译信息配置项，包括buildOption、targets配置等。
  • entry > hvigorfile.ts：模块级编译构建任务脚本。
  • entry >oh-package.json5：配置三方包声明文件的入口及包名。

• build-profile.json5：应用级配置信息，包括签名、产品配置等。
• hvigorfile.ts：应用级编译构建任务脚本。

具体应用程序包差别可查看官网：

HAP/HAR/HSP：文档中心

Stage模型配置文件（非常重要，开发中需要重点关注的）

每个应用项目的代码目录下必须包含应用配置文件，这些配置文件会向编译工具、操作系统和应用市场提供应用的基本信息。

在基于Stage模型开发的应用项目代码下，都存在一个app.json5配置文件、以及一个或多个module.json5配置文件。

app.json5配置文件主要包含以下内容：

• 应用的全局配置信息，包含应用的Bundle名称、开发厂商、版本号等基本信息。
• 特定设备类型的配置信息。

module.json5配置文件主要包含以下内容：

• Module的基本配置信息，包含Module名称、类型、描述、支持的设备类型等基本信息。
• 应用组件信息，包含UIAbility组件和ExtensionAbility组件的描述信息。
• 应用运行过程中所需的权限信息。

**两个文件一个是app.json和module.json5**（需重点讲解关注的两个文件）

文档中心