从 Android 项目结构看 HarmonyOS 项目结构：先从目录开始建立手感

为什么第二篇先看项目结构

第一篇我先把 Android 和 HarmonyOS 的比较地图画出来：语言、应用模型、UI 范式、Native 桥接层、工程化和多设备能力。真正开始学习时，我觉得最适合落地的入口不是某个 API，而是项目结构。

原因很简单：打开一个新工程时，目录结构会先告诉你这套体系怎么组织应用。Android 开发者看到 app/src/main、AndroidManifest.xml、build.gradle，大概能猜到入口、资源和构建在哪里；到了 HarmonyOS 工程，如果一上来看到 AppScope、entry、module.json5、hvigorfile.ts、oh-package.json5，就很容易失去方向。

所以这一篇先做一件小事：把两套工程放在同一张桌面上看。

先看一张对照表

关注点	Android 常见位置	HarmonyOS 常见位置	可以先怎么理解
工作空间入口	`settings.gradle`、根目录 `build.gradle`	根目录 `build-profile.json5`、`hvigorfile.ts`	都承担“这个工程有哪些模块、怎么构建”的入口角色
应用级配置	`AndroidManifest.xml`、项目级 Gradle 配置	`AppScope/app.json5`	应用名称、图标、全局配置等信息会被拆到新的配置体系里
模块级配置	`app/build.gradle`、`src/main/AndroidManifest.xml`	`entry/module.json5`、模块级 `build-profile.json5`	HarmonyOS 更强调模块配置和 HAP/HAR/HSP 这类包形态
代码目录	`src/main/java` 或 `src/main/kotlin`	`entry/src/main/ets`	Android 侧是 Java/Kotlin，HarmonyOS 侧主要进入 ArkTS/ETS
Native 代码	`src/main/cpp`、CMake / NDK 配置	`src/main/cpp`、NAPI native module 配置	涉及 C/C++ 时，两边都会多出一层 native 构建和桥接配置
UI 资源	`res/layout`、`res/drawable`、`res/values`	`resources/base`、`resources/rawfile` 等	资源仍然独立管理，但目录命名和访问方式不同
页面入口	Activity / Fragment	UIAbility / Page / ArkUI component	不要急着找“一模一样”的入口，要先看应用模型
依赖管理	Gradle dependencies、Maven 仓库	`oh-package.json5`、ohpm	依赖声明的位置和生态源不同，迁移三方库时会很明显
构建系统	Gradle、Android Gradle Plugin	hvigor、`hvigorfile.ts`	工具链换了，任务、插件和构建脚本也要重新熟悉
产物形态	APK / AAB / AAR	HAP / HAR / HSP	不同产物会影响模块拆分、复用方式和发布流程
多设备入口	product flavors、资源限定、不同 module	`products/`、多 HAP、设备类型配置	多设备适配不只是 UI 变宽，还会进入工程结构本身

这张表仍然不是完整清单，但比“只看 app 和 entry”更接近真实工程。它先把最容易影响迁移手感的部分放在一起：配置、代码、资源、native、依赖、构建、产物和多设备入口。后面每一层都可以单独拆开讲。

Android 工程的直觉

一个普通 Android 应用通常会有这样的直觉：

project/
  settings.gradle
  build.gradle
  app/
    build.gradle
    src/main/
      AndroidManifest.xml
      java/ 或 kotlin/
      res/

这里最容易抓住的是三件事：

AndroidManifest.xml 声明组件、权限、入口 Activity。
src/main/java 或 src/main/kotlin 放业务代码。
res/ 放布局、图片、字符串、颜色、主题等资源。

如果是现代 Android 项目，还会看到更多 Jetpack 相关结构，比如 ui/、data/、domain/、viewmodel/、repository/。这不是系统强制的目录，而是工程架构逐步沉淀出来的习惯。

换句话说，Android 工程里有两层结构：一层是平台要求的结构，一层是团队自己组织业务代码的结构。

HarmonyOS 工程的第一眼

HarmonyOS 工程给 Android 开发者的第一眼冲击，往往来自这些名字：

project/
  AppScope/
    app.json5
  entry/
    src/main/
      ets/
      resources/
      module.json5
  build-profile.json5
  hvigorfile.ts
  oh-package.json5

可以先这样理解：

AppScope/app.json5 更偏应用级配置。
entry/module.json5 更偏模块级配置，也会涉及 ability 声明。
entry/src/main/ets 是 ArkTS/ETS 代码的主要位置。
resources/ 是 HarmonyOS 的资源目录。
hvigorfile.ts、build-profile.json5、oh-package.json5 和构建、依赖、工程配置有关。

如果用 Android 经验类比，entry 有点像一个主应用模块，但不要把它直接等价成 Android 的 app 模块。HarmonyOS 还有 HAP、HAR、HSP 等包形态，后面讲工程化时要单独展开。

配置文件的变化：从 Manifest 到 json5

Android 开发者很熟悉 AndroidManifest.xml。它承担了很多声明职责：Activity、Service、权限、intent-filter、应用图标、主题等。

HarmonyOS 这边会看到 app.json5 和 module.json5。这两个文件会让人感觉“Manifest 被拆开了”。粗略说：

app.json5 更靠近应用级元信息。
module.json5 更靠近模块、ability、页面入口、权限等配置。

这也是为什么我不建议一开始就问“AndroidManifest.xml 对应 HarmonyOS 的哪个文件”。更好的问题是：

> Android 里原本由 Manifest 承担的职责，在 HarmonyOS 里分别被哪些配置文件接走了？

这个问法会更接近真实工程迁移。

代码目录的变化：从 Java/Kotlin 到 ArkTS

Android 侧的代码目录通常是 java/ 或 kotlin/。即使用了 Compose，语言栈也大多是 Kotlin。

HarmonyOS 侧的代码通常进入 ets/，开发语言是 ArkTS。这个变化不只是文件后缀变了，还会影响 UI 写法、状态管理、模块组织和类型约束。

对 Android 开发者来说，这里有一个学习顺序：

1. 先看 entry/src/main/ets 下的入口文件。 2. 再看页面或组件如何组织。 3. 再看状态变量和事件处理。 4. 最后再补 ArkTS 与 TypeScript 的差异。

如果一开始就把 ArkTS 当成“另一种 Kotlin”或“随便写的 TypeScript”，后面会很容易踩坑。

资源目录的变化：熟悉但不等同

Android 的 res/ 很成熟：layout、drawable、mipmap、values、font 等目录几乎是肌肉记忆。

HarmonyOS 也有资源目录，但命名、分类和访问方式不同。Android 开发者可以先记住一个大方向：资源仍然会被平台统一管理，只是目录结构、限定方式和引用 API 发生了变化。

这一层适合后面单独写一篇，因为资源系统会牵涉到多语言、多设备、图片、颜色、字符串、rawfile 等内容。现在只需要先把它放进地图里。

工程化入口：Gradle 到 hvigor

Android 工程化绕不开 Gradle。依赖、插件、构建变体、签名、打包，基本都能在 Gradle 体系里找到入口。

HarmonyOS 侧会看到 hvigor 和 ohpm。比如官方代码工坊工程里就能看到 hvigorfile.ts、oh-package.json5、build-profile.json5 这些文件。它们对应的是 HarmonyOS 的构建、依赖和工程配置入口。

这里我现在先不展开细节，只给一个判断：

> 从 Android 转 HarmonyOS，最先不适应的往往不是 UI API，而是工程工具链。

因为工具链决定了你怎么引依赖、怎么分模块、怎么签名、怎么运行、怎么打包。真正做项目时，这些问题会比“某个 Button 怎么写”更早出现。

小结

这一篇先从目录结构建立手感。Android 和 HarmonyOS 都有应用配置、模块配置、代码目录、资源目录和构建系统，但它们的组织方式并不是一一对应。

对 Android 开发者来说，学习 HarmonyOS 的第一步不是背 ArkUI 组件，也不是马上找 Activity 的替代品，而是先看懂工程目录：

应用级配置在哪里。
模块级配置在哪里。
ArkTS 代码从哪里进入。
资源如何组织。
构建和依赖由谁负责。

参考素材

Android App architecture：https://developer.android.com/topic/architecture
Android App components overview：https://developer.android.com/guide/components/fundamentals
HarmonyOS 构建第一个 ArkTS 应用：https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/start-with-ets-stage
HarmonyOS 应用开发导读：https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/application-dev-guide
HarmonyOS 代码工坊：https://gitcode.com/HarmonyOS_Samples/sample_in_harmonyos

// Kai@CodeHubble

// 观测坐标：Android-HarmonyOS/2026-05-07