ArkUI 项目结构设计：小项目 vs 大项目

网罗开发 （小红书、快手、视频号同名）

大家好，我是展菲，目前在上市企业从事人工智能项目研发管理工作，平时热衷于分享各种编程领域的软硬技能知识以及前沿技术，包括iOS、前端、Harmony OS、Java、Python等方向。在移动端开发、鸿蒙开发、物联网、嵌入式、云原生、开源等领域有深厚造诣。

图书作者：《ESP32-C3 物联网工程开发实战》
图书作者：《SwiftUI 入门，进阶与实战》
超级个体：COC上海社区主理人
特约讲师：大学讲师，谷歌亚马逊分享嘉宾
科技博主：华为HDE/HDG

我的博客内容涵盖广泛，主要分享技术教程、Bug解决方案、开发工具使用、前沿科技资讯、产品评测与使用体验 。我特别关注云服务产品评测、AI 产品对比、开发板性能测试以及技术报告，同时也会提供产品优缺点分析、横向对比，并分享技术沙龙与行业大会的参会体验。我的目标是为读者提供有深度、有实用价值的技术洞察与分析。

展菲：您的前沿技术领航员

👋 大家好，我是展菲！

📱 全网搜索"展菲"，即可纵览我在各大平台的知识足迹。

📣 公众号"Swift社区"，每周定时推送干货满满的技术长文，从新兴框架的剖析到运维实战的复盘，助您技术进阶之路畅通无阻。

💬 微信端添加好友"fzhanfei"，与我直接交流，不管是项目瓶颈的求助，还是行业趋势的探讨，随时畅所欲言。

📅 最新动态：2025 年 3 月 17 日

快来加入技术社区，一起挖掘技术的无限潜能，携手迈向数字化新征程！

文章目录

- 引言
- 一、小项目为什么"看起来很简单"？
- - 为什么这样可以？
  - 小项目的本质
- 二、小项目结构的"隐性问题"
- - 一旦项目变大，就会出现：
- 三、大项目结构的核心目标
- 四、推荐的大项目结构
- - 基础分层版本
  - 各层职责
- 五、从小项目演进到大项目
- - 小项目写法
  - 大项目写法
- 六、再进阶：按"业务模块"拆分
- - 示例结构
- 七、状态管理在大项目中的位置
- - 小项目
  - 大项目
  - 示例
- [八、组件设计差异（小 vs 大）](#八、组件设计差异（小 vs 大）)
- - 小项目组件
  - 大项目组件
- 九、一个非常实用的判断标准
- - 如果你开始出现：
- 十、常见误区
- 总结
- - 小项目
  - 中型项目
  - 大型项目

引言

很多人刚开始写 ArkUI 项目时，结构都很简单：

复制代码

entry
 ├─ pages
 ├─ components
 └─ utils

写 Demo、写小工具完全没问题。

但只要项目稍微复杂一点，就会开始出现熟悉的问题：

页面越来越大
逻辑到处都是
状态难以管理
改一个功能影响一大片

最后你会发现：

问题不是功能难，而是结构撑不住。

一、小项目为什么"看起来很简单"？

先看一个典型小项目结构：

复制代码

entry
 ├─ pages
 │   ├─ Home.ets
 │   └─ Detail.ets
 │
 ├─ components
 │
 └─ utils

为什么这样可以？

因为小项目通常有几个特点：

页面少（3～5个）
逻辑简单
数据量小
没有复杂状态

所以：

ts 复制代码

// 页面里直接写逻辑
async loadData() {
  const res = await fetch(...)
  this.list = res
}

也不会出大问题。

小项目的本质

"页面驱动"

复制代码

Page = UI + 逻辑 + 数据

结论：

小项目不是结构好，而是复杂度还没暴露

二、小项目结构的"隐性问题"

很多人会说：

"我这个结构也能用啊？"

确实能用，但问题在于：

它不具备"扩展能力"

一旦项目变大，就会出现：

1、页面爆炸

ts 复制代码

Home.ets → 500 行 → 1000 行

2、逻辑分散

A 页面写接口
B 页面写业务
C 页面写状态

3、复用困难

ts 复制代码

// 同样逻辑写三遍

4、状态混乱

ts 复制代码

this.data
this.list
this.user

到处都是。

本质问题：

没有分层

三、大项目结构的核心目标

当项目变大，结构设计的目标会发生变化：

从：能跑，到：可维护、可扩展、可复用

所以，大项目必须做一件事：

分层（Layered Architecture）

四、推荐的大项目结构

基础分层版本

复制代码

entry
 ├─ pages
 ├─ components
 ├─ services
 ├─ models
 ├─ store
 └─ utils

各层职责

复制代码

pages       页面（UI 入口）
components  UI 组件
services    业务逻辑
models      数据结构
store       状态管理
utils       工具函数

核心原则：

UI、业务、数据分离

五、从小项目演进到大项目

小项目写法

ts 复制代码

@Entry
@Component
struct HomePage {

  @State list: any[] = []

  async loadData() {
    const res = await fetch("/api/list")
    this.list = await res.json()
  }

}

大项目写法

1、Model

ts 复制代码

export interface Item {
  id: number
  name: string
}

2、Service

ts 复制代码

export class ItemService {

  async getList(): Promise<Item[]> {
    const res = await fetch("/api/list")
    return await res.json()
  }

}

3、Page

ts 复制代码

@Entry
@Component
struct HomePage {

  @State list: Item[] = []

  service: ItemService = new ItemService()

  async aboutToAppear() {
    this.list = await this.service.getList()
  }

}

变化非常关键：

复制代码

Page → 不再写业务逻辑
Service → 负责逻辑

六、再进阶：按"业务模块"拆分

当项目继续变大，仅仅分层还不够。

需要：

按业务模块拆分（Feature-based）

示例结构

复制代码

entry
 ├─ features
 │   ├─ home
 │   │   ├─ pages
 │   │   ├─ components
 │   │   ├─ services
 │   │   └─ models
 │   │
 │   ├─ user
 │   │   ├─ pages
 │   │   ├─ services
 │   │   └─ models
 │
 ├─ common
 │   ├─ components
 │   ├─ services
 │   └─ utils
 │
 └─ store

本质：

从"技术分层" → "业务分层"

七、状态管理在大项目中的位置

在 ArkUI 中，状态是核心。

小项目

ts 复制代码

@State data

大项目

复制代码

store
 ├─ userStore
 ├─ appStore
 └─ gameStore

示例

ts 复制代码

class UserStore {

  user = {}

  setUser(u) {
    this.user = u
  }

}

核心：

状态必须集中管理

八、组件设计差异（小 vs 大）

小项目组件

ts 复制代码

// 直接写
Text("Hello")

大项目组件

ts 复制代码

@Component
export struct UserCard {
  @Prop user: User
}

区别：

复制代码

临时 UI → 可复用组件

九、一个非常实用的判断标准

你可以用这个来判断是否需要升级架构：

如果你开始出现：

页面超过 300 行
同一逻辑写了 2 次
状态不好管理
改一个功能影响多个页面

那就说明：

你的项目已经"超出小项目结构能力"

十、常见误区

1、一开始就用大项目结构：过度设计。

2、永远停留在小项目结构：后期崩溃。

3、只分文件，不分职责

ts 复制代码

// 分了目录，但还是乱写

本质：

结构不是目录，而是职责

总结

ArkUI 项目结构，本质是随着复杂度演进的。

小项目

复制代码

pages + components + utils

特点：

简单
快速开发

中型项目

复制代码

+ services + models

特点：

分层清晰
可维护

大型项目

复制代码

Feature-based + Store

特点：

模块化
可扩展

最后一句话总结：

在 ArkUI 中，项目结构不是一开始就定死的，而是随着复杂度"进化"的。

而你要做的，不是选一个"完美结构"，而是：

在"刚好复杂"的时候，做"刚好合理"的拆分。