Skip to content

JSR-330 註解 ​

Koin 編譯器外掛程式會讀取來自 jakarta.inject 與 javax.inject 的標準 JSR-330 註解。帶有 @Singleton 或 @Inject 建構函式的類別會直接成為 Koin 定義,其上不需要有任何 Koin 註解。本頁面列出了支援的內容以及如何進行設定。這適用於註解風格:你需要編譯器外掛程式(Compiler Plugin)以及帶有 @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 Multiplatform 程式碼中,這些 Java 構件無法使用。請加入 koin-jsr330,它為每個 Kotlin 目標提供了 jakarta.inject 註解:

kotlin
kotlin {
    sourceSets {
        commonMain.dependencies {
            implementation("io.insert-koin:koin-jsr330:$koin_annotations_version")
        }
    }
}

NOTE

koin-jsr330 是與 Koin Annotations 一同發佈的,而非與 Koin BOM 一起發佈。請使用 Koin Annotations 的版本。

支援的註解 ​

JSR-330 註解Koin 對應項適用於
@Singleton@Singleton / @Single類別、@Module 中的函式
建構函式上的 @Inject@Factory類別
@Named("x")@Named("x")類別、函式、參數
@Qualifier@Qualifier你自訂的限定詞註解類別

兩個套件皆可運作:jakarta.inject.* 與 javax.inject.*。若在同一個類別上同時存在 Koin 註解,則以 Koin 註解為優先。例如,在帶有 @Inject 建構函式的類別上標註 @KoinViewModel,會宣告為 ViewModel 而非工廠。

JSR-330 的 @Scope 對 Koin 作用域沒有任何效果。請使用 Koin 的 @Scope 與 @Scoped,或是作用域原型(例如 @ActivityScope,請參閱作用域)。

定義 ​

@Singleton 會宣告一個 single(單例)。帶有 @Inject 建構函式且沒有其他註解的類別則會宣告一個 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 會使用主建構函數。當類別有多個建構函式時,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()
}

繫結至超型別的方式與 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,
)

關於限定詞如何解析,請參閱限定詞。

與 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 或注入參數的註解。請改用 Koin 的對應註解:@KoinViewModel、@KoinWorker、@InjectedParam。Context 參數不需要限定詞:Koin 會傳遞傳給 androidContext() 的 context。

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> 參數。請使用 Lazy<T> 參數,或參閱進階模式中的提供者模式。
  • 僅限註解風格:@Singleton 與 @Inject 僅透過 @ComponentScan 來宣告定義。在 DSL 模組中,你仍需撰寫 single<T>()。接著編譯器外掛程式 DSL 會讀取參數上的 @Named,並使用帶有 @Inject 的建構函式。
  • 編譯期安全:JSR-330 定義會像 Koin 註解一樣由編譯器外掛程式進行檢查(請參閱編譯期安全)。