限定符
限定符为定义赋予了一个名称,以便你可以声明同一类型的多个定义并请求特定的一个。本页涵盖字符串、类型和枚举限定符、自定义限定符注解以及常见错误。本文假设你已知晓如何声明定义(请参阅定义)。
何时需要限定符
Koin 通过其类型来查找定义。如果两个定义提供了相同的类型(例如两个 Database 实例),对 Database 的普通请求将无法在它们之间做出选择。限定符可以将它们区分开来。
如果这两个对象扮演不同的角色,请考虑为它们赋予不同的类型(例如将 LocalDatabase 和 RemoteDatabase 分别作为它们各自的接口)。类型不匹配会在编译器阶段被捕获,而错误的限定符字符串则不会。
命名限定符
声明每个定义时指定一个名称,然后在注入它的位置请求该名称:
import org.koin.core.annotation.Named
import org.koin.core.qualifier.named
import org.koin.plugin.module.dsl.*
class UserRepository(
@Named("local") private val localDb: Database,
@Named("remote") private val remoteDb: Database,
)
val dataModule = module {
single<Database>(named("local")) { create(::LocalDatabase) }
single<Database>(named("remote")) { create(::RemoteDatabase) }
single<UserRepository>()
}single<UserRepository>() 会读取构造函数形参上的 @Named 并解析带限定符的定义。你也可以将 @Named("local") 直接置于 LocalDatabase 类本身:随后 single<LocalDatabase>() 便会使用该名称进行注册。@Named 注解来自 koin-annotations 构件。
import org.koin.core.annotation.Named
import org.koin.core.annotation.Singleton
@Singleton
@Named("local")
class LocalDatabase : Database
@Singleton
@Named("remote")
class RemoteDatabase : Database
@Singleton
class UserRepository(
@Named("local") private val localDb: Database,
@Named("remote") private val remoteDb: Database,
)@Named 可用于类、提供程序函数以及形参。
import org.koin.core.qualifier.named
val dataModule = module {
single<Database>(named("local")) { LocalDatabase() }
single<Database>(named("remote")) { RemoteDatabase() }
single {
UserRepository(
localDb = get(named("local")),
remoteDb = get(named("remote")),
)
}
}singleOf(::UserRepository) 仅按类型解析形参,因此无法传递限定符。请如示例所示,使用 get(named(...)) 编写构造函数调用。
在定义之外,将限定符传递给 get() 或 inject():
val localDb: Database by inject(named("local"))
val remoteDb: Database = get(named("remote"))相同的限定符实参存在于所有注入 API 中,例如 Compose 中的 koinInject(named("local"))。请参阅注入。
类型限定符
类型也可以充当限定符。拼写错误会变为编译错误,并且在 IDE 中重命名该类型会自动更新所有使用之处:
import org.koin.core.annotation.Qualifier
object LocalDb
object RemoteDb
class UserRepository(
@Qualifier(LocalDb::class) private val localDb: Database,
@Qualifier(RemoteDb::class) private val remoteDb: Database,
)
val dataModule = module {
single<Database>(named<LocalDb>()) { create(::LocalDatabase) }
single<Database>(named<RemoteDb>()) { create(::RemoteDatabase) }
single<UserRepository>()
}object LocalDb
object RemoteDb
@Singleton
@Qualifier(LocalDb::class)
class LocalDatabase : Database
@Singleton
@Qualifier(RemoteDb::class)
class RemoteDatabase : Database
@Singleton
class UserRepository(
@Qualifier(LocalDb::class) private val localDb: Database,
@Qualifier(RemoteDb::class) private val remoteDb: Database,
)@Qualifier(name = "local") 是字符串形式,等同于 @Named("local")。
object LocalDb
object RemoteDb
val dataModule = module {
single<Database>(named<LocalDb>()) { LocalDatabase() }
single<Database>(named<RemoteDb>()) { RemoteDatabase() }
single { UserRepository(get(named<LocalDb>()), get(named<RemoteDb>())) }
}在调用站点:get<Database>(named<LocalDb>())。qualifier<LocalDb>() 是 named<LocalDb>() 的别名。
枚举限定符
枚举成员也可以作为限定符:
enum class DbType { LOCAL, REMOTE }
val dataModule = module {
single<Database>(named(DbType.LOCAL)) { LocalDatabase() }
single<Database>(named(DbType.REMOTE)) { RemoteDatabase() }
}
val localDb: Database = get(named(DbType.LOCAL))named(DbType.LOCAL) 是由小写成员名称构成的字符串限定符。它与 named("local") 是相同的限定符。
自定义限定符注解
使用注解时,你可以创建自己的限定符注解。使用 @Qualifier(或 @Named)对其进行注解,然后像使用 @Named 一样使用它:
import org.koin.core.annotation.Qualifier
@Qualifier
annotation class BaseUrl
@Qualifier
annotation class AuthUrl
@Singleton
@BaseUrl
fun baseUrl(): String = "https://api.example.com"
@Singleton
@AuthUrl
fun authUrl(): String = "https://auth.example.com"
@Singleton
class ApiClient(
@BaseUrl private val baseUrl: String,
@AuthUrl private val authUrl: String,
)不带形参的注解将成为该注解类上的类型限定符。在代码中,可通过 get<String>(named<BaseUrl>()) 进行获取。
自定义限定符可以接受形参,以便通过一个注解定义一组限定符:
enum class AppDispatchers { Default, IO }
@Qualifier
annotation class Dispatcher(val dispatcher: AppDispatchers)
@Module
class DispatchersModule {
@Singleton
@Dispatcher(AppDispatchers.IO)
fun ioDispatcher(): CoroutineDispatcher = Dispatchers.IO
@Singleton
@Dispatcher(AppDispatchers.Default)
fun defaultDispatcher(): CoroutineDispatcher = Dispatchers.Default
@Singleton
fun applicationScope(
@Dispatcher(AppDispatchers.Default) dispatcher: CoroutineDispatcher,
): CoroutineScope = CoroutineScope(SupervisorJob() + dispatcher)
}形参的值将成为限定符:
- 字符串形参:
@ApiName("users")是字符串限定符"users",与@Named("users")相同。 - 枚举形参:
@Dispatcher(AppDispatchers.IO)是由枚举的完全限定类名和成员构成的字符串限定符,即named("com.myapp.AppDispatchers.IO")。它与使用小写成员名称的named(AppDispatchers.IO)不同。
编译器插件会在构建时检查自定义限定符:提供程序和注入点具有不同的限定符将导致构建错误。自定义限定符注解也可用于编译器插件 DSL,作用于构造函数形参以及传递给 single<T>() 的类上。
自定义限定符注解在构造函数或传统 DSL 中不可用。在这些地方请使用 named()。
JSR-330 限定符
jakarta.inject.Named、javax.inject.Named 以及标记有 jakarta.inject.Qualifier 的注解其工作方式与 Koin 的对等项类似。请参阅 JSR-330 支持。
常见错误
- 注入点缺少限定符:当每个
Database定义都带有限定符时,get<Database>()将失败并抛出NoDefinitionFoundException。带有限定符的定义只能通过该限定符来查找到。 - 拼写不同:
named("encrypted")和named("encrypted_client")是两个不同的限定符。使用类型或枚举限定符,或者将字符串保存在常量中,以避免出现此类情况。 - 为每个定义都添加限定符:如果类型本身已经不同,限定符不会带来任何益处。仅在两个定义共享相同类型时才使用限定符。
借助编译器插件,前两个错误会成为构建错误。当带限定符的形参没有匹配项但存在同一类型的无限定符定义时,错误信息会指向该定义。
