限定詞
限定詞為定義指定一個名稱,讓你可以宣告同一型別的多個定義,並請求特定的某一個定義。本頁面涵蓋字串、型別與列舉限定詞、自訂限定詞註解以及常見錯誤。本文預設你已知曉如何宣告定義(請參閱 定義)。
何時需要限定詞
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,並解析具限定詞的定義。你也可以直接在 LocalDatabase 類別本身加上 @Named("local"):這樣 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)並不相同。
編譯器外掛程式會在建置期檢查自訂限定詞:若提供者與注入點的限定詞不一致,將會產生建置錯誤。自訂限定詞註解也適用於 Compiler Plugin DSL,可用於建構函式參數以及傳遞給 single<T>() 的類別。
自訂限定詞註解無法在 Constructor 或 Classic 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")是兩個不同的限定詞。請使用型別或列舉限定詞,或者將字串保留在常數中,以避免這種情況。 - 對每個定義都加上限定詞:如果型別本來就不同,限定詞就毫無作用。只有在兩個定義共用相同型別時才使用限定詞。
使用編譯器外掛程式時,前兩個錯誤會被視為建置錯誤。當具有限定詞的參數找不到相符項,但存在相同型別的未限定定義時,錯誤訊息會指向該定義。
