阅读时长约 19 分钟 | 难度★★★★☆ | 篇章第 1 篇 · 项目架构与设计哲学对应源码xuanxiang_ohos_app/entry/src/main/ets/前言随着 HarmonyOS 应用功能不断扩展代码组织方式直接决定了项目的可维护性、协作效率与未来演进空间。玄象项目作为一款包含星宿、周易、命理、风水、历法等十余个功能模块的传统文化应用采用了common/components/constants/utils/pages六层架构划分源码目录。本篇将深入剖析玄象项目的目录约定与分层架构让您掌握在 ArkTS 项目中构建清晰可维护工程结构的方法论。提示目录约定是团队协作的通用语言。良好的目录结构能让新成员在 5 分钟内理解项目骨架反之则会让协作陷入混乱。一、玄象项目 ets 源码目录总览1.1 完整目录树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 定义entryability/ └── EntryAbility.ets # 主入口 Ability entrybackupability/ └── EntryBackupAbility.ets # 备份扩展 Ability2.2 Ability 层规范玄象项目 Ability 层规范目录名 Ability 类型名entryability对应EntryAbility。一个 Ability 一个文件避免单文件多 Ability。使用export defaultAbility 类用export default导出。提示玄象项目若新增WidgetAbility应建立widgetability/WidgetAbility.ets目录结构。三、公共组件层common/components3.1 五大复用组件玄象项目common/components/包含 5 个跨模块复用组件组件文件复用场景BottomTabBarBottomTabBar.ets底部导航栏FiveElementBadgeFiveElementBadge.ets五行徽章GoldBorderCardGoldBorderCard.ets金边卡片GoldButtonGoldButton.ets金色按钮GoldTitleGoldTitle.ets金色标题3.2 组件入库准则玄象项目组件入库准则准则说明复用度 ≥ 3至少被 3 个页面引用无业务逻辑组件内部不依赖特定业务数据接口稳定通过Prop/Link暴露的接口稳定自包含样式样式不依赖外部传入3.3 组件命名规范玄象项目组件命名遵循功能描述 类型后缀模式命名模式示例形容词 名词GoldButton、GoldTitle业务名 名词BottomTabBar、FiveElementBadge形容词 业务名 名词GoldBorderCard3.4 组件导出方式// common/components/GoldButton.etsComponentexportstruct GoldButton{// ...}玄象项目组件统一使用export struct命名导出便于 IDE 自动补全。四、常量层common/constants4.1 常量层清单common/constants/ ├── Colors.ets # 颜色常量 └── Styles.ets # 样式常量4.2 常量层规范玄象项目常量层规范纯定义无逻辑常量类不应包含方法。static readonly所有常量用static readonly修饰。类型显式标注所有常量显式标注类型。4.3 常量层扩展规划玄象项目未来可扩展以下常量文件common/constants/ ├── Colors.ets # 颜色 ├── Styles.ets # 样式 ├── Typography.ets # 字体规范 ├── Motion.ets # 动画时长与曲线 ├── ZIndex.ets # 层级 z-index └── Dimensions.ets # 屏幕尺寸与响应式断点五、工具层common/utils5.1 五大工具类玄象项目common/utils/包含 5 个核心工具类工具类文件职责LunarCalendarLunarCalendar.ets农历计算、节气推算、干支推算MansionDataMansionData.ets二十八宿数据与查询HexagramDataHexagramData.ets六十四卦数据与纳甲HeavenlyStemsHeavenlyStems.ets天干地支与五行归属SolarTermsSolarTerms.ets节气时刻表与节令计算5.2 工具类设计原则玄象项目工具类设计原则静态方法为主无需实例化如LunarCalendar.getSolarTerm()。纯函数相同输入永远产生相同输出无副作用。无 UI 依赖工具类不引用 ArkUI 组件。可独立测试工具类应可在单元测试中独立测试。5.3 工具类典型实现// common/utils/HeavenlyStems.etsexportclassHeavenlyStems{staticreadonlySTEMS:string[][甲,乙,丙,丁,戊,己,庚,辛,壬,癸];staticreadonlyBRANCHES:string[][子,丑,寅,卯,辰,巳,午,未,申,酉,戌,亥];staticgetStem(index:number):string{returnHeavenlyStems.STEMS[index%10];}staticgetBranch(index:number):string{returnHeavenlyStems.BRANCHES[index%12];}staticgetFiveElement(stem:string):string{constmap:Recordstring,string{甲:木,乙:木,丙:火,丁:火,戊:土,己:土,庚:金,辛:金,壬:水,癸:水};returnmap[stem]||;}}5.4 工具类测试覆盖玄象项目工具类应有完整的单元测试覆盖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(火);});});六、页面层pages6.1 页面层组织方式玄象项目页面层采用按功能模块分目录的组织方式pages/ ├── Index.ets # 路由根 ├── SplashPage.ets # 启动页直接放在 pages 下 ├── HomePage.ets # 首页直接放在 pages 下 └── mansion/ # 星宿模块所有页面 ├── MansionListPage.ets ├── MansionDetailPage.ets └── StarTerritoryPage.ets6.2 页面命名规范玄象项目页面命名遵循功能名 Page 后缀模式命名含义MansionListPage星宿列表页MansionDetailPage星宿详情页StarTerritoryPage星野分野页AiNamingPageAI 取名页AiAssistantPageAI 助手页提示页面命名避免缩写使用完整单词便于理解。6.3 功能模块目录规划玄象项目按功能模块划分目录目录模块页面数mansion/二十八星宿3yijing/周易易学4mingli/八字命理3fengshui/风水罗盘5astronomy/天文历法4music/乐律1geography/地理九州1naming/AI 取名2assistant/AI 助手1stems/天干地支2profile/用户中心26.4 页面级组件 vs 公共组件玄象项目对组件的划分原则类型位置复用度公共组件common/components/≥ 3 个页面页面级组件页面内部Builder单页面使用// 页面级组件在 HomePage 内部定义为 BuilderBuilderTodayHeavenCard(){// ...}BuilderBottomNavBar(){// ...}七、路由根层Index.ets7.1 Index.ets 的特殊性玄象项目Index.ets是应用路由根特殊性在于必须注册到路由表pages/Index必须出现在main_pages.json。必须用Entry标注作为应用启动后第一个加载的页面。必须返回Navigation容器作为应用路由根的容器。7.2 Index.ets 与其他页面的关系应用启动 ↓ EntryAbility.onWindowStageCreate ↓ loadContent(pages/Index) ↓ Index.ets 渲染 Navigation 容器 ↓ SplashPage 作为初始内容渲染 ↓ 3 秒后 router.replaceUrl 到 HomePage ↓ 后续所有页面通过 router.pushUrl 跳转八、跨层依赖规则8.1 分层依赖关系玄象项目六层架构的依赖关系遵循单向依赖原则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 动态共享包随着功能扩展玄象项目可将部分功能拆分为 HSPHarmony Shared Packagexuanxiang_ohos_app/ ├── entry/ # 主入口模块 ├── features/ │ ├── mansion/ # 星宿功能 HSP │ ├── yijing/ # 周易功能 HSP │ └── mingli/ # 命理功能 HSP └── commons/ # 公共代码 HAR9.3 第三阶段HAR 静态共享包玄象项目若孵化出独立的小工具如每日宜忌可拆分为 HARHarmony Archive静态共享包发布到 OHPM 中心供其他应用复用。9.4 演进决策矩阵触发条件演进方向团队规模扩大≥ 5 人按功能拆分 HSP应用体积超过 100MB拆分动态加载 HSP出现可独立复用的功能拆分为 HAR 发布出现跨应用共享的需求发布到 OHPM十、玄象项目目录约定最佳实践10.1 命名总规范玄象项目目录命名总规范目录名小写mansion/而非Mansion/。文件名 PascalCaseMansionListPage.ets而非mansion_list_page.ets。类名 PascalCaseHeavenlyStems而非heavenlyStems。常量 UPPER_SNAKE_CASEPRIMARY_GOLD而非primaryGold。方法名 camelCasegetSolarTerm()而非GetSolarTerm()。10.2 文件大小建议玄象项目对单个.ets文件大小的建议文件类型建议行数超出处理页面组件≤ 500 行拆分为多个Builder公共组件≤ 300 行拆分子组件工具类≤ 800 行按职责拆分为多个类常量类≤ 200 行按主题拆分10.3 import 顺序规范玄象项目 import 顺序规范// 1. HarmonyOS 官方 Kitimport{router}fromkit.ArkUI;import{hilog}fromkit.PerformanceAnalysisKit;// 2. 三方库import{describe,it}fromohos/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