从零构建鸿蒙应用：深度解析应用架构与项目结构

目录

导言

HarmonyOS应用的基本组成：FA（Feature Ability）和 PA（Particle Ability）

Feature Ability (FA) - 功能可见的交互单元

Particle Ability (PA) - 功能内聚的后台服务单元

FA 与 PA 的关系与协作

项目目录详解：entry、library、build.gradle、ohos.config.json等关键文件和目录的作用

关键文件和目录详解

总结

导言

HarmonyOS（鸿蒙操作系统）作为面向万物互联时代的新一代智能终端操作系统，其应用开发理念与传统的单设备应用开发有着显著区别。理解鸿蒙应用的架构思想和项目结构，是开发者高效构建分布式应用、充分利用鸿蒙特性的基石。本章将深入剖析鸿蒙应用的核心组成单元（FA/PA）、项目目录结构以及依赖管理机制。

HarmonyOS应用的基本组成：FA（Feature Ability）和 PA（Particle Ability）

鸿蒙应用的核心设计理念是“一次开发，多端部署”，其实现基础在于将应用功能拆解为独立、可复用的能力单元。这些能力单元主要分为两类：Feature Ability (FA) 和 Particle Ability (PA)。

Feature Ability (FA) - 功能可见的交互单元

• 定位： FA 代表了用户可以直接感知和交互的应用界面部分。它是应用的“门面”，负责展示UI、处理用户输入和导航。

• 形态： 通常表现为一个独立的 UI 页面 (Page Ability 是 FA 最主要的实现形式)。

• 特点：

  • 有UI： 必须包含用户界面（声明式 UI 如 ArkTS）。

  • 独立入口： 通常作为用户启动应用或功能模块的起点，在设备桌面上有对应的图标。

  • 生命周期管理： 拥有完整的生命周期（onStart, onActive, onInactive, onBackground, onForeground, onStop），由系统管理其状态切换。

  • 跨设备启动： 支持被同一用户的其他设备上的应用或服务远程启动（需配置权限），实现分布式流转。

• 使用场景： 应用的首页、商品详情页、设置页面、播放器界面等任何需要直接与用户交互的界面。

Particle Ability (PA) - 功能内聚的后台服务单元

• 定位： PA 代表了应用的后台服务或数据处理能力。它专注于执行后台任务、提供数据访问或计算服务，通常没有用户界面。它是应用的“引擎”。

• 形态： 主要实现形式是 Service Ability 和 Data Ability。

  • Service Ability: 用于执行后台运行任务（如下载文件、播放音乐、长时间计算、与设备硬件交互）。

  • Data Ability: 用于提供统一的数据访问接口（如操作本地数据库、文件或跨应用共享数据）。它抽象了底层数据存储细节。

• 特点：

  • 无UI (通常)： 专注于后台逻辑执行或数据操作。

  • 被调用执行： 不能独立运行，需要被 FA 或其他 PA (通过 Intent 或 AbilitySlice 的 connectAbility 方法) 启动或连接来触发其功能。

  • 生命周期： 同样拥有生命周期（如 Service Ability 有 onStart, onCommand, onConnect, onDisconnect, onStop），但其触发和管理方式与 FA 不同。

  • 跨设备调用： 可以被同一用户的其他设备上的应用或服务远程调用（需配置权限），实现分布式能力共享。

• 使用场景： 后台音乐播放服务、文件下载服务、位置信息服务、数据库操作封装、提供传感器数据访问接口等。

FA 与 PA 的关系与协作

• 解耦与复用： FA 和 PA 的设计实现了前端交互与后端逻辑的分离，使得 PA 可以被多个不同的 FA 复用。

• 协同工作： 一个典型的鸿蒙应用由一个或多个 FA 和 PA 组成。FA 负责展示信息和接收用户指令，当需要执行耗时操作、访问数据或使用设备能力时，FA 会启动或连接相应的 PA 来完成任务。PA 完成任务后，可以将结果返回给 FA 进行展示或触发后续操作。

• 分布式基础： FA 和 PA 都支持跨设备调用，这是鸿蒙分布式能力的核心体现。一个设备上的 FA 可以启动或连接到另一个设备上的 PA，实现能力的无缝流转和协同。

• AbilitySlice： FA (Page Ability) 内部可以包含一个或多个 AbilitySlice。AbilitySlice 是单个页面的具体内容和逻辑承载者，一个 Page Ability 可以管理多个 AbilitySlice 的导航栈（类似于 Android 的 Activity 和 Fragment 的关系）。

 FA 是应用的“脸面”和“入口”，负责用户交互；PA 是应用的“肌肉”和“内脏”，负责后台服务和数据处理。它们通过清晰的边界和定义的接口（如 Intent）进行通信和协作，共同构建出灵活、可复用、支持分布式特性的鸿蒙应用。

项目目录详解：entry、library、build.gradle、ohos.config.json等关键文件和目录的作用

一个标准的鸿蒙应用项目（使用 DevEco Studio 创建）遵循清晰的结构。理解每个目录和文件的作用是高效开发和维护项目的基础。以下是一个典型项目结构的详解：

MyHarmonyApp/  (项目根目录)
├── entry/          # 主模块 - 应用入口
│   ├── src/
│   │   ├── main/
│   │   │   ├── java/         # Java 代码 (可选)
│   │   │   ├── js/           # JS 代码 (旧版UI, 逐渐淘汰)
│   │   │   ├── ets/          # ArkTS 代码 (主要开发语言，声明式UI)
│   │   │   │   ├── Application/  # 应用级逻辑 (可选，如全局状态)
│   │   │   │   ├── MainAbility/  # 主FA（Page Ability）及其Slice
│   │   │   │   ├── pages/        # 通常放置AbilitySlice对应的UI页面 (index.ets)
│   │   │   │   ├── service/      # Service Ability (PA) 实现
│   │   │   │   ├── data/         # Data Ability (PA) 实现
│   │   │   │   └── ...           # 其他自定义能力或工具类目录
│   │   │   ├── resources/    # 资源文件 (图片、字符串、布局、配置文件等)
│   │   │   │   ├── base/
│   │   │   │   │   ├── element/   # 公共元素定义 (字符串string.json, 颜色color.json, 尺寸float.json等)
│   │   │   │   │   ├── media/     # 媒体资源 (图片、音频、视频等)
│   │   │   │   │   └── profile/   # 页面布局文件 (主要对应JS UI, ArkTS UI 多在ets中定义)
│   │   │   │   └── en_US/     # 英文资源 (或其他语言目录，如zh_CN)
│   │   │   │       ├── element/
│   │   │   │       └── ...
│   │   │   ├── config.json    # **模块级配置文件 (极其重要!)**
│   │   │   └── ...            # 其他配置文件
│   │   └── ohosTest/      # 测试代码目录 (可选)
│   └── build.gradle       # **entry模块的构建脚本 (Gradle)**
├── AppScope/        # 配置文件	
│   ├── resources/ # 用于存放应用需要用到的资源文件
│   │   └── base/
│   │       ├── element/        # 文件夹主要存放公共的字符串、布局文件等资源
│   │       ├── media/  # 存放全局公共的多媒体资源文件
│   └── app.json5   # 用于声明应用的全局配置信息，比如应用Bundle名称、应用名称、应用图标、应用版本号等
├── build-profile.json5       # 工程级或Module级的构建配置文件，包括应用签名、产品配置等。
├── hvigorfile.ts   # 工程级或Module级的编译构建任务脚本，开发者可以自定义编译构建工具版本、控制构建行为的配置参数。
├── oh-package.json5            # 用于存放依赖库的信息，包括所依赖的三方库和共享包。
└── oh_modules/    # 工程的依赖包，存放工程依赖的源文件

关键文件和目录详解

• entry/ (主模块)：

  • 作用： 这是应用的默认启动模块，包含应用的主入口 Ability (通常是 MainAbility/EntryAbility) 及其相关代码、资源和配置文件。最终打包成 .hap (HarmonyOS Ability Package) 文件的就是这个模块（或其变体如 entry-default.hap）。

  • src/main/ets/： 核心开发目录。Application 可选，用于应用全局逻辑。MainAbility 是主页面 Ability。pages/ 目录通常存放各个 UI 页面（AbilitySlice 对应的 ArkTS UI 文件，如 index.ets）。service/ 和 data/ 存放对应的 PA 实现。

  • src/main/resources/： 资源管理核心目录。base/ 是默认资源。en_US/, zh_CN/ 等是按语言区域划分的资源目录，系统会根据设备语言自动加载对应资源。element/ 下的 JSON 文件定义字符串、颜色、尺寸等常量。media/ 存放图片等多媒体。profile/ 下的 JSON 文件主要用于定义 JS UI 的布局（ArkTS UI 通常直接在 .ets 文件中定义 UI 结构）。

  • src/main/config.json (模块级配置文件 - 核心！)： 这是该模块（entry）的核心配置文件，定义了模块的所有元信息，必须存在。主要配置项包括：

    • app: 应用基本信息（包名 bundleName, 应用名称 vendor, 版本号 version）。

    • deviceConfig: 支持的设备类型（default, tablet, tv, wearable, car 等）及其具体配置（如屏幕分辨率要求、权限申请 reqPermissions）。

    • module: 模块核心配置。包括：

      • name: 模块名。

      • type: 模块类型 (entry 或 feature - 相当于可独立安装的功能模块)。

      • srcEntry: 模块入口（通常是 ./ets/MainAbility/MainAbility.ts）。

      • abilities: 最重要的数组之一。在此处声明该模块包含的所有 Ability (FA 和 PA)。每个 Ability 需要配置其 name (类名), icon, label, type (page for FA, service or data for PA), launchType (standard or singleton), visible (是否允许其他应用调用)，以及最重要的 skills (定义该 Ability 能响应的 Intent 动作和数据类型，决定如何被启动)。对于 Page Ability，还需要指定其 mainAbility 属性是否为 true (通常是主入口 FA)。

      • requestPermissions: 声明该模块运行所需申请的权限列表。

      • distro: 模块分发信息（如 deliveryWithInstall - 是否随应用安装时安装）。

      • js / metadata / shortcuts / 等：其他可选配置。

• AppScope/
  • resources/：用于存放应用需要用到的资源文件。
    • base/element：文件夹主要存放公共的字符串、布局文件等资源
    • base/media：存放全局公共的多媒体资源文件
  • app.json5：用于声明应用的全局配置信息，比如应用Bundle名称、应用名称、应用图标、应用版本号等。
• build-profile.json5：工程级或Module级的构建配置文件，包括应用签名、产品配置等。
• hvigorfile.ts：工程级或Module级的编译构建任务脚本，开发者可以自定义编译构建工具版本、控制构建行为的配置参数。
• oh-package.json5：用于存放依赖库的信息，包括所依赖的三方库和共享包。
• oh_modules/：工程的依赖包，存放工程依赖的源文件。

总结

深入理解鸿蒙应用的 FA/PA 架构、清晰掌握项目目录结构与核心配置文件的作用、以及熟练运用依赖管理机制，构成了鸿蒙应用开发的坚实基础。这不仅仅是项目结构的认知，更是对鸿蒙分布式理念和模块化思想的实践。在后续章节中，我们将基于这些知识，深入探索 UI 开发、Ability 生命周期管理、数据存储、设备互联等具体开发技能。