前十五课覆盖了环境搭建、UI基础、状态管理、导航、依赖注入、平台抽象、网络层、平台互操作和资源管理。从本课开始进入架构与工程化模块。本课将深入CMP应用架构设计的核心:Clean Architecture的层次职责与依赖规则、MVI模式在共享代码中的落地方式、多模块拆分策略与依赖约束、UseCase的组织与测试友好性,以及生产级架构的完整实践。本课内容基于CMP 1.12.1、Kotlin 2.3.20与Lifecycle 2.10.0。 文末附有15道配套习题与本课知识点总结。
目录
- 一、为什么需要架构设计:从单体到分层
- 二、Clean Architecture的层次与职责
- 三、MVI模式在CMP中的落地
- 四、多模块架构策略
- 五、UseCase的组织与测试友好性
- 六、生产级架构实践
- 配套习题(15题)
- 本课知识点总结
一、为什么需要架构设计:从单体到分层
1.1 架构成熟度模型
Kotlin架构成熟度可分为五个层级,这为评估和演进项目架构提供了标尺:
| 层级 | 特征信号 |
|---|---|
| Level 1 | 单一扁平包,UI/Activity中直接执行数据库/网络查询,全局可变状态,无依赖注入 |
| Level 2 | 拆分为标准包(ui、data),但业务逻辑直接存在于ViewModel或Activity中 |
| Level 3 | 清晰的MVVM/MVI分离,构造器依赖注入,ViewModel作用域正确使用,StateFlow暴露UI状态 |
| Level 4 | 多模块Gradle结构(:core、:feature),Clean Architecture分层(UI → UseCase → Repository),可注入的协程调度器,单元测试覆盖 |
| Level 5 | 清晰的KMP布局,commonMain逻辑与平台特定代码分离,完全响应式的Flow管道,DI作用域正确管理,测试覆盖率>70% |
CMP项目架构设计的核心目标,是将共享代码的架构成熟度提升到Level 4-5,同时保持跨平台的可维护性。
1.2 单体架构的痛点
在单模块CMP项目中,所有代码(UI、ViewModel、Repository、ApiService)都放在同一个 composeApp 模块中。随着项目增长,这会导致三个问题:
边界模糊。UI代码可以直接依赖Repository,业务逻辑散落在ViewModel中,UseCase层缺失,导致代码难以测试和复用。
编译时间线性增长。任何一处修改都会触发整个模块的重新编译。
团队协作冲突。多个开发者同时修改同一个模块,容易产生合并冲突。
一项针对从遗留单体迁移到CMP + Clean Architecture的企业级案例研究显示,迁移后结构性可维护性和开发者体验有明显改善,代码认知复杂度降低,并支持了并行功能开发。但研究也揭示了权衡:平均增量编译时间增加了近四倍,且团队需要适应声明式UI范式的学习曲线。
二、Clean Architecture的层次与职责
2.1 推荐的分层结构
CMP项目的Clean Architecture采用三层核心分离:
| 层次 | 职责 | 允许的依赖 |
|---|---|---|
| Domain层 | 实体模型、Repository接口、UseCase | 纯Kotlin,无任何平台导入 |
| Data层 | Repository实现、数据源(网络/数据库) | 依赖Domain层,可依赖Ktor/Room/SQLDelight |
| Presentation层 | ViewModel、Compose UI、状态管理 | 依赖Domain层,可依赖Compose/Koin |
依赖规则:依赖方向始终从外层指向内层。Presentation层可以调用Domain层的UseCase,Data层实现Domain层的Repository接口,但Domain层不能依赖任何外层。
2.2 Domain层:纯Kotlin的契约定义
Domain层是架构的核心,不依赖任何框架或平台API。它包含:
// domain/model/User.kt
data class User(
val id: Long,
val name: String,
val email: String,
)
// domain/repository/UserRepository.kt
interface UserRepository {
suspend fun getUser(id: Long): Result<User>
suspend fun getUsers(page: Int): Result<List<User>>
}
// domain/usecase/GetUserUseCase.kt
class GetUserUseCase(
private val userRepository: UserRepository,
) {
suspend operator fun invoke(userId: Long): Result<User> =
userRepository.getUser(userId)
}
Domain层中不应出现任何 androidx.*、platform.UIKit.*、io.ktor.* 的导入。这确保了Domain层的逻辑可以在所有平台上运行,且可以独立于UI框架进行单元测试。
2.3 Data层:Repository实现与数据源
Data层实现Domain层定义的接口,负责数据来源决策(Remote/Local/Cache):
// data/repository/UserRepositoryImpl.kt
class UserRepositoryImpl(
private val userApiService: UserApiService,
private val userLocalDataSource: UserLocalDataSource,
) : UserRepository {
override suspend fun getUser(id: Long): Result<User> = runCatching {
val cached = userLocalDataSource.get(id)
if (cached != null && !cached.isExpired()) {
return@runCatching cached.toDomain()
}
val remote = userApiService.getUser(id)
userLocalDataSource.save(remote)
remote.toDomain()
}
override suspend fun getUsers(page: Int): Result<List<User>> = runCatching {
userApiService.getUsers(page).map { it.toDomain() }
}
}
2.4 Presentation层:ViewModel与UI
Presentation层包含ViewModel和Compose UI。ViewModel持有屏幕状态、接收事件、调用UseCase,但不直接依赖Repository或ApiService:
// presentation/UserViewModel.kt
class UserViewModel(
private val getUser: GetUserUseCase,
) : ViewModel() {
private val _uiState = MutableStateFlow(UserUiState())
val uiState: StateFlow<UserUiState> = _uiState.asStateFlow()
fun onEvent(event: UserEvent) {
when (event) {
is UserEvent.LoadUser -> loadUser(event.userId)
}
}
private fun loadUser(userId: Long) {
viewModelScope.launch {
_uiState.update { it.copy(isLoading = true, error = null) }
getUser(userId)
.onSuccess { user -> _uiState.update { it.copy(user = user, isLoading = false) } }
.onFailure { e -> _uiState.update { it.copy(error = e.toAppError(), isLoading = false) } }
}
}
}
关键约束:在commonMain中,viewModel() 必须提供初始化器,不能使用无参调用:
// ✅ 正确
val vm = viewModel { UserViewModel(getUser = getUserUseCase) }
// ❌ 错误:在非JVM平台会失败
val vm = viewModel<UserViewModel>()
下面是 Clean Architecture 三层结构的依赖关系示意图:
三、MVI模式在CMP中的落地
3.1 为什么选择MVI
MVI(Model-View-Intent)是MVVM的增强形态,可以理解为“MVVM+”。其核心思想是将UI状态建模为不可变数据类,所有用户交互建模为密封接口事件,状态更新通过单一入口进行。MVI的核心优势在于:
单向数据流。用户操作 → Intent → ViewModel处理 → 状态更新 → UI重组,数据流始终单向。
可预测的状态管理。状态只能通过 copy() 产生新实例,杜绝了可变状态带来的不确定性。
高度可测试。ViewModel不依赖UI框架,测试时只需发送Intent并断言状态即可。
3.2 MVI三要素
MVI模式由三个核心组件构成:
// 1. State:不可变数据类,描述屏幕完整状态
data class UserUiState(
val user: User? = null,
val isLoading: Boolean = false,
val error: AppError? = null,
)
// 2. Intent:用户交互事件,密封接口保证穷尽性
sealed interface UserIntent {
data class LoadUser(val userId: Long) : UserIntent
data object DismissError : UserIntent
}
// 3. Effect:一次性副作用,不参与状态渲染
sealed interface UserEffect {
data class ShowToast(val message: String) : UserEffect
data object NavigateBack : UserEffect
}
State与Effect的关键区别:State参与UI渲染且可被重组;Effect是一次性事件(导航、Snackbar),不应在配置更改后重放。Effect通过 Channel 暴露(而非 SharedFlow),因为 SharedFlow 的replay缓存在iOS上会导致导航事件意外重放。
3.3 MVI ViewModel的实现
class UserViewModel(
private val getUser: GetUserUseCase,
) : ViewModel() {
private val _uiState = MutableStateFlow(UserUiState())
val uiState: StateFlow<UserUiState> = _uiState.asStateFlow()
private val _effects = Channel<UserEffect>(Channel.BUFFERED)
val effects: Flow<UserEffect> = _effects.receiveAsFlow()
fun onIntent(intent: UserIntent) {
when (intent) {
is UserIntent.LoadUser -> loadUser(intent.userId)
UserIntent.DismissError -> _uiState.update { it.copy(error = null) }
}
}
private fun loadUser(userId: Long) {
viewModelScope.launch {
_uiState.update { it.copy(isLoading = true, error = null) }
getUser(userId)
.onSuccess { user ->
_uiState.update { it.copy(user = user, isLoading = false) }
}
.onFailure { e ->
_uiState.update { it.copy(error = e.toAppError(), isLoading = false) }
_effects.send(UserEffect.ShowToast(e.message ?: "加载失败"))
}
}
}
}
3.4 UI层的事件消费
@Composable
fun UserScreen(viewModel: UserViewModel = koinViewModel()) {
val state by viewModel.uiState.collectAsStateWithLifecycle()
LaunchedEffect(viewModel) {
viewModel.effects.collect { effect ->
when (effect) {
is UserEffect.ShowToast -> { /* 显示Snackbar */ }
UserEffect.NavigateBack -> { /* 导航返回 */ }
}
}
}
when {
state.isLoading -> LoadingIndicator()
state.error != null -> ErrorContent(state.error, onRetry = {
viewModel.onIntent(UserIntent.LoadUser(1))
})
state.user != null -> UserContent(state.user)
}
}
下面是 MVI 模式的单向数据流示意图:
四、多模块架构策略
4.1 AGP 9.0的强制性要求
AGP 9.0不再支持在同一个模块中同时应用 com.android.application 和 org.jetbrains.kotlin.multiplatform 插件。必须将单体模块拆分为独立的平台应用模块和KMP共享库模块。
2026年的KMP默认项目结构是一个专门的 shared KMP共享库模块 + 各平台独立应用模块(androidApp、iosApp、desktopApp),而非旧版的单一 composeApp 模块。
4.2 推荐的多模块布局
// settings.gradle.kts
include(":shared")
include(":androidApp")
include(":desktopApp")
// Feature模块
include(":feature:auth:domain")
include(":feature:auth:data")
include(":feature:auth:presentation")
include(":feature:home:domain")
include(":feature:home:data")
include(":feature:home:presentation")
// Core模块
include(":core:domain")
include(":core:data")
include(":core:presentation")
include(":core:designsystem")
4.3 模块依赖规则
各模块的依赖关系遵循严格的层次约束:
// feature/auth/domain/build.gradle.kts
kotlin {
sourceSets {
commonMain.dependencies {
implementation(projects.core.domain)
}
}
}
// feature/auth/data/build.gradle.kts
kotlin {
sourceSets {
commonMain.dependencies {
implementation(projects.core.domain)
implementation(projects.core.data)
implementation(projects.feature.auth.domain)
}
}
}
// feature/auth/presentation/build.gradle.kts
kotlin {
sourceSets {
commonMain.dependencies {
implementation(projects.core.domain)
implementation(projects.core.presentation)
implementation(projects.core.designsystem)
implementation(projects.feature.auth.domain)
}
}
}
核心依赖规则:domain 模块不依赖任何其他模块(除了 core:domain);data 模块依赖 domain 和 core:data;presentation 模块依赖 domain、core:presentation 和 core:designsystem。data 模块不依赖 presentation,domain 模块不依赖 data。
4.4 模块化带来的收益
构建加速。Gradle增量编译和缓存可以更高效地工作,修改 feature:auth:presentation 不会触发 feature:home:data 的重新编译。
团队并行开发。不同开发者可以同时修改不同模块,减少合并冲突。
架构约束的强制执行。Gradle模块依赖关系本身就是一种架构约束——如果 domain 模块试图依赖 data 模块,构建会失败。
MVI与Clean Architecture的结合已在多个生产级示例项目中得到验证,包括使用Compose Multiplatform、Koin和Ktor的完整MVI架构示例。
下面是多模块架构的依赖关系示意图:
五、UseCase的组织与测试友好性
5.1 UseCase的职责边界
UseCase封装一个具体的业务操作,是Domain层与Presentation层之间的桥梁。一个UseCase通常只做一件事:
// 简单UseCase:直接委托Repository
class GetUserUseCase(private val userRepository: UserRepository) {
suspend operator fun invoke(userId: Long): Result<User> =
userRepository.getUser(userId)
}
// 复杂UseCase:组合多个Repository或执行额外逻辑
class SubmitOrderUseCase(
private val orderRepository: OrderRepository,
private val cartRepository: CartRepository,
) {
suspend operator fun invoke(): Result<Order> {
val cart = cartRepository.getCart()
if (cart.items.isEmpty()) return Result.failure(EmptyCartException())
return orderRepository.submitOrder(cart.toOrder())
}
}
5.2 UseCase的测试策略
UseCase的测试在 commonTest 中进行,使用手写的Fake实现替代Mock框架。这不仅是Kotlin社区的推荐做法,也是KMP项目的实际需要——Fake不依赖反射,在KMP所有目标上均可运行。
// commonTest
class SubmitOrderUseCaseTest {
private val fakeCartRepository = FakeCartRepository()
private val fakeOrderRepository = FakeOrderRepository()
private val useCase = SubmitOrderUseCase(fakeOrderRepository, fakeCartRepository)
@Test
fun `returns failure when cart is empty`() = runTest {
fakeCartRepository.setCart(Cart(items = emptyList()))
val result = useCase()
assertTrue(result.isFailure)
assertTrue(result.exceptionOrNull() is EmptyCartException)
}
}
测试要点:UseCase测试是业务逻辑的“最低测试覆盖单元”——每个UseCase至少应有一个测试用例,覆盖正常路径和边界情况。
六、生产级架构实践
6.1 Koin在多模块架构中的组织
在多模块架构中,每个模块可以定义自己的Koin模块,然后在 composeApp 的 initKoin() 中统一注册。Koin的 @ComponentScan 会自动发现各模块中被注解标记的组件。
// feature/auth/data 中的模块定义
@Module
@ComponentScan("com.example.app.feature.auth.data")
class AuthDataModule
// composeApp 中统一初始化
fun initKoin(config: KoinAppDeclaration? = null) {
startKoin {
includes(config)
modules(
AuthDataModule().module,
HomeDataModule().module,
// ...
)
}
}
6.2 跨模块通信
在多模块架构中,模块之间不应直接依赖。跨模块通信通过两种方式实现:
共享Domain接口。模块A暴露Domain层的接口,模块B通过依赖注入获取实现。
导航参数传递。通过Navigation 3的返回栈传递数据,而非直接调用其他模块的ViewModel。
6.3 架构决策矩阵
| 项目规模 | 推荐架构 | 模块化策略 |
|---|---|---|
| 小型(<10屏) | MVVM + Clean分层 | 单模块,按包分层 |
| 中型(10-30屏) | MVI + Clean分层 | 多模块,feature-based |
| 大型(>30屏,多团队) | MVI + Clean分层 + DI作用域 | 多模块 + Convention Plugins |
单模块CMP项目的分层布局(适合中小型项目):
composeApp/src/commonMain/kotlin/com/myapp/
├── data/ → API clients, repositories
├── domain/ → Models, repository interfaces, UseCases
├── presentation/ → ViewModels, Compose screens
└── di/ → Koin modules
下面是架构决策流程图:
配套习题(15题)
第一组:Clean Architecture分层(4题)
第1题 Clean Architecture中,Domain层的正确特征是( )
A. 依赖Ktor和Room等框架 B. 纯Kotlin,不依赖任何平台API或框架 C. 包含Compose UI代码 D. 直接依赖Android SDK
答案:B
解析:Domain层是架构的核心,包含实体模型、Repository接口和UseCase,是纯Kotlin代码,不依赖任何框架或平台API。这确保了Domain层的逻辑可以在所有平台上运行,且可以独立于UI框架进行单元测试。
第2题 在Clean Architecture中,依赖方向是( )
A. 从内层指向外层 B. 从外层指向内层 C. 双向依赖 D. 没有依赖规则
答案:B
解析:依赖方向始终从外层指向内层。Presentation层可以调用Domain层的UseCase,Data层实现Domain层的Repository接口,但Domain层不能依赖任何外层。
第3题 Data层中Repository实现的核心职责是( )
A. 渲染UI B. 处理用户交互事件 C. 决定数据来源(Remote/Local/Cache)并映射为Domain模型 D. 管理导航状态
答案:C
解析:Data层实现Domain层定义的Repository接口,负责数据来源决策(Remote/Local/Cache),将DTO映射为Domain模型,并处理数据同步逻辑。
第4题 在CMP的commonMain中,获取ViewModel的正确方式是( )
A. viewModel<UserViewModel>()
B. viewModel { UserViewModel(getUserUseCase) }
C. remember { UserViewModel() }
D. UserViewModel()
答案:B
解析:在commonMain中,viewModel() 必须提供初始化器,因为非JVM平台不支持类型反射来自动实例化ViewModel。无参调用 viewModel<UserViewModel>() 在非JVM平台会失败。
第二组:MVI模式(4题)
第5题 MVI模式中,State和Effect的关键区别是( )
A. State是一次性事件,Effect参与UI渲染 B. State参与UI渲染且可被重组,Effect是一次性事件,不应在配置更改后重放 C. 两者完全相同 D. State只能用于Android,Effect用于iOS
答案:B
解析:State参与UI渲染且可被重组;Effect是一次性事件(导航、Snackbar),不应在配置更改后重放。Effect应通过Channel暴露而非SharedFlow,因为SharedFlow的replay缓存在iOS上会导致导航事件意外重放。
第6题 MVI模式中,Intent的推荐定义方式是( )
A. 使用字符串常量 B. 使用密封接口(sealed interface)保证穷尽性 C. 使用枚举 D. 使用Int常量
答案:B
解析:使用密封接口定义Intent,when 表达式强制穷尽所有事件类型,添加新事件时编译器会提示处理。这提供了编译期的类型安全和事件完整性保证。
第7题 MVI中State应该设计为( )
A. 可变类,直接修改属性 B. 不可变data class,通过copy()产生新实例 C. 包含Flow属性的复杂对象 D. 使用全局变量
答案:B
解析:State应为不可变data class,所有属性为val,通过copy()产生新实例。这保证了状态更新的原子性和可预测性。State不应包含Flow类型的属性。
第8题 MVI相比MVVM的核心优势不包括( )
A. 单向数据流,数据流始终单向 B. 可预测的状态管理,状态只能通过copy()更新 C. 自动生成所有UI代码 D. 高度可测试,ViewModel不依赖UI框架
答案:C
解析:MVI不会自动生成UI代码。其核心优势包括单向数据流、可预测的状态管理和高度可测试性。
第三组:多模块架构(4题)
第9题 AGP 9.0对CMP项目结构的要求是( )
A. 可以继续使用单一composeApp模块 B. 必须将Android应用入口从KMP共享模块中分离 C. 只能使用一个模块 D. 不需要任何模块化
答案:B
解析:AGP 9.0不再支持在同一个模块中同时应用com.android.application和org.jetbrains.kotlin.multiplatform插件。必须将单体模块拆分为独立的平台应用模块和KMP共享库模块。
第10题 多模块架构中,feature/auth/domain模块的依赖规则是( )
A. 可以依赖feature/auth/data B. 可以依赖core:domain,但不能依赖data层 C. 可以依赖所有模块 D. 不依赖任何模块
答案:B
解析:domain模块是纯Kotlin的,不依赖任何其他模块(除了core:domain)。data模块依赖domain和core:data,presentation模块依赖domain、core:presentation和core:designsystem。domain不依赖data,data不依赖presentation。
第11题 模块化架构带来的收益不包括( )
A. 构建加速,增量编译更高效 B. 团队并行开发,减少合并冲突 C. 完全消除所有bug D. Gradle模块依赖关系本身就是架构约束
答案:C
解析:模块化架构可以加速构建、支持团队并行开发、通过Gradle依赖关系强制执行架构约束,但不会完全消除bug。
第12题 在KMP 2026默认项目结构中,共享代码的组织方式是( )
A. 所有代码放在composeApp单一模块中 B. 专门的shared KMP共享库模块 + 各平台独立应用模块 C. 每个平台一个独立的共享模块 D. 不需要共享模块
答案:B
解析:2026年KMP默认项目结构是一个专门的shared KMP共享库模块 + 各平台独立应用模块(androidApp、iosApp、desktopApp),而非旧版的单一composeApp模块。
第四组:UseCase与生产实践(3题)
第13题 UseCase的职责是( )
A. 渲染UI界面 B. 封装一个具体的业务操作,是Domain层与Presentation层之间的桥梁 C. 管理数据库连接 D. 处理网络请求
答案:B
解析:UseCase封装一个具体的业务操作,是Domain层与Presentation层之间的桥梁。简单UseCase直接委托Repository,复杂UseCase组合多个Repository或执行额外业务逻辑。
第14题 UseCase测试中推荐使用的测试替身类型是( )
A. Mock框架 B. 手写的Fake实现 C. 真实网络请求 D. 反射调用
答案:B
解析:UseCase测试应使用手写的Fake实现替代Mock框架。Fake不依赖反射,在KMP所有目标上均可运行,行为更接近真实实现,测试更可靠。
第15题 多模块架构中跨模块通信的推荐方式是( )
A. 模块之间直接依赖对方的ViewModel B. 共享Domain接口或通过Navigation 3返回栈传递数据 C. 使用全局变量 D. 通过反射调用
答案:B
解析:在多模块架构中,模块之间不应直接依赖。跨模块通信通过共享Domain接口(模块A暴露Domain层接口,模块B通过DI获取实现)或通过Navigation 3的返回栈传递数据实现。
本课知识点总结
1. 架构成熟度与Clean Architecture分层
Kotlin架构成熟度从Level 1(单体,UI中直接执行DB/网络查询)到Level 5(Clean KMP布局,完全响应式,测试覆盖率>70%)。CMP项目应采用Clean Architecture三层分离:Domain层(纯Kotlin,Repository接口,UseCase,无平台导入)、Data层(Repository实现,数据源决策,DTO→Domain映射)、Presentation层(ViewModel,Compose UI,状态管理)。依赖方向从外层指向内层。企业级迁移案例表明,迁移后结构性可维护性和开发者体验有明显改善,但编译时间增加近四倍。
2. MVI模式在CMP中的落地
MVI是MVVM的增强形态。三要素:State(不可变data class,通过copy()更新)、Intent(密封接口,穷尽性检查)、Effect(一次性副作用,通过Channel暴露而非SharedFlow,避免iOS上导航事件重放)。在commonMain中,viewModel() 必须提供初始化器(非JVM平台不支持类型反射)。
3. 多模块架构策略
AGP 9.0要求平台应用入口与KMP共享模块分离。2026年KMP默认结构:shared KMP共享库 + androidApp/iosApp/desktopApp 独立入口模块。Feature模块按 domain/data/presentation 拆分,依赖规则:domain不依赖data,data不依赖presentation。模块化收益:构建加速、团队并行开发、Gradle依赖关系强制架构约束。
4. UseCase的组织与测试
UseCase是Domain层与Presentation层之间的桥梁,封装单一业务操作。简单UseCase委托Repository,复杂UseCase组合多个Repository。测试在commonTest中进行,使用手写Fake实现替代Mock框架。每个UseCase至少应有一个测试用例。
5. 生产级架构实践与决策矩阵
Koin在多模块架构中通过@ComponentScan自动发现各模块组件。跨模块通信通过共享Domain接口或Navigation 3返回栈实现。架构决策:小型项目(<10屏)单模块按包分层,中型项目(10-30屏)多模块feature-based,大型项目(>30屏)多模块+Convention Plugins。
下一课预告:第17课将深入性能优化与基准测试,包括Compose三阶段渲染管线的优化切入点、重组优化策略(@Stable/@Immutable、key()、derivedStateOf)、Lazy布局的性能陷阱、iOS端Metal着色器编译停顿的预编译策略、基准测试工具链,以及JetBrains的find_degradation脚本与LazyGridImageView基准对比。