Skip to content

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 工件:

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 注解具有更高优先级。例如,在带有 @Inject constructor 的类上添加 @KoinViewModel 会将其声明为 ViewModel,而不是 factory。

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 会使用主构造函数。当一个类有多个构造函数时,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() 的上下文。

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 注解一样由编译器插件进行检查(请参阅编译时安全性)。