从小项目到大型鸿蒙 App 的架构变化

大家好，我是子玥酱，一名长期深耕在一线的前端程序媛 👩‍💻。曾就职于多家知名互联网大厂，目前在某国企负责前端软件研发相关工作，主要聚焦于业务型系统的工程化建设与长期维护。

我持续输出和沉淀前端领域的实战经验，日常关注并分享的技术方向包括前端工程化、小程序、React / RN、Flutter、跨端方案，
在复杂业务落地、组件抽象、性能优化以及多端协作方面积累了大量真实项目经验。

技术方向：前端 / 跨端 / 小程序 / 移动端工程化
内容平台：掘金、知乎、CSDN、简书
创作特点：实战导向、源码拆解、少空谈多落地
文章状态：长期稳定更新，大量原创输出

我的内容主要围绕前端技术实战、真实业务踩坑总结、框架与方案选型思考、行业趋势解读展开。文章不会停留在“API 怎么用”，而是更关注为什么这么设计、在什么场景下容易踩坑、真实项目中如何取舍，希望能帮你在实际工作中少走弯路。

子玥酱 · 前端成长记录官 ✨
👋 如果你正在做前端，或准备长期走前端这条路
📚 关注我，第一时间获取前端行业趋势与实践总结
🎁 可领取11 类前端进阶学习资源（工程化 / 框架 / 跨端 / 面试 / 架构）
💡 一起把技术学“明白”，也用“到位”

持续写作，持续进阶。
愿我们都能在代码和生活里，走得更稳一点 🌱

引言

很多开发者刚开始做HarmonyOS 应用时，项目规模通常不大：

• 几个页面
• 几个组件
• 一个简单的数据结构

代码结构可能是这样的：

pages components utils

一开始看起来完全没问题。

但当项目逐渐变大：

• 页面数量增加
• 业务逻辑复杂
• 团队成员变多

原来的结构很快就会出现问题：

• 代码越来越难维护
• 状态管理混乱
• 页面之间耦合严重

我在做一个鸿蒙项目时，从小型项目结构一路演进到大型应用架构，中间经历了几次比较典型的架构变化。

阶段一：小项目结构

很多鸿蒙项目一开始都是这种结构：

pages ├─ HomePage ├─ DetailPage ├─ ProfilePage components ├─ Banner ├─ Card utils ├─ request ├─ storage

例如一个页面：

@Entry@Componentstruct HomePage{@Statelist:string[]=[]aboutToAppear(){this.loadData()}asyncloadData(){this.list=awaitrequest('/api/list')}build(){List(){LazyForEach(this.list,(item)=>{ListItem(){Text(item)}})}}}

这种结构适合：

• Demo
• 小项目
• 个人练手项目

但随着页面越来越多，会出现几个问题：

• 页面逻辑越来越重
• 网络请求散落在各个页面
• 状态难以复用

阶段二：业务模块化

当页面超过20 个以上，很多团队会开始进行第一次架构调整。

从页面驱动变成业务模块驱动。

结构变成这样：

features ├─ home │ ├─ HomePage │ ├─ HomeService │ └─ components │ ├─ user │ ├─ ProfilePage │ ├─ UserService │ └─ components │ ├─ order │ ├─ OrderPage │ ├─ OrderService │ └─ components common ├─ components ├─ utils └─ request

这种结构有一个明显好处：

业务逻辑聚合在一起。

例如：

home ├─ 页面 ├─ 组件 ├─ API

Home 模块相关代码全部在同一目录。

例如：

classHomeService{asyncfetchFeed(){returnrequest('/api/feed')}}

页面调用：

aboutToAppear(){newHomeService().fetchFeed().then(res=>{this.list=res})}

这样结构会清晰很多。

阶段三：状态管理层出现

当项目继续变大，你会发现新的问题：

• 页面之间需要共享数据
• 用户信息到处传
• 状态同步困难

例如：

用户信息 登录状态 购物车数据

如果全部用@Prop或@Link传递，会非常混乱。这时候通常会引入全局状态层。

鸿蒙中常见方式：

@Provide / @Consume

例如在根组件：

@ProvideuserInfo:User={name:"Tom"}

子组件：

@ConsumeuserInfo:User

这样可以避免：

层层传参

很多大型应用还会做Store 层：

store ├─ userStore ├─ cartStore └─ appStore

例如：

classUserStore{@StateuserInfo:User|null=nulllogin(user:User){this.userInfo=user}}

这样状态管理就会更清晰。

阶段四：分层架构

当应用规模继续扩大时，仅仅模块化还不够。很多团队会引入分层架构。

典型结构是：

presentation service repository model

例如：

features └─ order ├─ pages ├─ components ├─ service ├─ repository └─ model

各层职责：

presentation（UI层）

页面 组件

service（业务逻辑层）

订单逻辑 状态处理

repository（数据层）

网络请求 本地缓存 数据库

例如：

classOrderRepository{asyncfetchOrders(){returnrequest('/api/orders')}}

Service：

classOrderService{repository=newOrderRepository()asyncgetOrders(){returnthis.repository.fetchOrders()}}

Page：

aboutToAppear(){newOrderService().getOrders().then(res=>{this.list=res})}

这样 UI 就不会直接依赖 API。

阶段五：组件系统化

当项目规模到几十个页面时，组件数量会暴涨。很多团队会建立组件系统。

例如：

design-system ├─ Button ├─ Card ├─ Modal ├─ Form └─ Table

统一设计：

• UI 风格
• 交互逻辑
• 主题

例如：

@Componentstruct AppButton{@Proptext:stringbuild(){Button(this.text).width(200).height(44)}}

所有页面统一使用：

AppButton

而不是：

Button

这样：

• UI 一致
• 维护更容易

总结

从小项目到大型鸿蒙应用，架构通常会经历这样一个演进过程：

页面驱动 ↓ 业务模块化 ↓ 状态管理层 ↓ 分层架构 ↓ 组件系统

很多项目的问题其实不是技术选型错误，而是：

架构没有随着项目规模演进。

小项目结构用在大项目上，迟早会失控。如果你准备做一个长期维护的鸿蒙应用，建议尽早规划三件事：

1、业务模块划分
2、状态管理方案
3、组件系统设计

把这三件事做好，项目规模变大时，架构会稳定很多。