Android clean architecture
Skill SAM42-Lab/everything-claude-code-kr/skills/android-clean-architecture
안드로이드 및 Kotlin Multiplatform 프로젝트를 위한 Clean Architecture 패턴 - 모듈 구조, 의존성 규칙, UseCase, Repository 및 데이터 레이어 패턴.From its SKILL.md
npx -y skills add SAM42-Lab/everything-claude-code-kr --skill android-clean-architectureAssembled from the repository path, not quoted from the project. Check it against their README if it does not work.
One thing to look at
- 1 stars1 stars. Stars are a popularity signal and not a quality one, but at this level it is likely that nobody has read this closely except its author, and you would be relying on your own review.
SKILL.md
9.3 KB, as published. Nobody here has run it
안드로이드 클린 아키텍처 (Android Clean Architecture)
안드로이드 및 KMP 프로젝트를 위한 클린 아키텍처 패턴입니다. 모듈 경계, 의존성 역전, UseCase/Repository 패턴, 그리고 Room, SQLDelight, Ktor를 이용한 데이터 레이어 설계를 다룹니다.
활성화 시점
- 안드로이드 또는 KMP 프로젝트 모듈 구조를 설계할 때
- UseCase, Repository 또는 DataSource를 구현할 때
- 레이어(domain, data, presentation) 간의 데이터 흐름을 설계할 때
- Koin 또는 Hilt를 이용한 의존성 주입을 설정할 때
- 계층화된 아키텍처에서 Room, SQLDelight 또는 Ktor로 작업할 때
모듈 구조
권장 레이아웃
project/
├── app/ # 안드로이드 진입점, DI 구성, Application 클래스
├── core/ # 공유 유틸리티, 베이스 클래스, 에러 타입
├── domain/ # UseCase, 도메인 모델, 레포지토리 인터페이스 (Pure Kotlin)
├── data/ # 레포지토리 구현체, 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만 포함해야 합니다.
도메인 레이어 (Domain Layer)
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>>
}
데이터 레이어 (Data Layer)
레포지토리 구현체
로컬 및 원격 데이터 소스 간의 조정을 담당합니다.
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) 패턴
매퍼는 데이터 모델 근처에 확장 함수로 유지하세요.
// 데이터 레이어에서
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 데이터베이스 (안드로이드)
@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/") }
}
의존성 주입 (Dependency Injection)
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 (안드로이드 전용)
@Module
@InstallIn(SingletonComponent::class)
abstract class RepositoryModule {
@Binds
abstract fun bindItemRepository(impl: ItemRepositoryImpl): ItemRepository
}
@HiltViewModel
class ItemListViewModel @Inject constructor(
private val getItems: GetItemsByCategoryUseCase
) : ViewModel()
에러 처리 (Error Handling)
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 { /* shared deps */ }
commonTest.dependencies { implementation(kotlin("test")) }
}
}
모듈에 적용:
// domain/build.gradle.kts
plugins { id("kmp-library") }
피해야 할 안티 패턴
domain에 안드로이드 프레임워크 클래스 임포트 - 순수 Kotlin 유지- UI 레이어에 데이터베이스 엔티티나 DTO 노출 - 항상 도메인 모델로 매핑
- ViewModel에 비즈니스 로직 작성 - UseCase로 추출
GlobalScope또는 구조화되지 않은 코루틴 사용 -viewModelScope또는 구조화된 동시성 사용- 거대한 레포지토리 구현체 - 집중된 DataSource로 분할
- 순환 모듈 의존성 - A가 B에 의존하면 B는 A에 의존해서는 안 됨
참조
UI 패턴은 compose-multiplatform-patterns 스킬을 참조하세요.
비동기 패턴은 kotlin-coroutines-flows 스킬을 참조하세요.