HarmonyOS应用《玄象》开发实战：项目目录约定：common/components/constants/utils/pages 六层架构

阅读时长：约 19 分钟　|　难度：★★★★☆　|　篇章：第 1 篇 · 项目架构与设计哲学

对应源码：xuanxiang_ohos_app/entry/src/main/ets/

前言

随着 HarmonyOS 应用功能不断扩展，代码组织方式 直接决定了项目的可维护性、协作效率与未来演进空间。玄象项目作为一款包含星宿、周易、命理、风水、历法等十余个功能模块的传统文化应用，采用了 common/components/constants/utils/pages 六层架构 划分源码目录。本篇将深入剖析玄象项目的目录约定与分层架构，让您掌握在 ArkTS 项目中构建清晰可维护工程结构的方法论。

提示：目录约定是团队协作的"通用语言"。良好的目录结构能让新成员在 5 分钟内理解项目骨架，反之则会让协作陷入混乱。

一、玄象项目 ets 源码目录总览

1.1 完整目录树

text 复制代码

entry/src/main/ets/
├── entryability/                  # 应用入口 Ability
│   └── EntryAbility.ets
├── entrybackupability/            # 备份扩展 Ability
│   └── EntryBackupAbility.ets
├── common/                        # 公共代码层
│   ├── components/                # 复用组件
│   │   ├── BottomTabBar.ets
│   │   ├── FiveElementBadge.ets
│   │   ├── GoldBorderCard.ets
│   │   ├── GoldButton.ets
│   │   └── GoldTitle.ets
│   ├── constants/                 # 常量定义
│   │   ├── Colors.ets
│   │   └── Styles.ets
│   └── utils/                     # 工具类
│       ├── HeavenlyStems.ets
│       ├── HexagramData.ets
│       ├── LunarCalendar.ets
│       ├── MansionData.ets
│       └── SolarTerms.ets
└── pages/                         # 页面层
    ├── Index.ets                  # 路由根
    ├── SplashPage.ets             # 启动页
    ├── HomePage.ets               # 首页
    ├── mansion/                   # 二十八星宿模块
    ├── yijing/                    # 周易易学模块
    ├── mingli/                    # 八字命理模块
    ├── fengshui/                  # 风水罗盘模块
    ├── astronomy/                 # 天文历法模块
    ├── music/                     # 乐律模块
    ├── geography/                 # 地理九州模块
    ├── naming/                    # AI 取名模块
    ├── assistant/                 # AI 助手模块
    ├── stems/                     # 天干地支模块
    └── profile/                   # 用户中心模块

1.2 六层架构概览

玄象项目将源码划分为六大层级：

层级	目录	职责
1. Ability 层	`entryability/`、`entrybackupability/`	应用入口与扩展能力
2. 公共组件层	`common/components/`	跨模块复用的 UI 组件
3. 常量层	`common/constants/`	颜色、样式、配置等常量
4. 工具层	`common/utils/`	业务算法与数据处理
5. 页面层	`pages/`	所有页面级组件
6. 路由根层	`pages/Index.ets`	应用路由入口

二、Ability 层：应用入口与扩展能力

2.1 Ability 层职责

Ability 层包含玄象项目的所有 Ability 定义：

text 复制代码

entryability/
└── EntryAbility.ets              # 主入口 Ability
entrybackupability/
└── EntryBackupAbility.ets        # 备份扩展 Ability

2.2 Ability 层规范

玄象项目 Ability 层规范：

目录名 = Ability 类型名 ：entryability 对应 EntryAbility。
一个 Ability 一个文件：避免单文件多 Ability。
使用 export default ：Ability 类用 export default 导出。

提示：玄象项目若新增 WidgetAbility，应建立 widgetability/WidgetAbility.ets 目录结构。

三、公共组件层：common/components

3.1 五大复用组件

玄象项目 common/components/ 包含 5 个跨模块复用组件：

组件	文件	复用场景
`BottomTabBar`	`BottomTabBar.ets`	底部导航栏
`FiveElementBadge`	`FiveElementBadge.ets`	五行徽章
`GoldBorderCard`	`GoldBorderCard.ets`	金边卡片
`GoldButton`	`GoldButton.ets`	金色按钮
`GoldTitle`	`GoldTitle.ets`	金色标题

3.2 组件入库准则

玄象项目组件入库准则：

准则	说明
复用度 ≥ 3	至少被 3 个页面引用
无业务逻辑	组件内部不依赖特定业务数据
接口稳定	通过 `@Prop` / `@Link` 暴露的接口稳定
自包含样式	样式不依赖外部传入

3.3 组件命名规范

玄象项目组件命名遵循 功能描述 + 类型后缀 模式：

命名模式	示例
形容词 + 名词	`GoldButton`、`GoldTitle`
业务名 + 名词	`BottomTabBar`、`FiveElementBadge`
形容词 + 业务名 + 名词	`GoldBorderCard`

3.4 组件导出方式

typescript 复制代码

// common/components/GoldButton.ets
@Component
export struct GoldButton {
  // ...
}

玄象项目组件统一使用 export struct 命名导出，便于 IDE 自动补全。

四、常量层：common/constants

4.1 常量层清单

text 复制代码

common/constants/
├── Colors.ets       # 颜色常量
└── Styles.ets       # 样式常量

4.2 常量层规范

玄象项目常量层规范：

纯定义，无逻辑：常量类不应包含方法。
static readonly ：所有常量用 static readonly 修饰。
类型显式标注：所有常量显式标注类型。

4.3 常量层扩展规划

玄象项目未来可扩展以下常量文件：

text 复制代码

common/constants/
├── Colors.ets          # 颜色
├── Styles.ets          # 样式
├── Typography.ets      # 字体规范
├── Motion.ets          # 动画时长与曲线
├── ZIndex.ets          # 层级 z-index
└── Dimensions.ets      # 屏幕尺寸与响应式断点

五、工具层：common/utils

5.1 五大工具类

玄象项目 common/utils/ 包含 5 个核心工具类：

工具类	文件	职责
`LunarCalendar`	`LunarCalendar.ets`	农历计算、节气推算、干支推算
`MansionData`	`MansionData.ets`	二十八宿数据与查询
`HexagramData`	`HexagramData.ets`	六十四卦数据与纳甲
`HeavenlyStems`	`HeavenlyStems.ets`	天干地支与五行归属
`SolarTerms`	`SolarTerms.ets`	节气时刻表与节令计算

5.2 工具类设计原则

玄象项目工具类设计原则：

静态方法为主 ：无需实例化，如 LunarCalendar.getSolarTerm()。
纯函数：相同输入永远产生相同输出，无副作用。
无 UI 依赖：工具类不引用 ArkUI 组件。
可独立测试：工具类应可在单元测试中独立测试。

5.3 工具类典型实现

typescript 复制代码

// common/utils/HeavenlyStems.ets
export class HeavenlyStems {
  static readonly STEMS: string[] = ['甲', '乙', '丙', '丁', '戊', '己', '庚', '辛', '壬', '癸'];
  static readonly BRANCHES: string[] = ['子', '丑', '寅', '卯', '辰', '巳', '午', '未', '申', '酉', '戌', '亥'];

  static getStem(index: number): string {
    return HeavenlyStems.STEMS[index % 10];
  }

  static getBranch(index: number): string {
    return HeavenlyStems.BRANCHES[index % 12];
  }

  static getFiveElement(stem: string): string {
    const map: Record<string, string> = {
      '甲': '木', '乙': '木',
      '丙': '火', '丁': '火',
      '戊': '土', '己': '土',
      '庚': '金', '辛': '金',
      '壬': '水', '癸': '水'
    };
    return map[stem] || '';
  }
}

5.4 工具类测试覆盖

玄象项目工具类应有完整的单元测试覆盖：

typescript 复制代码

describe('HeavenlyStemsTest', () => {
  it('should return correct stem', 0, () => {
    expect(HeavenlyStems.getStem(0)).assertEqual('甲');
    expect(HeavenlyStems.getStem(9)).assertEqual('癸');
  });

  it('should return correct five element', 0, () => {
    expect(HeavenlyStems.getFiveElement('甲')).assertEqual('木');
    expect(HeavenlyStems.getFiveElement('丙')).assertEqual('火');
  });
});

六、页面层：pages

6.1 页面层组织方式

玄象项目页面层采用 按功能模块分目录 的组织方式：

text 复制代码

pages/
├── Index.ets                  # 路由根
├── SplashPage.ets             # 启动页（直接放在 pages 下）
├── HomePage.ets               # 首页（直接放在 pages 下）
└── mansion/                   # 星宿模块所有页面
    ├── MansionListPage.ets
    ├── MansionDetailPage.ets
    └── StarTerritoryPage.ets

6.2 页面命名规范

玄象项目页面命名遵循 功能名 + Page 后缀 模式：

命名	含义
`MansionListPage`	星宿列表页
`MansionDetailPage`	星宿详情页
`StarTerritoryPage`	星野分野页
`AiNamingPage`	AI 取名页
`AiAssistantPage`	AI 助手页

提示：页面命名避免缩写，使用完整单词便于理解。

6.3 功能模块目录规划

玄象项目按功能模块划分目录：

目录	模块	页面数
`mansion/`	二十八星宿	3
`yijing/`	周易易学	4
`mingli/`	八字命理	3
`fengshui/`	风水罗盘	5
`astronomy/`	天文历法	4
`music/`	乐律	1
`geography/`	地理九州	1
`naming/`	AI 取名	2
`assistant/`	AI 助手	1
`stems/`	天干地支	2
`profile/`	用户中心	2

6.4 页面级组件 vs 公共组件

玄象项目对组件的划分原则：

类型	位置	复用度
公共组件	`common/components/`	≥ 3 个页面
页面级组件	页面内部 `@Builder`	单页面使用

typescript 复制代码

// 页面级组件：在 HomePage 内部定义为 @Builder
@Builder
TodayHeavenCard() {
  // ...
}

@Builder
BottomNavBar() {
  // ...
}

七、路由根层：Index.ets

7.1 Index.ets 的特殊性

玄象项目 Index.ets 是应用路由根，特殊性在于：

必须注册到路由表 ：pages/Index 必须出现在 main_pages.json。
必须用 @Entry 标注：作为应用启动后第一个加载的页面。
必须返回 Navigation 容器：作为应用路由根的容器。

7.2 Index.ets 与其他页面的关系

text 复制代码

应用启动
   ↓
EntryAbility.onWindowStageCreate
   ↓
loadContent('pages/Index')
   ↓
Index.ets 渲染 Navigation 容器
   ↓
SplashPage 作为初始内容渲染
   ↓
3 秒后 router.replaceUrl 到 HomePage
   ↓
后续所有页面通过 router.pushUrl 跳转

八、跨层依赖规则

8.1 分层依赖关系

玄象项目六层架构的依赖关系遵循"单向依赖"原则：

text 复制代码

Index.ets (路由根)
   ↓
pages/ (页面层)
   ↓
common/components/ (公共组件层)
   ↓
common/utils/ (工具层)
   ↓
common/constants/ (常量层)

8.2 依赖规则矩阵

依赖方 → 被依赖方	允许	说明
pages → common/components	✓	页面使用公共组件
pages → common/utils	✓	页面使用工具类
pages → common/constants	✓	页面使用常量
common/components → common/constants	✓	组件使用常量
common/components → common/utils	✓	组件使用工具类
common/utils → common/components	✗	工具类不应依赖组件
common/constants → common/utils	✗	常量不应依赖工具
pages → pages（跨模块）	✗	页面不应跨模块互相依赖

8.3 循环依赖的规避

玄象项目规避循环依赖的方法：

常量层无依赖 ：Colors.ets 不依赖任何其他文件。
工具层仅依赖常量 ：LunarCalendar.ets 仅依赖 Colors.ets。
组件层依赖常量与工具：不依赖页面。
页面层依赖一切：但不跨模块互相依赖。

提示：ArkTS 的 import 机制可能引发循环依赖问题。良好的分层架构能从源头避免循环依赖。

九、六层架构的演进路线

9.1 当前阶段：单模块架构

玄象项目当前所有代码位于 entry 模块，符合"小而美"的初始架构。

9.2 第二阶段：HSP 动态共享包

随着功能扩展，玄象项目可将部分功能拆分为 HSP（Harmony Shared Package）：

text 复制代码

xuanxiang_ohos_app/
├── entry/                    # 主入口模块
├── features/
│   ├── mansion/              # 星宿功能 HSP
│   ├── yijing/               # 周易功能 HSP
│   └── mingli/               # 命理功能 HSP
└── commons/                  # 公共代码 HAR

9.3 第三阶段：HAR 静态共享包

玄象项目若孵化出独立的小工具（如"每日宜忌"），可拆分为 HAR（Harmony Archive）静态共享包，发布到 OHPM 中心供其他应用复用。

9.4 演进决策矩阵

触发条件	演进方向
团队规模扩大（≥ 5 人）	按功能拆分 HSP
应用体积超过 100MB	拆分动态加载 HSP
出现可独立复用的功能	拆分为 HAR 发布
出现跨应用共享的需求	发布到 OHPM

十、玄象项目目录约定最佳实践

10.1 命名总规范

玄象项目目录命名总规范：

目录名小写 ：mansion/ 而非 Mansion/。
文件名 PascalCase ：MansionListPage.ets 而非 mansion_list_page.ets。
类名 PascalCase ：HeavenlyStems 而非 heavenlyStems。
常量 UPPER_SNAKE_CASE ：PRIMARY_GOLD 而非 primaryGold。
方法名 camelCase ：getSolarTerm() 而非 GetSolarTerm()。

10.2 文件大小建议

玄象项目对单个 .ets 文件大小的建议：

文件类型	建议行数	超出处理
页面组件	≤ 500 行	拆分为多个 `@Builder`
公共组件	≤ 300 行	拆分子组件
工具类	≤ 800 行	按职责拆分为多个类
常量类	≤ 200 行	按主题拆分

10.3 import 顺序规范

玄象项目 import 顺序规范：

typescript 复制代码

// 1. HarmonyOS 官方 Kit
import { router } from '@kit.ArkUI';
import { hilog } from '@kit.PerformanceAnalysisKit';

// 2. 三方库
import { describe, it } from '@ohos/hypium';

// 3. 项目内模块
import { Colors } from '../common/constants/Colors';
import { LunarCalendar } from '../common/utils/LunarCalendar';

总结

本篇以玄象项目 entry/src/main/ets/ 六层架构为蓝本，系统剖析了 HarmonyOS ArkTS 项目的目录约定与分层架构：从 Ability 层、公共组件层、常量层、工具层、页面层到路由根层的职责划分，到跨层依赖规则、循环依赖规避、演进路线规划。掌握这套六层架构方法论，能让您在面对任何规模的 HarmonyOS 项目时都能构建出清晰可维护的工程结构。

至此，第 1 篇章"项目架构与设计哲学"全部完成。下一篇将开启第 2 篇章："启动体验：Splash 与动画"，从 《11 · SplashPage 全屏暗色背景与 Stack 层叠布局》 开始，带您深入玄象项目启动页的实现细节。

如果这篇文章对你有帮助，欢迎点赞👍、收藏⭐、关注🔔，你的支持是我持续创作的动力！

相关资源：

HarmonyOS 官方文档：ArkTS 工程目录结构
HarmonyOS 官方文档：HSP 动态共享包
HarmonyOS 官方文档：HAR 静态共享包
开源鸿蒙跨平台社区：https://openharmonycrossplatform.csdn.net