JSR-330 어노테이션
Koin 컴파일러 플러그인은 jakarta.inject 및 javax.inject의 표준 JSR-330 어노테이션을 읽어 들입니다. 별도의 Koin 어노테이션 없이도 @Singleton 또는 @Inject constructor가 지정된 클래스는 Koin 정의(definition)가 됩니다. 이 페이지에서는 지원되는 항목과 설정 방법을 설명합니다. 이는 어노테이션 스타일에 적용되며, 컴파일러 플러그인과 @ComponentScan이 적용된 모듈이 필요합니다(모듈 참조).
주요 사용 사례는 다른 JSR-330 프레임워크와 공유하는 코드이거나, 기존 클래스를 변경하지 않고 유지하는 Hilt 또는 Dagger로부터의 마이그레이션입니다(Hilt에서 마이그레이션하기 참조).
설정
JVM 및 Android에서는 이미 사용 중인 JSR-330 아티팩트를 그대로 유지합니다:
dependencies {
implementation("jakarta.inject:jakarta.inject-api:2.0.1")
// 또는 레거시 패키지
implementation("javax.inject:javax.inject:1")
}Kotlin 멀티플랫폼 코드에서는 이러한 Java 아티팩트를 사용할 수 없습니다. 모든 Kotlin 타깃에 대해 jakarta.inject 어노테이션을 제공하는 koin-jsr330을 추가하세요:
kotlin {
sourceSets {
commonMain.dependencies {
implementation("io.insert-koin:koin-jsr330:$koin_annotations_version")
}
}
}NOTE
koin-jsr330은 Koin BOM이 아닌 Koin Annotations와 함께 배포됩니다. Koin Annotations 버전을 사용하세요.
지원되는 어노테이션
| JSR-330 어노테이션 | Koin 동등 항목 | 적용 대상 |
|---|---|---|
@Singleton | @Singleton / @Single | 클래스, @Module 내의 함수 |
생성자의 @Inject | @Factory | 클래스 |
@Named("x") | @Named("x") | 클래스, 함수, 파라미터 |
@Qualifier | @Qualifier | 커스텀 한정자(qualifier) 어노테이션 클래스 |
jakarta.inject.* 및 javax.inject.* 두 패키지 모두 작동합니다. 동일한 클래스에 지정된 Koin 어노테이션이 우선순위를 갖습니다. 예를 들어, @Inject constructor가 있는 클래스에 지정된 @KoinViewModel은 팩토리가 아닌 ViewModel을 선언합니다.
JSR-330의 @Scope는 Koin 스코프에 아무런 영향을 주지 않습니다. Koin의 @Scope와 @Scoped, 또는 @ActivityScope와 같은 스코프 아키타입을 사용하세요(스코프 참조).
정의
@Singleton은 싱글톤(single)을 선언합니다. 다른 어노테이션 없이 @Inject constructor만 있는 클래스는 팩토리(factory)를 선언합니다:
import jakarta.inject.Inject
import jakarta.inject.Singleton
@Singleton
class UserRepository @Inject constructor(
private val api: ApiService,
private val database: UserDatabase,
)
// 요청마다 새로운 인스턴스 생성
class GetUserUseCase @Inject constructor(
private val repository: UserRepository,
)클래스에 @Singleton 어노테이션이 있는 경우 @Inject는 선택 사항입니다. Koin은 기본 생성자(primary constructor)를 사용합니다. 클래스에 생성자가 여러 개 있는 경우, Koin은 @Inject가 지정된 생성자를 사용합니다.
다른 어노테이션된 클래스와 마찬가지로, 이러한 클래스는 @ComponentScan의 대상 패키지에 포함되어 있어야 합니다:
@Module
@ComponentScan("com.example.data")
class DataModule@Singleton은 직접 빌드하는 객체를 위해 @Module 클래스의 프로바이더 함수에서도 작동합니다:
@Module
class NetworkModule {
@Singleton
fun retrofit(): Retrofit = Retrofit.Builder()
.baseUrl("https://api.example.com")
.build()
}상위 타입(supertype)으로의 바인딩은 Koin 어노테이션과 동일하게 동작합니다. 클래스는 해당 인터페이스에 바인딩됩니다(정의 참조).
한정자
@Named는 선언부와 주입 지점 모두에서 작동합니다:
import jakarta.inject.Inject
import jakarta.inject.Named
import jakarta.inject.Singleton
@Singleton
@Named("inMemory")
class InMemoryCache @Inject constructor() : Cache
@Singleton
@Named("disk")
class DiskCache @Inject constructor(private val context: Context) : Cache
@Singleton
class ImageLoader @Inject constructor(
@Named("inMemory") private val memoryCache: Cache,
@Named("disk") private val diskCache: Cache,
)JSR-330의 @Qualifier가 지정된 커스텀 한정자 어노테이션은 Koin의 커스텀 한정자와 동일하게 작동합니다:
import jakarta.inject.Qualifier
@Qualifier
@Retention(AnnotationRetention.BINARY)
annotation class IoDispatcher
@Module
class DispatcherModule {
@Singleton
@IoDispatcher
fun ioDispatcher(): CoroutineDispatcher = Dispatchers.IO
}
@Singleton
class SyncManager @Inject constructor(
@IoDispatcher private val dispatcher: CoroutineDispatcher,
)한정자가 확인(resolve)되는 방식에 대해서는 한정자를 참조하세요.
Koin 어노테이션과 혼용하기
동일한 프로젝트 내에서, 그리고 동일한 클래스에서 JSR-330과 Koin 어노테이션을 함께 사용할 수 있습니다:
@Singleton // jakarta.inject
@Named("local")
class LocalDatabase @Inject constructor() : Database
@Single // Koin
@Named("remote")
class RemoteDatabase(private val api: ApiService) : Database
@Factory // Koin, JSR-330 생성자 사용
class DatabaseManager @Inject constructor(
@Named("local") private val local: Database,
@Named("remote") private val remote: Database,
)JSR-330에는 ViewModel, 워커(Worker) 또는 주입된 파라미터(injected parameter)를 위한 어노테이션이 없습니다. 이러한 항목에는 Koin 어노테이션인 @KoinViewModel, @KoinWorker, @InjectedParam을 사용하세요. Context 파라미터에는 한정자가 필요하지 않습니다. Koin이 androidContext()에 전달된 컨텍스트를 넘겨줍니다.
@KoinViewModel
class UserViewModel @Inject constructor(
private val repository: UserRepository,
private val savedStateHandle: SavedStateHandle,
) : ViewModel()제한 사항
- 필드 및 메서드 주입:
@Inject lateinit var필드와@Inject메서드는 지원되지 않습니다. 생성자를 통해 주입하거나 Android 컴포넌트에서by inject()를 사용하세요(진입점 참조). Provider<T>:jakarta.inject.Provider<T>파라미터는 확인할 수(resolve) 없습니다.Lazy<T>파라미터를 사용하거나 고급 패턴의 프로바이더 패턴을 사용하세요.- 어노테이션 스타일 전용:
@Singleton및@Inject는@ComponentScan을 통해서만 정의를 선언합니다. DSL 모듈에서는 여전히single<T>()를 작성해야 합니다. 그런 다음 컴파일러 플러그인 DSL이 파라미터의@Named를 읽고@Inject생성자를 사용합니다. - 컴파일 타임 안전성: JSR-330 정의는 Koin 어노테이션과 마찬가지로 컴파일러 플러그인에 의해 검사됩니다(컴파일 타임 안전성 참조).
관련 문서
- Hilt에서 마이그레이션하기: JSR-330을 통해 기존 클래스를 유지하면서 진행하는 단계별 마이그레이션 가이드입니다.
- 정의: 정의 유형 및 인터페이스 바인딩.
- 한정자: 명명된 한정자(named), 타입 한정자 및 커스텀 한정자.
- 어노테이션 레퍼런스: 모든 Koin 어노테이션에 대한 설명.
- 컴파일러 플러그인 설정: 플러그인 설치 방법.
