企业级 Jetpack Compose 项目（入门版）最佳结构

企业级 Jetpack Compose 项目（入门版）最佳结构

适合人群

• Compose 初学者
• Android 中大型业务
• 后续可扩展模块化
• 团队协作
• MVVM
• Clean Architecture（轻量版）
• 不分 module（先单 module）

---

一、推荐技术栈（2026 企业标准）

分类	技术	说明
核心	Kotlin	官方
UI	Jetpack Compose	UI 框架
UI 规范	Material3	UI 规范
页面跳转	Navigation Compose	页面跳转
状态管理	ViewModel	状态管理
UI 状态	StateFlow	UI 状态
异步	Coroutines	异步
网络	Retrofit	网络请求
网络拦截	OkHttp	网络拦截
JSON	Kotlin Serialization / Gson	JSON 解析
本地数据库	Room	本地数据库
DI 注入	Hilt	DI 注入
图片加载	Coil	图片加载

---

二、真正适合企业的目录结构

不分 module，但已经是企业规范。

app/
├── api/                          # 网络层
│   ├── ApiService.kt
│   ├── ApiClient.kt
│   └── interceptor/
│
├── base/                         # 基类
│   ├── BaseViewModel.kt
│   ├── BaseActivity.kt
│   ├── BaseRepository.kt
│   └── UiState.kt
│
├── common/                       # 通用
│   ├── constants/
│   ├── ext/
│   ├── utils/
│   └── manager/
│
├── data/                         # 数据层
│   ├── model/
│   ├── dto/
│   ├── entity/
│   ├── repository/
│   └── local/
│
├── ui/
│   ├── theme/
│   ├── components/
│   ├── navigation/
│   └── pages/
│       ├── home/
│       ├── login/
│       ├── profile/
│       └── ...
│
├── viewmodel/
│
├── di/                           # Hilt 依赖注入
│
├── route/                        # 路由常量
│
├── App.kt
└── MainActivity.kt

---

三、为什么这样设计

这是企业项目的"渐进式架构"

不是：

feature-home
feature-login
feature-user

这种上来就模块化。

因为：

新人最容易死在：

• module 依赖
• component 依赖
• Hilt 跨 module
• navigation 共享
• 多 module 调试

导致：

Compose 还没学会，架构先崩了。

所以，企业正确成长路线：

第一阶段（你现在）

单 module

但是分层、规范、MVVM、状态管理、UI 规范、Repository、网络层全部完整。

第二阶段

再拆：

feature-home
feature-login
core-network
core-ui
core-common

这才是真正企业路线。

---

四、Compose 企业规范（核心）

1. 页面结构：Page + ViewModel

例如：

• HomePage.kt
• HomeViewModel.kt

不要：

• HomeScreen.kt
• HomeScreen2.kt
• HomeContent.kt

新人很容易乱。

2. UI 状态统一管理

不要：

var loading by mutableStateOf(false)
var list by mutableStateOf(...)
var error by mutableStateOf(...)

企业规范：

data class HomeUiState(
    val loading: Boolean = false,
    val list: List<Article> = emptyList(),
    val error: String = ""
)

ViewModel：

private val _uiState = MutableStateFlow(HomeUiState())
val uiState = _uiState.asStateFlow()

Compose：

val uiState by viewModel.uiState.collectAsState()

3. 不要把网络写进 ViewModel

错误：

viewModelScope.launch {
    retrofit.getList()
}

正确：

ViewModel
     ↓
Repository
     ↓
Api

---

五、企业级 Compose 页面结构

推荐：

home/
├── HomePage.kt
├── HomeViewModel.kt
├── HomeUiState.kt
├── HomeAction.kt
├── components/
│   ├── Banner.kt
│   ├── ArticleItem.kt
│   └── ...

为什么？

企业项目页面越来越大。如果 HomePage.kt 写 3000 行，后期必炸。

---

六、企业级 Navigation 规范

route 统一管理

object Route {
    const val HOME = "home"
    const val LOGIN = "login"
    const val PROFILE = "profile"
}

NavigationHost

NavHost(
    navController = navController,
    startDestination = Route.HOME
) {
    composable(Route.HOME) {
        HomePage()
    }
    composable(Route.LOGIN) {
        LoginPage()
    }
}

---

七、企业级 Compose UI 规范

1. 组件化

不要：

Column {
    ...
}

写几千行。

应该：

HomeHeader()
BannerSection()
ArticleList()

2. 组件命名规范

类型	命名示例
页面	HomePage、LoginPage、ProfilePage
组件	UserCard、ArticleItem、HomeBanner
Dialog	DeleteDialog、LogoutDialog

---

八、企业级状态管理（重点）

页面只做：

• 状态消费

when {
    uiState.loading -> { ... }
    uiState.error.isNotEmpty() -> { ... }
    else -> { ... }
}

不要： 页面自己请求网络、写业务、处理数据。

---

九、企业级主题规范

theme/
├── Color.kt
├── Theme.kt
├── Type.kt
└── Dimens.kt

不要魔法值：

• ❌ padding(13.dp)
• ✅ padding(AppDimens.Space16)

---

十、真正企业级开发流程

一个新页面如何开发？

1. 定义 UI 状态：data class UserUiState()
2. 写 Repository：class UserRepository
3. 写 ViewModel：class UserViewModel
4. 写 Compose 页面：UserPage()
5. 拆组件：UserHeader、UserInfo、UserList
6. 接 Navigation

---

十一、新人最容易踩的坑

1. Compose 写成 XML 思维

• ❌ 一个页面几千行

2. 所有状态都用 mutableStateOf

• 企业里大部分：StateFlow + UiState

3. 页面直接请求网络

• ❌ 禁止

4. Navigation 乱跳

• ❌ 必须 route 统一、参数统一、页面唯一入口

5. Composable 乱传 ViewModel

• ❌ ArticleItem(viewModel)
• ✅ ArticleItem(article = xxx, onClick = {})

组件：无状态化 ------ 这是企业核心。

---

十二、推荐学习路线

第一阶段

先掌握：

• Compose 基础
• State
• StateFlow
• Navigation
• ViewModel

第二阶段

再学：

• Hilt
• Repository
• Room
• Retrofit

第三阶段

再学：

• MVI
• 多 module
• Compose 性能优化
• Design System
• 动态化

---

十三、真正适合你的项目模板

推荐练手项目：资讯类 APP

因为包含：

• Banner
• Tab
• 列表
• 登录
• 收藏
• 搜索
• 网络
• 分页
• 状态管理

几乎企业全覆盖。

---

十四、最终推荐

如果你是：Compose 入门 → 企业路线

那么最佳方案：单 module + 企业规范目录

不要一开始：

• Clean Architecture 究极版
• MVI 究极版
• 多 module
• 插件化

否则：80% 新人直接崩。

真正企业成长路线

Compose 基础
     ↓
规范 MVVM
     ↓
Repository
     ↓
状态管理
     ↓
组件化
     ↓
模块化
     ↓
大型架构

这才是正确路线。

---

十五、Flow + ViewModel 企业标准组合

是的。现在企业里：Flow + ViewModel 是标准组合。

不是 "有了 Flow 就不用 ViewModel"，而是 ViewModel 负责管理 Flow。

1. 三者关系

角色	ViewModel	Flow	Compose
定位	生命周期 + 状态管理层	数据流	UI 层
负责	持有 UI 状态、页面数据管理、页面销毁不丢数据、协程作用域、调用 Repository	数据变化通知、响应式更新、异步流、状态分发	显示状态、响应用户操作

所以真正企业结构：

Compose UI
    ↑ collectState
ViewModel
    ↑ StateFlow
Repository
    ↑ Flow
DataSource / API

2. 企业里真正的标准写法

ViewModel：

@HiltViewModel
class HomeViewModel @Inject constructor(
    private val repository: HomeRepository
) : ViewModel() {

    private val _uiState = MutableStateFlow(HomeUiState())
    val uiState = _uiState.asStateFlow()

    init {
        loadData()
    }

    private fun loadData() {
        viewModelScope.launch {
            repository.getArticleList()
                .collect { list ->
                    _uiState.update {
                        it.copy(articleList = list)
                    }
                }
        }
    }
}

Repository：

class HomeRepository @Inject constructor(
    private val api: ApiService
) {
    fun getArticleList(): Flow<List<Article>> = flow {
        emit(api.getArticleList())
    }
}

Compose：

@Composable
fun HomePage(
    viewModel: HomeViewModel = hiltViewModel()
) {
    val uiState by viewModel.uiState.collectAsState()

    LazyColumn {
        items(uiState.articleList) { article ->
            // ...
        }
    }
}

3. 为什么现在大量推荐 Flow

能力	Flow
Kotlin 官方	✅
协程支持	✅
链式操作	✅
combine	✅
debounce	✅
retry	✅
异常处理	✅
Room 支持	✅
Compose 支持	✅

4. ViewModel 为什么没淘汰

因为 Flow 不负责：

• 生命周期
• 页面状态保存
• configuration change
• viewModelScope
• 页面逻辑管理

举个例子：屏幕旋转时，如果没有 ViewModel，页面重建，数据重新请求，用户体验很差。而 ViewModel 可以保留状态。

5. 现在企业最主流的组合

层级	技术
UI 层	Compose
状态层	ViewModel
响应式层	StateFlow
数据层	Repository

6. StateFlow 和 SharedFlow 区别

StateFlow --- 用于 UI 状态

• 有初始值
• 保存最新状态
• 例如：val uiState: StateFlow<HomeUiState>

SharedFlow --- 用于一次性事件

• 无初始值
• 例如：Toast、跳转、Dialog、支付结果
• 例如：private val _event = MutableSharedFlow<HomeEvent>()

7. 企业现在已经很少用

• ❌ LiveData / MutableLiveData
• ❌ XML
• ❌ Fragment + XML

8. Compose 企业推荐架构（2026）

Compose
     +
ViewModel
     +
StateFlow
     +
Repository
     +
Hilt

这是现在最稳的。

9. 很多人误区

误区 1：

❌ "Compose 不需要 ViewModel"
✅ 真正企业：Compose 更需要 ViewModel。因为 Compose 重组频繁，更需要状态管理和生命周期管理。

误区 2：

❌ "mutableStateOf 就够了"
小 Demo 可以。企业不行。企业要求页面状态统一为 data class UiState()，然后用 MutableStateFlow(UiState())。

10. 最终企业推荐

场景	推荐方案
小状态（输入框、checkbox、tab）	remember { mutableStateOf() }
页面状态（列表、网络、登录、用户信息、分页、搜索）	ViewModel + StateFlow

11. 你现在最应该学的组合

推荐顺序：

第一阶段：Compose、ViewModel、StateFlow、Navigation

第二阶段：Repository、Retrofit、Hilt、Room

第三阶段：MVI、多 Module、性能优化、Design System

12. 真正企业里的标准模板

现在很多大厂实际就是：

Compose UI
     ↓
ViewModel
     ↓
MutableStateFlow
     ↓
Repository
     ↓
Retrofit / Room

这是目前 Android 最主流方案。