Skip to content

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 아티팩트를 그대로 유지합니다:

kotlin
dependencies {
    implementation("jakarta.inject:jakarta.inject-api:2.0.1")
    // 또는 레거시 패키지
    implementation("javax.inject:javax.inject:1")
}

Kotlin 멀티플랫폼 코드에서는 이러한 Java 아티팩트를 사용할 수 없습니다. 모든 Kotlin 타깃에 대해 jakarta.inject 어노테이션을 제공하는 koin-jsr330을 추가하세요:

kotlin
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)를 선언합니다:

kotlin
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의 대상 패키지에 포함되어 있어야 합니다:

kotlin
@Module
@ComponentScan("com.example.data")
class DataModule

@Singleton은 직접 빌드하는 객체를 위해 @Module 클래스의 프로바이더 함수에서도 작동합니다:

kotlin
@Module
class NetworkModule {

    @Singleton
    fun retrofit(): Retrofit = Retrofit.Builder()
        .baseUrl("https://api.example.com")
        .build()
}

상위 타입(supertype)으로의 바인딩은 Koin 어노테이션과 동일하게 동작합니다. 클래스는 해당 인터페이스에 바인딩됩니다(정의 참조).

한정자 ​

@Named는 선언부와 주입 지점 모두에서 작동합니다:

kotlin
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의 커스텀 한정자와 동일하게 작동합니다:

kotlin
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 어노테이션을 함께 사용할 수 있습니다:

kotlin
@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()에 전달된 컨텍스트를 넘겨줍니다.

kotlin
@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 어노테이션과 마찬가지로 컴파일러 플러그인에 의해 검사됩니다(컴파일 타임 안전성 참조).