Android Clean Architecture
Android 및 KMP 프로젝트를 위한 클린 아키텍처 패턴입니다. 모듈 경계, 의존성 역전, UseCase/Repository 패턴, Room, SQLDelight, Ktor를 활용한 데이터 계층 설계를 다룹니다.
활성화 시기
- Android 또는 KMP 프로젝트 모듈을 구조화할 때
- UseCase, Repository 또는 DataSource를 구현할 때
- 계층(domain, data, presentation) 간 데이터 흐름을 설계할 때
- Koin 또는 Hilt로 의존성 주입을 설정할 때
- 계층형 아키텍처에서 Room, SQLDelight 또는 Ktor를 사용할 때
모듈 구조
권장 레이아웃
project/
├── app/ # Android 진입점, DI 연결, Application 클래스
├── core/ # 공유 유틸리티, 기본 클래스, 오류 타입
├── domain/ # UseCase, 도메인 모델, 저장소 인터페이스 (순수 Kotlin)
├── data/ # Repository 구현, DataSource, DB, 네트워크
├── presentation/ # 화면, ViewModel, UI 모델, 네비게이션
├── design-system/ # 재사용 가능한 Compose 컴포넌트, 테마, 타이포그래피
└── feature/ # 기능 모듈 (선택 사항, 대규모 프로젝트용)
├── auth/
├── settings/
└── profile/
의존성 규칙
app → presentation, domain, data, core
presentation → domain, design-system, core
data → domain, core
domain → core (또는 의존성 없음)
core → (의존성 없음)
중요: domain은 절대 data, presentation 또는 어떤 프레임워크에도 의존해서는 안 됩니다. 순수 Kotlin만 포함합니다.
도메인 계층
UseCase 패턴
각 UseCase는 하나의 비즈니스 작업을 나타냅니다. 깔끔한 호출을 위해 operator fun invoke를 사용하세요:
class GetItemsByCategoryUseCase(
private val repository: ItemRepository
) {
suspend operator fun invoke(category: String): Result<List<Item>> {
return repository.getItemsByCategory(category)
}
}
// 반응형 스트림을 위한 Flow 기반 UseCase
class ObserveUserProgressUseCase(
private val repository: UserRepository
) {
operator fun invoke(userId: String): Flow<UserProgress> {
return repository.observeProgress(userId)
}
}
도메인 모델
도메인 모델은 일반 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 }
저장소 인터페이스
도메인에 정의되고 데이터에서 구현됩니다:
interface ItemRepository {
suspend fun getItemsByCategory(category: String): Result<List<Item>>
suspend fun saveItem(item: Item): Result<Unit>
fun observeItems(): Flow<List<Item>>
}
데이터 계층
Repository 구현
로컬 및 원격 데이터 소스를 조정합니다:
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() }
}
}
}
Mapper 패턴
데이터 모델 근처에 확장 함수로 Mapper를 유지하세요:
// 데이터 계층
fun 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)
@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
)
@Dao
interface 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)
-- Item.sq
CREATE 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)
class ItemRemoteDataSource(private val client: HttpClient) {
suspend fun fetchItems(category: String): List<ItemDto> {
return client.get("api/items") {
parameter("category", category)
}.body()
}
}
// 콘텐츠 협상을 사용한 HttpClient 설정
val httpClient = HttpClient {
install(ContentNegotiation) { json(Json { ignoreUnknownKeys = true }) }
install(Logging) { level = LogLevel.HEADERS }
defaultRequest { url("https://api.example.com/") }
}
의존성 주입
Koin (KMP 호환)
// 도메인 모듈
val domainModule = module {
factory { GetItemsByCategoryUseCase(get()) }
factory { ObserveUserProgressUseCase(get()) }
}
// 데이터 모듈
val dataModule = module {
single<ItemRepository> { ItemRepositoryImpl(get(), get()) }
single { ItemLocalDataSource(get()) }
single { ItemRemoteDataSource(get()) }
}
// 프레젠테이션 모듈
val presentationModule = module {
viewModelOf(::ItemListViewModel)
viewModelOf(::DashboardViewModel)
}
Hilt (Android 전용)
@Module
@InstallIn(SingletonComponent::class)
abstract class RepositoryModule {
@Binds
abstract fun bindItemRepository(impl: ItemRepositoryImpl): ItemRepository
}
@HiltViewModel
class ItemListViewModel @Inject constructor(
private val getItems: GetItemsByCategoryUseCase
) : ViewModel()
오류 처리
Result/Try 패턴
오류 전파에 Result<T> 또는 사용자 정의 sealed 타입을 사용하세요:
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
}
// ViewModel에서 — UI 상태로 매핑
viewModelScope.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 프로젝트의 경우 컨벤션 플러그인을 사용하여 빌드 파일 중복을 줄이세요:
// build-logic/src/main/kotlin/kmp-library.gradle.kts
plugins {
id("org.jetbrains.kotlin.multiplatform")
}
kotlin {
androidTarget()
iosX64(); iosArm64(); iosSimulatorArm64()
sourceSets {
commonMain.dependencies { /* 공유 의존성 */ }
commonTest.dependencies { implementation(kotlin("test")) }
}
}
모듈에 적용:
// domain/build.gradle.kts
plugins { id("kmp-library") }
피해야 할 안티 패턴
domain에서 Android 프레임워크 클래스를 임포트하는 것 — 순수 Kotlin 유지- 데이터베이스 엔티티나 DTO를 UI 계층에 노출 — 항상 도메인 모델로 매핑
- ViewModel에 비즈니스 로직을 넣는 것 — UseCase로 추출
GlobalScope또는 비구조화된 코루틴 사용 —viewModelScope또는 구조화된 동시성 사용- Repository 구현이 너무 비대해지는 것 — 집중된 DataSource로 분할
- 순환 모듈 의존성 — A가 B에 의존하면 B는 A에 의존해서는 안 됨
참고
UI 패턴은 skill: compose-multiplatform-patterns를 참조하세요.
비동기 패턴은 skill: kotlin-coroutines-flows를 참조하세요.