Skip to content

Android & Annotations ​

이 튜토리얼에서는 목록에서 선택한 사용자에게 인사말을 건네는 Android 앱을 빌드합니다. 클래스에 어노테이션을 지정하고, 이를 모듈로 스캔하며, ViewModel에 자체 스코프 종속성(scoped dependency)을 부여하고, @KoinApplication 클래스에서 Koin을 시작하는 방법을 알아봅니다. 약 10분이 소요되며 Android Studio가 필요합니다.

이 튜토리얼은 어노테이션을 사용합니다. Compiler Plugin DSL을 사용한 동일한 앱에 대해서는 Android 및 Android ViewModel을 참고하세요. 스타일을 비교하려면 Choosing your style을 참조하세요.

코드 가져오기 ​

전체 샘플 코드는 koin-getting-started/android-annotations에 있습니다. 저장소를 복제(clone)하고 Android Studio에서 android-annotations 폴더를 엽니다.

Gradle 설정 ​

이 샘플은 Koin Compiler Plugin을 적용하고 koin-android 및 koin-annotations를 추가합니다. 버전은 버전 카탈로그(version catalog)에서 관리됩니다.

toml
# gradle/libs.versions.toml
[versions]
# Kotlin, Android Gradle Plugin 및 AndroidX 항목 생략
koin = "<KOIN_VERSION>"
koin-plugin = "<KOIN_PLUGIN_VERSION>"

[libraries]
koin-android = { module = "io.insert-koin:koin-android", version.ref = "koin" }
koin-annotations = { module = "io.insert-koin:koin-annotations", version.ref = "koin" }
koin-test-junit4 = { module = "io.insert-koin:koin-test-junit4", version.ref = "koin" }

[plugins]
koin-compiler = { id = "io.insert-koin.compiler.plugin", version.ref = "koin-plugin" }
kotlin
// app/build.gradle.kts
plugins {
    alias(libs.plugins.android.application)
    alias(libs.plugins.kotlin.android)
    alias(libs.plugins.koin.compiler)
}

dependencies {
    implementation(libs.android.appcompat)
    implementation(libs.koin.android)
    implementation(libs.koin.annotations)

    testImplementation(libs.koin.test.junit4)
}

Compiler Plugin은 어노테이션을 처리하며 Kotlin 2.3.20 이상이 필요합니다. koin-annotations는 Koin 버전을 공유합니다. 컴파일 타임 안전성(Compile-time safety)은 기본적으로 활성화되어 있습니다. 자세한 내용은 Gradle setup 및 Compiler Plugin setup을 참조하세요.

애플리케이션 구조 ​

Activity는 ViewModel에 인사말을 요청합니다. ViewModel은 UserRepository에서 데이터를 읽어오는 UserService를 사용하며, 자신의 수명 주기에 스코프가 지정된 UserPresenter를 소유합니다.

User -> UserRepository -> UserService -> UserViewModel (+ UserPresenter) -> MainActivity

사용자 데이터 작성하기 ​

데이터 클래스와 기본 사용자 목록부터 시작합니다.

kotlin
data class User(val name: String, val email: String)

val DEFAULT_USER = User("Alice", "alice@example.com")

val DEFAULT_USERS = listOf(
    DEFAULT_USER,
    User("Bob", "bob@example.com"),
    User("Charlie", "charlie@example.com")
)

이 사용자들은 리포지토리에 저장되는 데이터입니다.

리포지토리 작성하기 ​

리포지토리는 메모리에 사용자를 유지합니다. 구현체에 @Singleton 어노테이션을 추가합니다.

kotlin
import org.koin.core.annotation.Singleton

interface UserRepository {
    fun findUserOrNull(name: String): User?
    fun addUsers(users: List<User>)
}

@Singleton
class UserRepositoryImpl : UserRepository {

    private val _users = arrayListOf<User>()

    override fun findUserOrNull(name: String): User? {
        return _users.firstOrNull { it.name == name }
    }

    override fun addUsers(users: List<User>) {
        _users.addAll(users)
    }
}

Koin은 UserRepositoryImpl을 상위 타입에 바인딩하므로, UserRepository를 요청하면 이 인스턴스를 가져옵니다. @Singleton은 @Single과 동일합니다(Definitions 참조).

서비스 작성하기 ​

UserService는 생성될 때 사용자를 로드하고 인사말 메시지를 준비합니다.

kotlin
interface UserService {
    fun getUserOrNull(name: String = DEFAULT_USER.name): User?
    fun loadUsers()
    fun prepareHelloMessage(user: User?): String
}

@Singleton
class UserServiceImpl(
    private val userRepository: UserRepository
) : UserService {

    init {
        loadUsers()
    }

    override fun getUserOrNull(name: String): User? = userRepository.findUserOrNull(name)

    override fun loadUsers() {
        userRepository.addUsers(DEFAULT_USERS)
    }

    override fun prepareHelloMessage(user: User?): String {
        return user?.let { "Hello '${user.name}' (${user.email})!" } ?: "User not found"
    }
}

Compiler Plugin이 생성자를 확인하여 UserRepository 인스턴스를 자동으로 전달합니다.

Presenter와 ViewModel 작성하기 ​

Presenter는 인사말의 서식을 지정합니다. 각 ViewModel이 자체 인스턴스를 갖도록 @ViewModelScope 어노테이션을 추가합니다.

kotlin
import org.koin.core.annotation.ViewModelScope

@ViewModelScope
class UserPresenter(
    private val userService: UserService
) {

    fun sayHello(name: String): String {
        val user = userService.getUserOrNull(name)
        val message = userService.prepareHelloMessage(user)
        return "[UserPresenter] $message"
    }
}

ViewModel에는 @KoinViewModel과 스코프가 지정된 Presenter를 주입받을 수 있도록 @ViewModelScope 어노테이션을 추가합니다.

kotlin
import org.koin.core.annotation.KoinViewModel
import org.koin.core.annotation.ViewModelScope

@ViewModelScope
@KoinViewModel
class UserViewModel(
    private val userService: UserService,
    private val userPresenter: UserPresenter
) : ViewModel() {

    fun sayHello(name: String): String {
        val user = userService.getUserOrNull(name)
        val message = userService.prepareHelloMessage(user)
        return "[UserViewModel] $message"
    }
}

Presenter는 ViewModel과 동일한 수명 주기를 가지며, ViewModel이 지워질(cleared) 때 함께 해제됩니다. ViewModel 스코프에 대한 설명은 ViewModel을, 일반적인 스코프에 대한 설명은 Scopes를 참조하세요.

Koin 모듈 선언하기 ​

모듈은 정의(definitions)를 그룹화합니다(Core Concepts 참조). 샘플 패키지를 스캔하는 모듈 클래스를 선언합니다.

kotlin
import org.koin.core.annotation.ComponentScan
import org.koin.core.annotation.Configuration
import org.koin.core.annotation.Module

@Module
@ComponentScan("org.koin.sample")
@Configuration
class AppModule

@ComponentScan은 org.koin.sample 및 그 하위 패키지에 있는 어노테이션이 달린 모든 클래스를 등록합니다. @Configuration은 @KoinApplication 진입점에서 이 모듈을 탐색할 수 있도록 만듭니다. 두 어노테이션 모두 Modules에 설명되어 있습니다.

Activity에 ViewModel 주입하기 ​

MainActivity에서 by viewModel() 델리게이트를 사용합니다.

kotlin
import org.koin.androidx.viewmodel.ext.android.viewModel

class MainActivity : AppCompatActivity() {

    private val viewModel: UserViewModel by viewModel()

    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        setContentView(R.layout.activity_simple)

        val nameInput = findViewById<EditText>(R.id.nameInput)
        val sayHelloButton = findViewById<Button>(R.id.sayHelloButton)
        val textField = findViewById<TextView>(R.id.text)

        sayHelloButton.setOnClickListener {
            val userName = nameInput.text.toString().trim().ifEmpty { "Alice" }
            textField.text = viewModel.sayHello(userName)
        }
    }
}

by viewModel()은 ViewModel 팩토리를 대신 생성하고 인스턴스를 Activity 수명 주기에 바인딩합니다. 다른 델리게이트들은 Android ViewModel을 참고하세요.

Koin 시작하기 ​

Application 클래스에 @KoinApplication 어노테이션을 달고, 타입이 지정된 startKoin<T>()를 사용하여 Koin을 시작합니다. AndroidManifest.xml에 해당 클래스를 등록하세요.

kotlin
import org.koin.android.ext.koin.androidContext
import org.koin.android.ext.koin.androidLogger
import org.koin.core.annotation.KoinApplication
import org.koin.core.annotation.KoinViewModelScopeApi
import org.koin.core.logger.Level
import org.koin.core.option.viewModelScopeFactory
import org.koin.plugin.module.dsl.startKoin

@OptIn(KoinViewModelScopeApi::class)
@KoinApplication
class MainApplication : Application() {

    override fun onCreate() {
        super.onCreate()

        startKoin<MainApplication> {
            androidContext(this@MainApplication)
            androidLogger(level = Level.DEBUG)
            options(viewModelScopeFactory())
        }
    }
}

startKoin<MainApplication>은 모든 @Configuration 모듈을 로드하므로 modules()를 직접 호출하지 않아도 됩니다. viewModelScopeFactory()는 @ViewModelScope에 필요한 각 ViewModel용 스코프를 생성하도록 Koin에 지시합니다. 이는 opt-in API입니다(@KoinViewModelScopeApi). 다른 옵션에 대해서는 Starting Koin on Android를 참조하세요.

빌드 타임에 그래프 검증하기 ​

프로젝트를 빌드합니다. Compiler Plugin이 전체 그래프를 검증합니다. 종속성이 누락되었거나 한정자(qualifier)가 일치하지 않는 경우, 또는 선언되지 않은 ViewModel에 대해 by viewModel()을 호출하면 해당 파일과 줄 번호를 표시하며 빌드가 실패합니다.

앱을 실행하고 이름을 입력한 다음 버튼을 눌러 인사말을 확인해 보세요. 플러그인이 확인하는 항목은 Compile-Time Safety에 나열되어 있습니다.

다음 단계 ​