系列第 1 篇。本文先讲工程底座为什么一个看似简单的羽毛球工具不应该只堆在一个页面里而要从第一版就把入口、公共能力和业务页面拆开。一、真实问题背景羽毛球组局工具的功能并不只是一个费用计算器。它同时包含费用计算、对阵轮转、实时计分、排名统计、我的设置、主题、截图分享、语音播报等能力。如果这些逻辑全部写进entry模块前期看起来快后期会很快变成页面互相引用、状态刷新混乱、资源路径分散的局面。这个项目选择用 HarmonyOS NEXT ArkTS 做一个本地优先 App。当前工程的构建目标已经进入 API 20 区间build-profile.json5中compatibleSdkVersion是6.0.0(20)targetSdkVersion是6.1.0(23)。这意味着文章里谈到的不是旧模板项目而是面向 HarmonyOS 6.0 之后应用形态的实战整理。二、目标与边界这篇文章只处理工程基线不展开每一个业务细节。目标是回答三个问题1. App 为什么拆成entry / common / features。2. API 20 工程里哪些配置决定了运行形态。3. 后续文章如何基于这个工程继续讲响应式、多端、TTS、分享和跨设备路线。边界也要说清楚智能排阵、语音播报、手表端计分、跨设备数据流转会在后续文章展开。本文只关注工程底座不把所有能力挤进一篇里。三、工程分层当前项目的核心结构是badmintonTools/ entry/ # 应用壳、EntryAbility、页面路由壳、启动窗 common/ # 模型、服务、存储、主题、断点系统、路由常量 features/ # 首页、费用、对阵、计分、统计、我的页 AppScope/ # 应用级图标、版本、bundle 信息 doc/ # 需求、截图、宣发图、系列文章entry负责把系统入口接进来包括EntryAbility、module.json5、main_pages.json、启动窗资源和主壳页面。common放跨页面共享能力例如SessionStore、SettingsStore、FeeCalcService、ScoreSpeechService、BreakpointSystem。features放用户可见的业务页面例如features/src/main/ets/scoring/LiveScoringPage.ets。这套拆法的好处是业务页面不直接关心 Ability 生命周期服务层不依赖具体页面入口层只调度页面和全局状态。后续接入 App Linking、备份恢复、手表控制端或平板展示端时不必把核心逻辑从页面里再挖出来。四、关键配置项目根部的build-profile.json5决定 SDK 和产品配置entry/build-profile.json5、common/build-profile.json5、features/build-profile.json5分别声明 Stage 模式模块。{ products: [ { name: default, targetSdkVersion: 6.1.0(23), compatibleSdkVersion: 6.0.0(20), runtimeOS: HarmonyOS } ] }entry/src/main/module.json5则决定入口 Ability、设备类型、权限、深链和扩展能力。项目里声明了phone、tablet、2in1这为后续“手机底部 Tab、平板侧边栏、2in1 宽屏布局”打了基础。{ module: { name: entry, type: entry, deviceTypes: [phone, tablet, 2in1], mainElement: EntryAbility } }五、入口生命周期entry/src/main/ets/entryability/EntryAbility.ets做了几件关键事初始化设置存储、恢复对局数据、恢复费用缓存、设置深浅色模式、初始化响应式断点系统并在窗口创建后加载pages/Index。SettingsStore.initPrefs(this.context); SettingsStore.hydrateFromPrefs(); SessionStore.initPrefs(this.context); SessionStore.hydrateFromPrefs(); FeeCalcService.initPrefs(this.context); FeeCalcService.hydrateFromPrefs(); BreakpointSystem.init();这段代码看起来普通但它定义了应用启动后的数据顺序先恢复本地持久化再让页面读取AppStorage中的镜像状态。这样首页、计分页、排名页不需要各自到处读 Preferences只要通过StorageLink或服务层拿状态即可。六、调试命令本次工程基线验证使用 Hvigor 构建$env:DEVECO_SDK_HOME D:\HuaweiDevelopFormalStudy\DevEco Studio\sdk $env:Path D:\HuaweiDevelopFormalStudy\DevEco Studio\jbr\bin;D:\HuaweiDevelopFormalStudy\DevEco Studio\sdk\default\openharmony\toolchains;D:\HuaweiDevelopFormalStudy\DevEco Studio\tools\node; $env:Path D:\HuaweiDevelopFormalStudy\DevEco Studio\tools\hvigor\bin\hvigorw.bat assembleHap --mode module -p productdefault --no-daemon验证时间2026-06-28。当前构建结果为BUILD SUCCESSFUL。这一步很重要因为文章讲的是工程化不是只停留在目录截图。七、官方参考HarmonyOS 工程配置、Stage 模型和 ArkTS 开发建议应以华为开发者官方文档为准。可以从 HarmonyOS 应用开发文档 进入再按 SDK 版本核对对应 API 行为。八、工程验收清单build-profile.json5明确 API 20 兼容线和目标 SDK。entry / common / features职责清楚不把业务服务写进 Ability。module.json5声明多设备类型为平板和 2in1 留出口。启动时先恢复 Preferences再加载页面。当前修改通过assembleHap构建验证。九、小结一个小工具 App 如果想写成系列文章第一篇不应该急着展示所有功能而应该先把工程骨架说清楚。这个项目的价值在于它既有真实业务又有 HarmonyOS 系统能力接入点后续可以自然展开响应式布局、本地持久化、截图分享、TTS 播报、App Linking、跨设备数据流转和手表端计分。十、下一篇衔接下一篇进入 ArkUI 响应式布局同一个Index.ets如何在手机上显示底部 Tab在平板和 2in1 上切换为侧边导航。