Android Clean Architecture

affaan-m/ECC/docs/zh-CN/skills/android-clean-architecture

作者 affaan-mef648e01899ba3e8dc6371642deaaf64b4477775无许可证275K 个星标收录于 2026年10月9日更新于 2026年10月9日仓库4天前更新

适用于Android和Kotlin多平台项目的Clean Architecture模式——模块结构、依赖规则、用例、仓库以及数据层模式。

仅含说明Software Development

AI 生成的概览

面向 Android 与 Kotlin 多平台项目的整洁架构模式指南，涵盖模块结构、分层与数据访问。

功能: 该技能为采用整洁架构的 Android 与 Kotlin 多平台项目提供结构参考。它说明推荐的模块布局、各层之间的依赖规则、UseCase 与 Repository 模式、映射器，以及使用 Room、SQLDelight 和 Ktor 的数据层设计。内容还涉及使用 Koin 与 Hilt 的依赖注入、错误处理模式、Gradle 约定插件以及应避免的反模式。
适用场景: 适用于搭建或重构 Android 或 KMP 项目的模块结构，或实现 UseCase、Repository 与 DataSource 时。也适用于设计领域层、数据层与表示层之间的数据流，或配置依赖注入。
运行要求: 除智能体外无需脚本或工具，属于纯说明性参考。应用这些模式的前提是一个 Kotlin 项目，可能使用 Room、SQLDelight、Ktor、Koin、Hilt 或 Gradle 约定插件。

Android 整洁架构

适用于 Android 和 KMP 项目的整洁架构模式。涵盖模块边界、依赖反转、UseCase/Repository 模式，以及使用 Room、SQLDelight 和 Ktor 的数据层设计。

何时启用

构建 Android 或 KMP 项目模块结构
实现 UseCases、Repositories 或 DataSources
设计各层（领域层、数据层、表示层）之间的数据流
使用 Koin 或 Hilt 设置依赖注入
在分层架构中使用 Room、SQLDelight 或 Ktor

模块结构

依赖规则

app → presentation, domain, data, corepresentation → domain, design-system, coredata → domain, coredomain → core (或无依赖)core → (无依赖)

app → presentation, domain, data, corepresentation → domain, design-system, coredata → domain, coredomain → core (或无依赖)core → (无依赖)

关键：domain 绝不能依赖 data、presentation 或任何框架。它仅包含纯 Kotlin 代码。

领域层

UseCase 模式

每个 UseCase 代表一个业务操作。使用 operator fun invoke 以获得简洁的调用点：

kotlin

class GetItemsByCategoryUseCase(    private val repository: ItemRepository) {    suspend operator fun invoke(category: String): Result<List<Item>> {        return repository.getItemsByCategory(category)    }}
// Flow-based UseCase for reactive streamsclass ObserveUserProgressUseCase(    private val repository: UserRepository) {    operator fun invoke(userId: String): Flow<UserProgress> {        return repository.observeProgress(userId)    }}

class GetItemsByCategoryUseCase(    private val repository: ItemRepository) {    suspend operator fun invoke(category: String): Result<List<Item>> {        return repository.getItemsByCategory(category)    }}
// Flow-based UseCase for reactive streamsclass ObserveUserProgressUseCase(    private val repository: UserRepository) {    operator fun invoke(userId: String): Flow<UserProgress> {        return repository.observeProgress(userId)    }}

领域模型

领域模型是普通的 Kotlin 数据类——没有框架注解：

kotlin

data class Item(    val id: String,    val title: String,    val description: String,    val tags: List<String>,    val status: Status,    val category: String)
enum class Status { DRAFT, ACTIVE, ARCHIVED }

data class Item(    val id: String,    val title: String,    val description: String,    val tags: List<String>,    val status: Status,    val category: String)
enum class Status { DRAFT, ACTIVE, ARCHIVED }

仓库接口

在领域层定义，在数据层实现：

kotlin

interface ItemRepository {    suspend fun getItemsByCategory(category: String): Result<List<Item>>    suspend fun saveItem(item: Item): Result<Unit>    fun observeItems(): Flow<List<Item>>}

interface ItemRepository {    suspend fun getItemsByCategory(category: String): Result<List<Item>>    suspend fun saveItem(item: Item): Result<Unit>    fun observeItems(): Flow<List<Item>>}

数据层

仓库实现

协调本地和远程数据源：

kotlin

class ItemRepositoryImpl(    private val localDataSource: ItemLocalDataSource,    private val remoteDataSource: ItemRemoteDataSource) : ItemRepository {
    override suspend fun getItemsByCategory(category: String): Result<List<Item>> {        return runCatching {            val remote = remoteDataSource.fetchItems(category)            localDataSource.insertItems(remote.map { it.toEntity() })            localDataSource.getItemsByCategory(category).map { it.toDomain() }        }    }
    override suspend fun saveItem(item: Item): Result<Unit> {        return runCatching {            localDataSource.insertItems(listOf(item.toEntity()))        }    }
    override fun observeItems(): Flow<List<Item>> {        return localDataSource.observeAll().map { entities ->            entities.map { it.toDomain() }        }    }}

class ItemRepositoryImpl(    private val localDataSource: ItemLocalDataSource,    private val remoteDataSource: ItemRemoteDataSource) : ItemRepository {
    override suspend fun getItemsByCategory(category: String): Result<List<Item>> {        return runCatching {            val remote = remoteDataSource.fetchItems(category)            localDataSource.insertItems(remote.map { it.toEntity() })            localDataSource.getItemsByCategory(category).map { it.toDomain() }        }    }
    override suspend fun saveItem(item: Item): Result<Unit> {        return runCatching {            localDataSource.insertItems(listOf(item.toEntity()))        }    }
    override fun observeItems(): Flow<List<Item>> {        return localDataSource.observeAll().map { entities ->            entities.map { it.toDomain() }        }    }}

映射器模式

将映射器作为扩展函数放在数据模型附近：

kotlin

// In data layerfun ItemEntity.toDomain() = Item(    id = id,    title = title,    description = description,    tags = tags.split("|"),    status = Status.valueOf(status),    category = category)
fun ItemDto.toEntity() = ItemEntity(    id = id,    title = title,    description = description,    tags = tags.joinToString("|"),    status = status,    category = category)

// In data layerfun ItemEntity.toDomain() = Item(    id = id,    title = title,    description = description,    tags = tags.split("|"),    status = Status.valueOf(status),    category = category)
fun ItemDto.toEntity() = ItemEntity(    id = id,    title = title,    description = description,    tags = tags.joinToString("|"),    status = status,    category = category)

Room 数据库 (Android)

kotlin

@Entity(tableName = "items")data class ItemEntity(    @PrimaryKey val id: String,    val title: String,    val description: String,    val tags: String,    val status: String,    val category: String)
@Daointerface ItemDao {    @Query("SELECT * FROM items WHERE category = :category")    suspend fun getByCategory(category: String): List<ItemEntity>
    @Upsert    suspend fun upsert(items: List<ItemEntity>)
    @Query("SELECT * FROM items")    fun observeAll(): Flow<List<ItemEntity>>}

@Entity(tableName = "items")data class ItemEntity(    @PrimaryKey val id: String,    val title: String,    val description: String,    val tags: String,    val status: String,    val category: String)
@Daointerface ItemDao {    @Query("SELECT * FROM items WHERE category = :category")    suspend fun getByCategory(category: String): List<ItemEntity>
    @Upsert    suspend fun upsert(items: List<ItemEntity>)
    @Query("SELECT * FROM items")    fun observeAll(): Flow<List<ItemEntity>>}

SQLDelight (KMP)

sql

-- Item.sqCREATE TABLE ItemEntity (    id TEXT NOT NULL PRIMARY KEY,    title TEXT NOT NULL,    description TEXT NOT NULL,    tags TEXT NOT NULL,    status TEXT NOT NULL,    category TEXT NOT NULL);
getByCategory:SELECT * FROM ItemEntity WHERE category = ?;
upsert:INSERT OR REPLACE INTO ItemEntity (id, title, description, tags, status, category)VALUES (?, ?, ?, ?, ?, ?);
observeAll:SELECT * FROM ItemEntity;

-- Item.sqCREATE TABLE ItemEntity (    id TEXT NOT NULL PRIMARY KEY,    title TEXT NOT NULL,    description TEXT NOT NULL,    tags TEXT NOT NULL,    status TEXT NOT NULL,    category TEXT NOT NULL);
getByCategory:SELECT * FROM ItemEntity WHERE category = ?;
upsert:INSERT OR REPLACE INTO ItemEntity (id, title, description, tags, status, category)VALUES (?, ?, ?, ?, ?, ?);
observeAll:SELECT * FROM ItemEntity;

Ktor 网络客户端 (KMP)

kotlin

class ItemRemoteDataSource(private val client: HttpClient) {
    suspend fun fetchItems(category: String): List<ItemDto> {        return client.get("api/items") {            parameter("category", category)        }.body()    }}
// HttpClient setup with content negotiationval httpClient = HttpClient {    install(ContentNegotiation) { json(Json { ignoreUnknownKeys = true }) }    install(Logging) { level = LogLevel.HEADERS }    defaultRequest { url("https://api.example.com/") }}

class ItemRemoteDataSource(private val client: HttpClient) {
    suspend fun fetchItems(category: String): List<ItemDto> {        return client.get("api/items") {            parameter("category", category)        }.body()    }}
// HttpClient setup with content negotiationval httpClient = HttpClient {    install(ContentNegotiation) { json(Json { ignoreUnknownKeys = true }) }    install(Logging) { level = LogLevel.HEADERS }    defaultRequest { url("https://api.example.com/") }}

依赖注入

Koin (适用于 KMP)

kotlin

// Domain moduleval domainModule = module {    factory { GetItemsByCategoryUseCase(get()) }    factory { ObserveUserProgressUseCase(get()) }}
// Data moduleval dataModule = module {    single<ItemRepository> { ItemRepositoryImpl(get(), get()) }    single { ItemLocalDataSource(get()) }    single { ItemRemoteDataSource(get()) }}
// Presentation moduleval presentationModule = module {    viewModelOf(::ItemListViewModel)    viewModelOf(::DashboardViewModel)}

// Domain moduleval domainModule = module {    factory { GetItemsByCategoryUseCase(get()) }    factory { ObserveUserProgressUseCase(get()) }}
// Data moduleval dataModule = module {    single<ItemRepository> { ItemRepositoryImpl(get(), get()) }    single { ItemLocalDataSource(get()) }    single { ItemRemoteDataSource(get()) }}
// Presentation moduleval presentationModule = module {    viewModelOf(::ItemListViewModel)    viewModelOf(::DashboardViewModel)}

Hilt (仅限 Android)

kotlin

@Module@InstallIn(SingletonComponent::class)abstract class RepositoryModule {    @Binds    abstract fun bindItemRepository(impl: ItemRepositoryImpl): ItemRepository}
@HiltViewModelclass ItemListViewModel @Inject constructor(    private val getItems: GetItemsByCategoryUseCase) : ViewModel()

@Module@InstallIn(SingletonComponent::class)abstract class RepositoryModule {    @Binds    abstract fun bindItemRepository(impl: ItemRepositoryImpl): ItemRepository}
@HiltViewModelclass ItemListViewModel @Inject constructor(    private val getItems: GetItemsByCategoryUseCase) : ViewModel()

错误处理

Result/Try 模式

使用 Result<T> 或自定义密封类型进行错误传播：

kotlin

sealed interface Try<out T> {    data class Success<T>(val value: T) : Try<T>    data class Failure(val error: AppError) : Try<Nothing>}
sealed interface AppError {    data class Network(val message: String) : AppError    data class Database(val message: String) : AppError    data object Unauthorized : AppError}
// In ViewModel — map to UI stateviewModelScope.launch {    when (val result = getItems(category)) {        is Try.Success -> _state.update { it.copy(items = result.value, isLoading = false) }        is Try.Failure -> _state.update { it.copy(error = result.error.toMessage(), isLoading = false) }    }}

sealed interface Try<out T> {    data class Success<T>(val value: T) : Try<T>    data class Failure(val error: AppError) : Try<Nothing>}
sealed interface AppError {    data class Network(val message: String) : AppError    data class Database(val message: String) : AppError    data object Unauthorized : AppError}
// In ViewModel — map to UI stateviewModelScope.launch {    when (val result = getItems(category)) {        is Try.Success -> _state.update { it.copy(items = result.value, isLoading = false) }        is Try.Failure -> _state.update { it.copy(error = result.error.toMessage(), isLoading = false) }    }}

约定插件 (Gradle)

对于 KMP 项目，使用约定插件以减少构建文件重复：

kotlin

// build-logic/src/main/kotlin/kmp-library.gradle.ktsplugins {    id("org.jetbrains.kotlin.multiplatform")}
kotlin {    androidTarget()    iosX64(); iosArm64(); iosSimulatorArm64()    sourceSets {        commonMain.dependencies { /* shared deps */ }        commonTest.dependencies { implementation(kotlin("test")) }    }}

// build-logic/src/main/kotlin/kmp-library.gradle.ktsplugins {    id("org.jetbrains.kotlin.multiplatform")}
kotlin {    androidTarget()    iosX64(); iosArm64(); iosSimulatorArm64()    sourceSets {        commonMain.dependencies { /* shared deps */ }        commonTest.dependencies { implementation(kotlin("test")) }    }}

在模块中应用：

应避免的反模式

在 domain 中导入 Android 框架类——保持其为纯 Kotlin
向 UI 层暴露数据库实体或 DTO——始终映射到领域模型
将业务逻辑放在 ViewModels 中——提取到 UseCases
使用 GlobalScope 或非结构化协程——使用 viewModelScope 或结构化并发
臃肿的仓库实现——拆分为专注的 DataSources
循环模块依赖——如果 A 依赖 B，则 B 绝不能依赖 A

参考

查看技能：compose-multiplatform-patterns 了解 UI 模式。查看技能：kotlin-coroutines-flows 了解异步模式。

来源与署名

来源：affaan-m/ECC位于docs/zh-CN/skills/android-clean-architecture提交ef648e0

许可证：无许可证

内容归原作者所有。SourceWeft 从公开仓库中收录这些内容。

举报或申请下架

Android Clean Architecture

Android 整洁架构

何时启用

模块结构

推荐布局

依赖规则

领域层

UseCase 模式

领域模型

仓库接口

数据层

仓库实现

映射器模式

Room 数据库 (Android)

SQLDelight (KMP)

Ktor 网络客户端 (KMP)

依赖注入

Koin (适用于 KMP)

Hilt (仅限 Android)

错误处理

Result/Try 模式

约定插件 (Gradle)

应避免的反模式

参考

来源与署名

更多来自 affaan-m/ECC 的技能

Unified Notifications Ops

Verification Loop

Ui To Vue

Unified Memory

Visa Doc Translate

Team Builder

更多Software Development技能

Playground

M5 Onboard

Cardputer Buddy

Web Design Guidelines

Vercel React Native Skills

Vercel React Best Practices