【Compose Multiplatform跨端声明式UI实用技术】第16课:CMP应用架构设计——从MVVM到Clean Architecture

38 阅读18分钟

前十五课覆盖了环境搭建、UI基础、状态管理、导航、依赖注入、平台抽象、网络层、平台互操作和资源管理。从本课开始进入架构与工程化模块。本课将深入CMP应用架构设计的核心:Clean Architecture的层次职责与依赖规则、MVI模式在共享代码中的落地方式、多模块拆分策略与依赖约束、UseCase的组织与测试友好性,以及生产级架构的完整实践。本课内容基于CMP 1.12.1、Kotlin 2.3.20与Lifecycle 2.10.0。 文末附有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 三层结构的依赖关系示意图:

mermaid diagram

三、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 模式的单向数据流示意图:

mermaid diagram

四、多模块架构策略

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架构示例。

下面是多模块架构的依赖关系示意图:

mermaid diagram

五、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

下面是架构决策流程图:

mermaid diagram

配套习题(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基准对比。