Koin 시작하기
이 페이지에서는 Koin 컨테이너를 시작하는 방법, 시작 시 전달할 수 있는 옵션, @KoinApplication을 사용한 타입 안전한 시작(typed startup), 로깅, 프로퍼티, 그리고 나중에 모듈을 로드하거나 언로드하는 방법을 다룹니다. 모듈이 무엇인지 이미 알고 있다고 가정합니다(모듈 참조).
코드 예제는 Compiler Plugin DSL, Annotations, Constructor / Classic DSL의 세 가지 탭으로 제공됩니다. 원하는 방식을 선택하세요. 이 선택은 모든 페이지에 적용됩니다.
Koin 시작
import org.koin.core.context.startKoin
fun main() {
startKoin {
printLogger()
modules(appModule)
}
}import org.koin.plugin.module.dsl.startKoin
@KoinApplication(modules = [AppModule::class])
class MyApp
fun main() {
startKoin<MyApp> {
printLogger()
}
}Koin 컴파일러 플러그인은 startKoin<MyApp>()을 @KoinApplication에 나열된 모듈과 자동으로 발견된 @Configuration 모듈들을 로드하는 startKoin { } 호출로 대체합니다. 자세한 내용은 @KoinApplication을 사용한 타입 안전한 시작을 참조하세요.
import org.koin.core.context.startKoin
fun main() {
startKoin {
printLogger()
modules(appModule)
}
}startKoin은 컨테이너를 생성하고 프로세스의 기본 컨텍스트인 GlobalContext에 등록합니다. 호출이 완료되면 모든 get(), by inject() 또는 플랫폼 API(by viewModel(), koinInject())가 이 컨테이너로부터 의존성을 해결(resolve)합니다.
startKoin은 프로세스당 한 번만 호출할 수 있습니다. 두 번 호출하면 KoinApplicationAlreadyStartedException이 발생합니다. 시작한 후에 모듈을 추가하려면 loadKoinModules를 사용하세요.
시작 옵션
startKoin { } 블록 내부의 모든 설정은 컨테이너를 구성하는 데 사용됩니다:
startKoin {
printLogger(Level.DEBUG)
properties(mapOf("server_url" to "https://api.example.com"))
allowOverride(false)
modules(coreModule, networkModule)
lazyModules(analyticsModule)
}| 옵션 | 동작 설명 |
|---|---|
modules(...) | 모듈을 즉시 로드합니다. 단일 모듈, 여러 모듈 또는 List<Module>을 전달받습니다. |
lazyModules(...) | 백그라운드에서 모듈을 로드합니다. koin-core-coroutines가 필요하며, 지연 모듈(Lazy Modules)을 참조하세요. |
printLogger(level) | 콘솔에 로그를 출력합니다. 로깅을 참조하세요. |
logger(logger) | 직접 구현한 Logger를 사용합니다. |
properties(map) | 맵으로부터 프로퍼티를 추가합니다. 프로퍼티를 참조하세요. |
fileProperties(file) | 클래스패스 파일(기본값은 /koin.properties)에서 프로퍼티를 로드합니다(JVM 전용). |
environmentProperties() | 시스템 프로퍼티와 환경 변수를 로드합니다(JVM 전용). |
allowOverride(false) | .override() 없이 두 정의가 동일한 타입을 선언할 경우 실패하도록 합니다. 정의 오버라이드를 참조하세요. |
strictOverride() | allowOverride(false)와 동일합니다. |
createEagerInstances() | createdAtStart 정의들을 지금 생성합니다. startKoin과 koinApplication은 블록 끝에서 이를 이미 수행하므로, koinApplication(createEagerInstances = false)를 사용할 때만 필요합니다. |
startKoin 블록은 호출 스레드에서 실행됩니다. 여기서 로드하는 모든 모듈과 모든 createdAtStart 정의는 시작 시간에 영향을 줍니다.
@KoinApplication을 사용한 타입 안전한 시작
Koin 컴파일러 플러그인을 사용하면, @KoinApplication 애너테이션이 추가된 애플리케이션 클래스가 로드할 모듈을 선언합니다. 해당 클래스로부터 타입 안전한 호출을 통해 Koin을 시작할 수 있습니다:
@Module
@ComponentScan("com.myapp.data")
class DataModule
@Module(includes = [DataModule::class])
class AppModule
@KoinApplication(modules = [AppModule::class])
class MyApp| 호출 | 결과 |
|---|---|
startKoin<MyApp>() | GlobalContext에서 MyApp의 모듈과 함께 Koin을 시작합니다. |
startKoin<MyApp> { ... } | 위와 동일하며, 구성 블록(로거, 프로퍼티, 추가 DSL 모듈)을 함께 전달합니다. |
koinApplication<MyApp>() | 전역에 등록되지 않는 격리된 KoinApplication을 생성합니다. |
koinConfiguration<MyApp>() | Koin을 대신 시작해 주는 API(Compose KoinApplication, Ktor)를 위한 KoinConfiguration을 생성합니다. |
withConfiguration<MyApp>() | 기존 KoinApplication에 MyApp의 모듈을 추가합니다(예: Ktor의 install(Koin) { } 내부). |
이 함수들은 org.koin.plugin.module.dsl에서 임포트됩니다. 이들은 컴파일러 스텁(compiler stub)입니다. 즉, 컴파일러 플러그인이 적용되지 않은 상태에서 실행하면 플러그인이 누락되었다는 메시지와 함께 런타임 에러가 발생합니다.
@KoinApplication은 두 개의 파라미터를 받습니다:
modules: 명시적으로 로드할@Module클래스들.configurations: 탐색할 구성 라벨들. 구성 라벨을 참조하세요.
각 @Module 클래스는 자신의 includes와 @ComponentScan 정의들을 가져옵니다. startKoin<MyApp> { }의 구성 블록은 일반적인 startKoin 블록이므로, 애너테이션 모듈과 DSL 모듈을 함께 혼합하여 사용할 수 있습니다:
startKoin<MyApp> {
printLogger()
modules(legacyDslModule)
}@KoinApplication 없이 @Module 클래스 로드하기
일반적인 startKoin { } 또는 koinApplication { } 블록 내에서 @Module 클래스를 직접 로드할 수 있습니다:
import org.koin.plugin.module.dsl.module
import org.koin.plugin.module.dsl.modules
startKoin {
module<NetworkModule>()
modules(DataModule::class, CacheModule::class)
}이 방식은 일부 모듈만 로드하려는 테스트 환경에서 유용합니다. module<T>()와 modules(vararg KClass) 역시 컴파일러 스텁이며, 플러그인이 이미 코드를 재작성하는 startKoin<T> { } 내부에서는 작동하지 않습니다.
NOTE
컴파일러 플러그인을 사용할 때는 호출할 AppModule().module 확장 프로퍼티가 존재하지 않습니다. 애너테이션 기반 모듈은 위에서 살펴본 것처럼 @KoinApplication과 startKoin<T>()를 사용하거나 module<T>()를 통해 로드하세요.
구성 라벨
@Configuration 태그가 지정된 @Module은 클래스패스 상의 다른 Gradle 모듈에 속한 것을 포함하여 @KoinApplication에 의해 자동으로 검색됩니다(@Configuration을 통한 자동 탐색 참조). 라벨을 사용하면 이러한 모듈 중 로드할 대상을 선택할 수 있습니다:
@Module
@Configuration
class CoreModule
@Module
@Configuration("prod")
class ProdDatabaseModule
@Module
@Configuration("test")
class TestDatabaseModule
@Module
@Configuration("default", "test")
class LoggingModule@KoinApplication
class MyApp // CoreModule 및 LoggingModule 로드
@KoinApplication(configurations = ["default", "prod"])
class ProdApp // CoreModule, LoggingModule, ProdDatabaseModule 로드
@KoinApplication(configurations = ["test"])
class TestApp // TestDatabaseModule 및 LoggingModule 로드규칙은 다음과 같습니다:
- 값이 지정되지 않은
@Configuration은"default"라벨을 의미합니다.@Configuration("default")와 동일합니다. configurations가 지정되지 않은@KoinApplication은"default"라벨만 로드합니다.- 라벨 목록을 지정하면 해당 라벨들만 로드됩니다. 기본 모듈도 계속 로드하려면 목록에
"default"를 추가하세요. - 하나의 모듈에 여러 라벨을 지정할 수 있습니다.
koinApplication을 사용한 격리된 인스턴스
koinApplication { }은 GlobalContext에 등록되지 않는 컨테이너를 생성합니다:
val koinApp = koinApplication {
modules(sdkModule)
}
val service = koinApp.koin.get<SdkService>()전역 API(KoinComponent, Activity 내의 by inject())는 이 컨테이너를 인식하지 못합니다. 호스트 앱의 컨테이너를 공유하지 않아야 하는 라이브러리 및 SDK나 독립된 인스턴스가 필요한 테스트에 사용하세요. 전체 패턴은 컨텍스트 격리(Context Isolation)에 설명되어 있습니다.
koinConfiguration { }은 아무것도 시작하지 않고 설정만을 구성합니다. Compose의 KoinApplication이나 Ktor 플러그인과 같이 Koin을 직접 시작하는 API에 전달할 때 사용합니다.
플랫폼별 시작 방법
- Android:
androidContext()및androidLogger()와 함께Application.onCreate()에서 Koin을 시작합니다. Android에서 Koin 시작하기를 참조하세요. - Compose:
KoinApplication또는KoinMultiplatformApplication을 사용하여 컴포저블 내에서 Koin을 시작합니다. Compose용 Koin을 참조하세요. - Ktor:
Application모듈에Koin플러그인을 설치합니다. Ktor용 Koin을 참조하세요. - Kotlin Multiplatform:
commonMain에서initKoin()함수를 공유하고 각 플랫폼에서 호출합니다. KMP 설정을 참조하세요.
런타임에 모듈 로드 및 언로드
시작 후에도 전역 컨테이너에 모듈을 추가하거나 제거할 수 있습니다:
import org.koin.core.context.loadKoinModules
import org.koin.core.context.unloadKoinModules
if (premiumEnabled) {
loadKoinModules(premiumModule)
}
// 이후 시점
unloadKoinModules(premiumModule)두 함수 모두 단일 모듈 또는 List<Module>을 받습니다. unloadKoinModules는 모듈의 정의들을 제거하고 해당 인스턴스들을 폐기하므로, 이후 이 타입들에 대한 get() 호출은 실패합니다.
컴파일러 플러그인은 런타임에 조립되는 그래프를 검증할 수 없습니다. 모듈이 언제 로드되는지, 혹은 실제로 로드되는지 알 수 없기 때문입니다. 런타임에 로드되는 모듈에서 다른 정의가 필요로 하는 타입은 반드시 @Provided로 표시해야 하며, 플러그인은 해당 모듈 자체가 시작 시점에 로드되지 않은 것으로 보고합니다. 컴파일 타임 안전성(Compile-Time Safety)을 참조하세요. 시작 속도를 높이기 위한 목적으로만 나중에 모듈을 로드하는 것이라면 대개 지연 모듈(Lazy Modules)이 더 적합합니다.
Koin 중지
import org.koin.core.context.stopKoin
stopKoin()stopKoin()은 전역 컨테이너를 종료합니다. 모든 인스턴스를 해제하고, 정의들의 onClose 콜백을 호출하며, GlobalContext를 정리합니다. 이후 startKoin을 다시 호출할 수 있습니다. 격리된 컨테이너의 경우 KoinApplication에서 close()를 호출하세요:
koinApp.close()테스트에서는 다음 테스트가 깨끗한 상태에서 시작될 수 있도록 매 테스트가 끝난 후 Koin을 중지하세요. 테스트에서 이를 자동으로 처리해 주는 JUnit 룰을 확인할 수 있습니다.
로깅
Koin은 기본적으로 아무것도 로깅하지 않습니다(EmptyLogger). 시작 블록에서 로깅을 활성화하세요:
startKoin {
printLogger(Level.DEBUG)
modules(appModule)
}Level에는 DEBUG, INFO, WARNING, ERROR, NONE이 있습니다. 각 로거의 기본 레벨은 INFO입니다.
| 로거 | 시작 옵션 | 플랫폼 | 아티팩트 |
|---|---|---|---|
EmptyLogger | (기본값) | 전체 | koin-core |
PrintLogger | printLogger() | 전체 | koin-core |
AndroidLogger | androidLogger() | Android (Logcat) | koin-android |
SLF4JLogger | slf4jLogger() | JVM | koin-logger-slf4j |
DEBUG 레벨에서 Koin은 각 모듈 로드와 각 의존성 해결(resolution) 과정을 소요 시간과 함께 로깅합니다. 이는 느린 정의를 찾는 데 유용하지만, 프로덕션 환경에는 너무 상세(verbose)합니다.
다른 곳으로 로그를 전송하려면 Logger를 상속받아 logger()로 전달하세요:
import org.koin.core.logger.Level
import org.koin.core.logger.Logger
import org.koin.core.logger.MESSAGE
class AppLogger : Logger(Level.INFO) {
override fun display(level: Level, msg: MESSAGE) {
MyLogSystem.log(level.name, msg)
}
}
startKoin {
logger(AppLogger())
}프로퍼티
프로퍼티(Properties)는 컨테이너에 저장되는 키-값 쌍입니다. URL이나 키와 같은 설정 값에 사용하세요.
프로퍼티 로드
startKoin {
properties(mapOf("server_url" to "https://api.example.com"))
fileProperties() // JVM: 클래스패스에서 /koin.properties를 읽음
environmentProperties() // JVM: 시스템 프로퍼티 및 환경 변수를 읽음
}Android에서는 androidFileProperties()가 assets 폴더에서 koin.properties를 읽습니다. 런타임에 Koin 인스턴스에서 프로퍼티를 설정하고 읽을 수도 있습니다:
val koin = KoinPlatform.getKoin()
koin.setProperty("session_token", token)
val token: String? = koin.getProperty("session_token")파일이나 환경 변수에서 로드된 값은 String입니다. 필요에 따라 직접 변환하세요(getProperty<String>("timeout").toInt()).
프로퍼티 주입
생성자 파라미터에 (koin-annotations의) @Property 애너테이션을 추가합니다:
class ApiClient(@Property("server_url") val url: String)
val networkModule = module {
single<ApiClient>()
}@Singleton
class ApiClient(@Property("server_url") val url: String)프로퍼티에 기본값을 지정하려면 동일한 키를 가진 최상위 값(top-level value)에 @PropertyValue 애너테이션을 추가합니다:
@PropertyValue("server_url")
val defaultServerUrl = "https://api.example.com"생성된 코드는 getProperty("server_url", defaultServerUrl)을 읽으므로, 아무도 프로퍼티를 설정하지 않았을 때 ApiClient가 기본값을 받게 됩니다.
val networkModule = module {
single { ApiClient(url = getProperty("server_url")) }
// 기본값이 있는 경우
single { ApiClient(url = getProperty("server_url", "https://api.example.com")) }
}getProperty(key)는 프로퍼티가 없으면 예외를 발생시킵니다. getPropertyOrNull(key)는 대신 null을 반환합니다.
여러 곳에서 getProperty를 호출하는 대신, 하나의 설정 클래스에서 프로퍼티를 읽고 해당 클래스를 주입하는 방식을 권장합니다. 이렇게 하면 키들을 하나의 파일에서 관리할 수 있습니다.
제한 사항
startKoin은 프로세스당 한 번만 실행됩니다. 다시 시작하기 전에stopKoin()을 호출하세요.fileProperties()와environmentProperties()는 JVM에서만 지원됩니다. 다른 플랫폼에서는properties()로 맵을 전달하세요.- 타입 안전한 시작(
startKoin<T>(),module<T>())에는 컴파일러 플러그인이 필요합니다. KSP 프로세서는 지원 중단(deprecated)되었으므로 KSP에서 마이그레이션하기를 참조하세요. - 시작 이후
loadKoinModules로 로드된 모듈은 컴파일 타임 그래프 검사에 포함되지 않습니다.
관련 문서
- 모듈: 정의 구조화,
includes(),@Module및@Configuration. - 정의: Koin이 생성하는 대상 선언, 즉시 생성(eager creation) 및 오버라이드.
- 지연 모듈: 시작 시간을 단축하기 위해 백그라운드에서 모듈 로드.
- 컨텍스트 격리: SDK를 위해 격리된 컨테이너에서 Koin 실행.
- 컴파일러 플러그인 설정:
startKoin<T>()에 필요한 플러그인 설치. - Android에서 Koin 시작하기:
androidContext(),androidLogger()및 AndroidX Startup.
