Compose Multiplatform & Annotations
이 튜토리얼에서는 메트로폴리탄 미술관(The Metropolitan Museum of Art)의 예술품 목록을 표시하고 세부 정보를 보여주는 Android 및 iOS용 Compose Multiplatform 앱을 빌드합니다. 두 개의 Gradle 모듈에 걸쳐 클래스에 어노테이션을 지정하고, 플랫폼별 정의를 제공하며, 컴포저블(composable)에 ViewModel을 주입하고, 루트 컴포저블에서 Koin을 시작하는 방법을 배웁니다. 약 20분이 소요되며 Android Studio와 iOS용 Xcode가 필요합니다.
이 튜토리얼은 어노테이션을 사용합니다. Compiler Plugin DSL을 사용한 동일한 앱을 보려면 Compose Multiplatform을 참조하세요. 스타일을 비교하려면 스타일 선택하기를 참조하세요.
코드 가져오기
전체 샘플 코드는 koin-getting-started/compose-annotations에 있습니다. 저장소를 클론하고 Android Studio에서 compose-annotations 폴더를 엽니다. 이 프로젝트에는 데이터 레이어를 위한 data 모듈과 UI를 위한 composeApp 모듈 등 두 개의 Gradle 모듈이 있습니다. iOS 앱은 iosApp에 있습니다.
Gradle 설정
두 Gradle 모듈 모두 Koin 컴파일러 플러그인(Compiler Plugin)을 적용합니다. 버전은 버전 카탈로그(version catalog)에서 관리됩니다.
# gradle/libs.versions.toml
[versions]
# Kotlin, Compose Multiplatform, Ktor, navigation and Coil entries omitted
koin = "<KOIN_VERSION>"
koin-plugin = "<KOIN_PLUGIN_VERSION>"
[libraries]
koin-core = { module = "io.insert-koin:koin-core", version.ref = "koin" }
koin-annotations = { module = "io.insert-koin:koin-annotations", version.ref = "koin" }
koin-compose-viewmodel = { module = "io.insert-koin:koin-compose-viewmodel", version.ref = "koin" }
[plugins]
koin-compiler = { id = "io.insert-koin.compiler.plugin", version.ref = "koin-plugin" }// data/build.gradle.kts
plugins {
alias(libs.plugins.kotlin.multiplatform)
alias(libs.plugins.android.library)
alias(libs.plugins.koin.compiler)
alias(libs.plugins.kotlin.serialization)
}
kotlin {
sourceSets {
commonMain.dependencies {
implementation(libs.koin.core)
api(libs.koin.annotations)
...
}
}
}// composeApp/build.gradle.kts
plugins {
alias(libs.plugins.kotlin.multiplatform)
alias(libs.plugins.android.application)
alias(libs.plugins.compose.multiplatform)
alias(libs.plugins.koin.compiler)
alias(libs.plugins.kotlin.compose)
alias(libs.plugins.kotlin.serialization)
}
kotlin {
sourceSets {
commonMain.dependencies {
api(project(":data"))
implementation(libs.koin.core)
implementation(libs.koin.compose.viewmodel)
implementation(libs.koin.annotations)
...
}
}
}컴파일러 플러그인은 타깃별 개별 설정 없이 모든 타깃에서 어노테이션을 처리합니다. Kotlin 2.3.20 이상이 필요하며, koin-annotations는 Koin 버전과 동일한 버전을 공유합니다. 자세한 내용은 Gradle 설정 및 Compiler Plugin 설정을 참조하세요.
애플리케이션 구조
이 앱은 원격 API에서 예술품 목록을 가져와 메모리에 캐시한 다음, 목록 화면과 상세 화면에 표시합니다.
MuseumApi -> MuseumStorage -> MuseumRepository -> ListViewModel / DetailViewModel -> Compose UIHTTP 통신에는 Ktor를, 데이터 스트림에는 Kotlin Flow를, 라우팅에는 Navigation Compose를 사용합니다. 제목이나 주석에 별도의 언급이 없는 한 코드는 commonMain에 작성됩니다.
데이터 레이어 작성하기
이 코드는 data Gradle 모듈에 작성합니다. MuseumObject 데이터 클래스는 API 응답을 매핑합니다.
@Serializable
data class MuseumObject(
val objectID: Int,
val title: String,
val artistDisplayName: String,
val medium: String,
val dimensions: String,
val objectURL: String,
val objectDate: String,
val primaryImage: String,
val primaryImageSmall: String,
val repository: String,
val department: String,
val creditLine: String,
)KtorMuseumApi는 Ktor의 HttpClient를 사용하여 목록을 가져옵니다. 여기에 @Singleton 어노테이션을 추가합니다.
import org.koin.core.annotation.Singleton
interface MuseumApi {
suspend fun getData(): List<MuseumObject>
}
@Singleton
class KtorMuseumApi(private val client: HttpClient) : MuseumApi {
companion object {
private const val API_URL =
"https://raw.githubusercontent.com/Kotlin/KMP-App-Template/main/list.json"
}
override suspend fun getData(): List<MuseumObject> {
return try {
client.get(API_URL).body()
} catch (e: Exception) {
if (e is CancellationException) throw e
e.printStackTrace()
emptyList()
}
}
}InMemoryMuseumStorage는 객체들을 MutableStateFlow에 캐시합니다.
interface MuseumStorage {
suspend fun saveObjects(newObjects: List<MuseumObject>)
fun getObjectById(objectId: Int): Flow<MuseumObject?>
fun getObjects(): Flow<List<MuseumObject>>
}
@Singleton
class InMemoryMuseumStorage : MuseumStorage {
private val storedObjects = MutableStateFlow(emptyList<MuseumObject>())
override suspend fun saveObjects(newObjects: List<MuseumObject>) {
storedObjects.value = newObjects
}
override fun getObjectById(objectId: Int): Flow<MuseumObject?> {
return storedObjects.map { objects ->
objects.find { it.objectID == objectId }
}
}
override fun getObjects(): Flow<List<MuseumObject>> = storedObjects
}MuseumRepository는 생성될 때 API로부터 저장소를 새로고침합니다.
@Singleton
class MuseumRepository(
private val museumApi: MuseumApi,
private val museumStorage: MuseumStorage,
) {
private val scope = CoroutineScope(SupervisorJob())
init {
initialize()
}
fun initialize() {
scope.launch {
refresh()
}
}
suspend fun refresh() {
museumStorage.saveObjects(museumApi.getData())
}
fun getObjects(): Flow<List<MuseumObject>> = museumStorage.getObjects()
fun getObjectById(objectId: Int): Flow<MuseumObject?> = museumStorage.getObjectById(objectId)
}Koin은 각 클래스를 해당 상위 타입에 바인딩하므로, KtorMuseumApi는 MuseumApi에 대한 요청을 처리하게 됩니다. 자세한 내용은 정의(Definitions)를 참조하세요.
데이터 모듈 선언하기
HttpClient는 직접 소유하지 않은 외부 클래스이므로, 모듈 클래스 내의 함수를 통해 제공합니다.
import org.koin.core.annotation.ComponentScan
import org.koin.core.annotation.Configuration
import org.koin.core.annotation.Module
import org.koin.core.annotation.Singleton
@Module
@Configuration
@ComponentScan("com.jetbrains.kmpapp.data")
class DataModule {
@Singleton
fun providesHttpClient(): HttpClient {
val json = Json { ignoreUnknownKeys = true }
return HttpClient {
install(ContentNegotiation) {
json(json, contentType = ContentType.Any)
}
}
}
}@ComponentScan은 data 패키지에서 어노테이션이 달린 클래스들을 등록합니다. @Configuration은 DataModule이 다른 Gradle 모듈에 위치해 있더라도 앱의 진입점에서 검색할 수 있도록 해줍니다. 자세한 내용은 모듈(Modules)을 참조하세요.
ViewModel 작성하기
이 코드와 이후의 튜토리얼 내용은 composeApp Gradle 모듈에서 진행됩니다. 각 ViewModel에 @KoinViewModel 어노테이션을 추가합니다.
import org.koin.core.annotation.KoinViewModel
@KoinViewModel
class ListViewModel(museumRepository: MuseumRepository) : ViewModel() {
val objects: StateFlow<List<MuseumObject>> =
museumRepository.getObjects()
.stateIn(viewModelScope, SharingStarted.WhileSubscribed(5000), emptyList())
}
@KoinViewModel
class DetailViewModel(private val museumRepository: MuseumRepository) : ViewModel() {
fun getObject(objectId: Int): Flow<MuseumObject?> =
museumRepository.getObjectById(objectId)
}screens 패키지에 모듈 클래스를 만들어 이들을 스캔합니다.
@ComponentScan
@Module
class ViewModelModule인자 없이 @ComponentScan을 사용하면 해당 모듈 클래스가 위치한 패키지와 하위 패키지를 스캔합니다. 자세한 내용은 ViewModel을 참조하세요.
플랫폼별 정의 추가하기
이 샘플에서는 플랫폼별로 서로 다른 구현을 제공하는 두 가지 방법을 보여줍니다. 첫 번째 방법은 공용 모듈에서 스캔하는 어노테이션이 적용된 expect 클래스를 사용하는 것입니다.
// commonMain
@Singleton
expect class NativeComponent() {
fun getInfo(): String
}
@Module
@ComponentScan
class NativeComponentModule// androidMain
@Singleton
actual class NativeComponent actual constructor() {
actual fun getInfo(): String = "Android NativeComponent"
}// nativeMain
@Singleton
actual class NativeComponent actual constructor() {
actual fun getInfo(): String = "iOS NativeComponent"
}두 번째 방법은 expect 모듈 클래스를 사용하는 것입니다. 각 플랫폼의 actual 모듈이 공유 인터페이스를 구현한 자체 구현체를 스캔합니다.
// commonMain
interface PlatformComponent {
fun getInfo(): String
}
@Module
expect class PlatformComponentModule// androidMain
@Module
@ComponentScan
actual class PlatformComponentModule
@Singleton
class AndroidPlatformComponent : PlatformComponent {
override fun getInfo(): String = "Android PlatformComponent"
}// iosMain
@Module
@ComponentScan
actual class PlatformComponentModule
@Singleton
class IOSPlatformComponent : PlatformComponent {
override fun getInfo(): String = "iOS PlatformComponent"
}플랫폼 클래스는 플랫폼 종속적인 의존성을 가질 수도 있습니다. Android에서는 AndroidContextWrapper가 Koin으로부터 Android Context를 전달받습니다.
// commonMain
interface ContextWrapper {
fun getContextInfo(): String
}
@Singleton
class NativeContextComponent(val ctx: ContextWrapper) {
fun getInfo(): String = "NativeContextComponent with ctx: ${ctx.getContextInfo()}"
}// androidMain
@Singleton
class AndroidContextWrapper(val context: Context) : ContextWrapper {
override fun getContextInfo(): String = "Android Context: $context"
}// nativeMain
@Singleton
class IOSContextWrapper : ContextWrapper {
override fun getContextInfo(): String = "iOS Context"
}공통 코드는 인터페이스를 요청하고, 각 플랫폼에 맞는 적절한 구현체를 주입받습니다. 이러한 패턴은 KMP 공유 모듈에서 자세히 다룹니다.
모듈 조립하기
포함할 모듈들과 함께 앱 모듈을 선언하고, 진입점 역할을 할 @KoinApplication 객체를 선언합니다.
import org.koin.core.annotation.Configuration
import org.koin.core.annotation.KoinApplication
import org.koin.core.annotation.Module
@Module(includes = [ViewModelModule::class, NativeComponentModule::class, PlatformComponentModule::class])
@Configuration
class AppModule
@KoinApplication
object KoinAppKoinApp은 모든 @Configuration 모듈을 수집합니다. 여기에는 포함된 하위 모듈들을 가진 AppModule과 data Gradle 모듈의 DataModule이 포함됩니다. 컴파일러 플러그인은 빌드 타임에 전체 의존성 그래프를 검증합니다.
Koin 시작 및 ViewModel 주입하기
루트 컴포저블에서 KoinApplication과 koinConfiguration<KoinApp>()을 사용하여 Koin을 시작합니다.
import org.koin.compose.KoinApplication
import org.koin.plugin.module.dsl.koinConfiguration
@Serializable
object ListDestination
@Serializable
data class DetailDestination(val objectId: Int)
@Composable
fun App() {
KoinApplication(configuration = koinConfiguration<KoinApp>()) {
MaterialTheme(
colorScheme = if (isSystemInDarkTheme()) darkColorScheme() else lightColorScheme()
) {
Surface {
val navController: NavHostController = rememberNavController()
NavHost(navController = navController, startDestination = ListDestination) {
composable<ListDestination> {
ListScreen(navigateToDetails = { objectId ->
navController.navigate(DetailDestination(objectId))
})
}
composable<DetailDestination> { backStackEntry ->
DetailScreen(
objectId = backStackEntry.toRoute<DetailDestination>().objectId,
navigateBack = { navController.popBackStack() }
)
}
}
}
}
}
}각 화면에서는 koinViewModel()을 사용하여 ViewModel을 가져옵니다.
import org.koin.compose.viewmodel.koinViewModel
@Composable
fun ListScreen(navigateToDetails: (objectId: Int) -> Unit) {
val viewModel = koinViewModel<ListViewModel>()
val objects by viewModel.objects.collectAsStateWithLifecycle()
...
}
@Composable
fun DetailScreen(objectId: Int, navigateBack: () -> Unit) {
val viewModel = koinViewModel<DetailViewModel>()
val obj by viewModel.getObject(objectId).collectAsStateWithLifecycle(initialValue = null)
...
}KoinApplication은 전체 앱에 대해 Koin을 한 번 시작합니다. Android에서는 Android 컨텍스트와 로거도 설정해주며, 이를 통해 AndroidContextWrapper가 Context를 가져올 수 있게 됩니다. 두 플랫폼 모두 동일한 App 컴포저블을 호스팅하므로, Android의 Application 클래스나 iOS 앱 코드에 별도의 시작 코드를 작성할 필요가 없습니다.
// iosMain
fun MainViewController() = ComposeUIViewController { App() }Android Studio에서 Android 앱을 실행하거나 Xcode에서 iOS 앱을 실행하면 예술품 목록이 표시됩니다. Compose 외부에서는 org.koin.plugin.module.dsl의 startKoin<KoinApp>()을 대신 사용하세요. 자세한 내용은 Compose용 Koin 및 Compose ViewModel을 참조하세요.
다음 단계
- 핵심 개념: 모듈, 정의, 주입의 기반이 되는 멘탈 모델을 알아봅니다.
- KMP 공유 모듈: 여러 플랫폼에 걸쳐 Koin 모듈을 공유하고 분리하는 방법을 알아봅니다.
- 어노테이션 레퍼런스: 모든 어노테이션과 해당 매개변수를 살펴봅니다.
- Compose 테스팅: Koin을 사용하는 컴포저블을 테스트하는 방법을 알아봅니다.
- 도구(Tooling): Koin용 IDE 플러그인 및 모니터링 도구를 확인해 보세요.
