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 構件:
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 {
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(工廠):
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 所涵蓋的套件中:
@Module
@ComponentScan("com.example.data")
class DataModule對於自行建構的物件,@Singleton 也可以用於 @Module 類別中的提供者函式:
@Module
class NetworkModule {
@Singleton
fun retrofit(): Retrofit = Retrofit.Builder()
.baseUrl("https://api.example.com")
.build()
}繫結至超型別的方式與 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,
)關於限定詞如何解析,請參閱限定詞。
與 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 或注入參數的註解。請改用 Koin 的對應註解:@KoinViewModel、@KoinWorker、@InjectedParam。Context 參數不需要限定詞:Koin 會傳遞傳給 androidContext() 的 context。
@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 註解一樣由編譯器外掛程式進行檢查(請參閱編譯期安全)。
