摘要
本文基于真实 HarmonyOS 项目 D:\\huawei\\one4，分析一个 ArkTS 应用如何做工程分层。项目名为“转盘决定吧”，包名 com.jiaweikang.one4，目标设备包含手机、平板和 2 合 1。文章重点不是介绍目录名，而是解释为什么要把页面、组件、服务、模型、工具、路由拆开，以及这种拆分如何影响后续的阅读功能、语音朗读、多设备适配和 AppGallery 发布。
1. 先从配置链路判断项目边界
HarmonyOS 项目不能只从 pages 开始看。真正决定应用身份和发布边界的是这几类配置：
|
AppScope/app.json5 entry/src/main/module.json5 entry/src/main/resources/base/profile/main_pages.json build-profile.json5 |
应用身份在 AppScope/app.json5：
|
{ "bundleName": "com.jiaweikang.one4", "versionCode": 2000004, "versionName": "1.0.5", "icon": "$media:layered_image", "label": "$string:app_name" } |
模块能力在 module.json5：
|
{ "deviceTypes": ["phone", "tablet", "2in1"], "pages": "$profile:main_pages", "requestPermissions": [ { "name": "ohos.permission.VIBRATE" }, { "name": "ohos.permission.INTERNET" } ] } |
这两处决定了后面所有技术约束：版本升级、设备素材、权限解释、页面路由和审核备注都要跟它们一致。
2. entry 模块的技术分层
本项目 entry/src/main/ets 的结构可以分成 7 类：
|
entryability/ 应用入口和全局初始化 pages/ 独立路由页面 views/ 首页 Tab 内部视图 components/ 可复用 ArkUI 组件 service/ 业务服务、本地数据、平台能力封装 model/ 类型模型 utils/ 随机、断点、震动等工具函数 constants/ 路由、主题等常量 |
这个分层的核心目标是控制依赖方向：
|
pages/views -> service/model/components/constants components -> constants/model service -> model/utils/platform kit utils -> pure helper |
不应该出现：
|
service -> pages utils -> UI 状态 components -> 某个业务页面 |
否则后面改一个页面，很容易牵动底层服务。
3. 页面层只做编排，不直接做持久化
例如首页 HomeView.ets 负责展示入口和触发路由：
|
router.pushUrl({ url: Routes.WHEEL }) |
阅读页 Reading.ets 负责文章列表、正文和播放按钮状态：
|
@State articles: ReadingArticle[] = ReadingLibrary.articles(); @State selectedId: string = ReadingLibrary.defaultArticleId(); @State voicePlaying: boolean = false; |
但页面不应该直接写 Preferences，不应该直接拼接语音 ReadInfo，也不应该直接维护全局转盘配置。这些都放到 service 层。
4. service 层承接业务稳定性
项目中的服务包括：
|
PreferencesStore.ets SettingsService.ets HistoryService.ets WheelService.ets ReadingLibrary.ets ReadingVoiceService.ets ScreenshotService.ets ShareService.ets SoundService.ets |
技术价值是把不稳定点集中起来：
- Preferences 读写异常
- SpeechKit 初始化失败
- 历史记录数量限制
- 转盘默认数据恢复
- 截图保存权限变化
页面只拿结果，不关心细节。
5. 路由必须集中管理
如果页面里到处写：
|
router.pushUrl({ url: 'pages/Reading' }) |
后期改路径会很痛苦。更好的方式是：
|
export class Routes { static readonly READING: string = 'pages/Reading'; static readonly WHEEL: string = 'pages/Wheel'; } |
页面调用：
|
router.pushUrl({ url: Routes.READING }) |
这不是形式主义，而是降低路由字符串出错概率。
6. 架构验收标准
判断这个工程结构是否健康，可以看 5 个问题：
7. 技术结论
小应用也需要分层。不是为了复杂，而是为了后续迭代时不崩：随机工具、阅读小站、SpeechKit 朗读、多设备适配、AGC 上架都可以在同一套架构里扩展。真正的 ArkTS 工程能力，不是写一个页面，而是让页面、服务、模型、路由和配置之间的边界稳定。再帮帮孩子吧，我这个应用用代码一个一个敲出来的，帮忙到应用市场下载一个评论一下体验一哈，谢谢支持，转盘决定吧
