引子500 行代码塞一个文件迟早要出事星空运势应用的所有代码都写在一个Index.ets文件里超过 500 行。功能跑起来没问题但每次改代码都要在文件里上下翻找——改转盘的坐标要翻到 200 行改塔罗的洗牌要翻到 400 行改导航栏要翻到 100 行。一开始图省事全塞一个文件开发速度快但维护成本越来越高。更麻烦的是三个页面的状态都耦合在一起——改转盘的逻辑可能影响星图的渲染改塔罗的状态可能影响导航栏的高亮。完整效果单文件架构的问题优点先把优点说清楚——单文件不是一无是处开发快所有代码在一个文件里跳转方便不用切换文件理解快读代码时不需要在多个文件之间跳转部署简单只有一个文件需要编译和打包对于小项目300 行单文件完全够用。但超过 500 行问题就开始显现。缺点1. 状态耦合Statepage:number0;// 导航状态StatewheelAngle:number0;// 转盘状态Statespinning:booleanfalse;// 转盘状态StateselectedSign:number-1;// 星图状态Statedealt:booleanfalse;// 塔罗状态StatetarotIdx:number[][];// 塔罗状态StatetarotOpen:boolean[][];// 塔罗状态7 个State变量全在同一个组件里。改任何一个都可能触发整个组件的重新渲染导致不必要的性能开销。2. 代码查找困难500 行代码在一个文件里找某个功能的实现需要上下翻找。虽然 IDE 有搜索功能但远不如文件级别的模块清晰。3. 复用困难转盘的旋转逻辑、塔罗的洗牌算法、星图的坐标计算——这些逻辑在当前应用中只能用一次。如果要做另一个应用比如每日塔罗需要复制粘贴代码。4. 测试困难单文件架构无法对单个功能进行单元测试。要测洗牌算法必须加载整个应用。Builder vs Component什么时候用哪个ArkUI 提供了两种代码复用方式Builder和Component。理解它们的区别是模块化的基础。Builder轻量级 UI 片段BuilderStarDetail(){Stack(){// 星图详情的 UI}}特点不能有State状态不能接收Prop或Link参数本质上是模板函数把一段 UI 代码封装起来调用方式和普通函数一样this.StarDetail()适用场景UI 片段的封装比如卡片样式、按钮样式不需要独立状态的简单组件同一页面内的代码组织Component独立组件Componentstruct StarPage{PropselectedSign:number-1;build(){Column(){// 星图页面的完整 UI}}}特点可以有State状态可以接收Prop、Link、Provide/Consume参数是独立的组件有完整的生命周期调用方式是标签语法StarPage /适用场景需要独立状态的复杂组件跨页面复用的组件需要单元测试的组件对比表特性BuilderComponent状态无有State参数普通参数Prop/Link复用性页面内复用跨页面复用性能轻量略重测试困难容易适用场景UI 片段独立组件当前应用的选择星空运势应用全部用Builder没有用Component。这是因为三个页面都在同一个组件里不需要跨组件通信。但如果要拆分就需要把Builder升级为Component。组件拆分策略怎么拆拆分的时机不是代码多就要拆而是功能独立一个功能可以独立运行比如转盘的旋转逻辑状态独立一个功能有自己的状态比如塔罗的洗牌状态复用需求一个功能要在多处使用比如卡片样式维护困难找代码要花很长时间拆分的粒度拆分不是越细越好。粒度太细会导致组件太多管理困难。建议按功能模块拆分当前结构单文件 Index.ets ├── TopNav() ├── WheelPage() ├── StarPage() ├── TarotPage() ├── StackedDeck() ├── DealtCards() ├── Readings() └── 数据定义 拆分后按功能模块 Index.ets # 主页面只负责路由和状态管理 ├── components/ │ ├── TopNav.ets # 导航栏组件 │ ├── WheelPage.ets # 转盘页面组件 │ ├── StarPage.ets # 星图页面组件 │ └── TarotPage.ets # 塔罗页面组件 ├── data/ │ ├── Signs.ts # 星座数据 │ ├── Tarot.ts # 塔罗数据 │ └── Colors.ts # 颜色配置 └── utils/ ├── shuffle.ts # 洗牌算法 └── math.ts # 数学工具函数拆分的步骤第一步提取数据数据是最容易拆分的因为数据没有依赖// data/Signs.tsexportconstSIGNS:SignData[][newSignData(白羊座,♈,3.21-4.19,火,热情勇敢·行动力强,[newStarPt(100,30,3),// ...]),// ...];第二步提取工具函数洗牌算法、日期种子、坐标计算——这些纯函数也可以轻松提取// utils/shuffle.tsexportfunctionfisherYatesShuffle(arr:number[],seed:number):number[]{constresult[...arr];letsseed;for(letiresult.length-1;i0;i--){s(s*110351524512345)%2147483648;constjs%(i1);[result[i],result[j]][result[j],result[i]];}returnresult;}第三步提取页面组件把三个页面拆分成独立的Component// components/WheelPage.etsComponentstruct WheelPage{Propspinning:booleanfalse;PropwheelAngle:number0;PropresultIdx:number-1;onSpin:()void(){};onReveal:()void(){};build(){Column(){// 转盘的 UI}}}第四步提取公共组件导航栏、卡片样式、按钮样式——这些可以跨页面复用的组件// components/TopNav.etsComponentstruct TopNav{Proppage:number0;onNavigate:(idx:number)void(){};build(){Row(){// 导航栏的 UI}}}拆分后的主页面// Index.etsEntryComponentstruct Index{Statepage:number0;StatewheelAngle:number0;Statespinning:booleanfalse;StateselectedSign:number-1;Statedealt:booleanfalse;StatetarotIdx:number[][0,1,2];StatetarotOpen:boolean[][false,false,false];build(){Column(){TopNav(page:this.page,onNavigate:(idx:number){this.pageidx;})Swiper(){WheelPage(spinning:this.spinning,wheelAngle:this.wheelAngle,...)StarPage(selectedSign:this.selectedSign,...)TarotPage(dealt:this.dealt,tarotIdx:this.tarotIdx,...)}.index(this.page).onChange((idx:number){this.pageidx;})}}}主页面只负责状态管理和路由UI 逻辑全部委托给子组件。数据与 UI 的分离原则拆分代码时一个重要的原则是数据与 UI 分离数据层定义数据结构、常量、工具函数UI 层使用数据渲染界面当前应用的问题当前应用把数据和 UI 混在一起constSIGNS:SignData[][...];// 数据Componentstruct Index{// UI 和状态}虽然数据定义在组件外面但SignData、StarPt等类定义也在同一个文件里。如果要复用这些数据必须把整个文件复制过去。改进方案把数据和类定义移到独立文件// data/types.tsexportclassPos2D{...}exportclassStarPt{...}exportclassSignData{...}exportclassTarotInfo{...}// data/Signs.tsimport{SignData,StarPt}from./types;exportconstSIGNS:SignData[][...];// data/Tarot.tsimport{TarotInfo}from./types;exportconstTAROT:TarotInfo[][...];这样每个文件职责单一修改数据不会影响 UI修改 UI 不会影响数据。状态管理的优化拆分组件后状态管理也需要优化。问题状态提升当前所有状态都在主组件里子组件通过Prop接收。这意味着每次状态变化主组件都会重新渲染然后所有子组件都会重新渲染。解决方案状态局部化把状态移到需要它的组件里// components/WheelPage.etsComponentstruct WheelPage{StatewheelAngle:number0;// 转盘角度只在转盘组件里Statespinning:booleanfalse;// 旋转状态只在转盘组件里StateresultIdx:number-1;// 结果只在转盘组件里build(){...}}// components/TarotPage.etsComponentstruct TarotPage{Statedealt:booleanfalse;// 抽牌状态只在塔罗组件里StatetarotIdx:number[][0,1,2];// 牌组只在塔罗组件里StatetarotOpen:boolean[][false,false,false];// 翻牌只在塔罗组件里build(){...}}这样每个组件管理自己的状态修改转盘状态不会触发塔罗组件的重新渲染。但有些状态需要共享page状态需要在导航栏和 Swiper 之间共享这种状态应该留在主组件里通过Prop或Link传递给子组件。踩坑记录坑 1Builder 不能有 StateBuilder不能声明State状态。如果需要状态必须用Component。这是很多新手踩的坑——以为Builder和Component一样结果发现无法添加状态。坑 2组件间的通信拆分后组件间需要通信。比如点击转盘的重新占卜按钮需要通知塔罗组件重置状态。ArkUI 提供了Provide/Consume、事件回调等方式但增加了复杂度。坑 3文件路径的引用拆分后需要 import 其他文件。ArkTS 的 import 路径相对复杂需要配置tsconfig.json的paths字段。新手容易在这里卡住。坑 4组件的生命周期Component有完整的生命周期aboutToAppear、aboutToDisappear 等Builder没有。如果需要在组件加载时执行逻辑必须用Component。代码改进建议1. 渐进式拆分不需要一次性拆完所有代码。可以按优先级逐步拆分先提取数据文件最简单再提取工具函数纯函数无依赖然后提取页面组件需要处理状态传递最后提取公共组件需要考虑复用性2. 建立目录规范entry/src/main/ets/ ├── pages/ # 页面组件 ├── components/ # 公共组件 ├── data/ # 数据定义 ├── utils/ # 工具函数 ├── styles/ # 样式配置 └── constants/ # 常量定义3. 使用 TypeScript 的模块系统ArkTS 基于 TypeScript可以充分利用 TypeScript 的模块系统export/import导出导入interface定义数据结构比class更轻量type定义类型别名enum定义枚举替代常量数组4. 考虑状态管理库对于复杂应用可以考虑引入状态管理库比如 ArkUI 的ohos.stateManagement但小项目用State就够了。总结星空运势应用的 500 行代码全部写在一个文件里短期内可以跑但长期维护会越来越痛苦。拆分代码的核心原则是单一职责——每个文件只做一件事每个组件只管一个功能。适用边界这个部分适合用作 ArkTS 代码架构和模块化的入门指南涵盖了单文件的问题、Builder vs Component、组件拆分策略、数据与 UI 分离、状态管理优化等核心知识点。但如果要上架应用商店还需要补充状态管理库、路由管理、错误处理、日志系统等内容。建议在此基础上逐步扩展而不是一次性做完所有功能。