JSR-330 注解
Koin 编译器插件可以读取来自 jakarta.inject 和 javax.inject 的标准 JSR-330 注解。带有 @Singleton 或 @Inject constructor 的类会成为 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 注解具有更高优先级。例如,在带有 @Inject constructor 的类上添加 @KoinViewModel 会将其声明为 ViewModel,而不是 factory。
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 会使用主构造函数。当一个类有多个构造函数时,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() 的上下文。
@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 注解一样由编译器插件进行检查(请参阅编译时安全性)。
