Skip to content

定義 ​

定義會告訴 Koin 如何建立某個型別,以及該執行個體應保留多久。本頁面涵蓋定義型別、介面繫結、建構函式參數的解析方式,以及非自有的類別之定義。本文假設你已經了解什麼是模組(請參閱核心概念)。

程式碼範例提供三種分頁標籤:Compiler Plugin DSL、Annotations、Constructor / Classic DSL。請選擇你偏好的方式,該選擇將套用至所有頁面。若你不確定該使用哪種風格,請閱讀選擇你的風格。

定義型別 ​

型別執行個體一般用途
single單一執行個體,在 Koin 容器的生命週期內持續保留Repository、API 用戶端、資料庫
factory每次被請求時建立新的執行個體Presenter、使用案例、短期的物件
scoped每個作用域單一執行個體,當作用域關閉時釋放繫結至 Activity、工作階段 (session)、請求的物件
viewModel由 ViewModel 生命週期管理ViewModel(Android 與 Compose Multiplatform)
worker由 WorkManager 建立Android ListenableWorker

宣告方式:

kotlin
import org.koin.dsl.module
import org.koin.plugin.module.dsl.*

val appModule = module {
    single<Database>()
    single<UserRepository>()
    factory<UserPresenter>()
    viewModel<UserViewModel>()
}
kotlin
@Singleton
class Database

@Singleton
class UserRepository(private val database: Database)

@Factory
class UserPresenter(private val repository: UserRepository)

@KoinViewModel
class UserViewModel(private val repository: UserRepository) : ViewModel()

@Singleton 與 @Single 是等價的。建議優先使用 JSR-330 名稱 @Singleton。

kotlin
import org.koin.dsl.module
import org.koin.core.module.dsl.*

val appModule = module {
    singleOf(::Database)
    singleOf(::UserRepository)
    factoryOf(::UserPresenter)
    viewModelOf(::UserViewModel)
}

你也可以自己撰寫建構函式呼叫,為每個相依性使用 get():

kotlin
val appModule = module {
    single { Database() }
    single { UserRepository(get()) }
    factory { UserPresenter(get()) }
    viewModel { UserViewModel(get()) }
}

使用 Compiler Plugin DSL 與註解時,你完全不需要撰寫 get()。Koin 編譯器外掛程式會讀取建構函式並為你產生呼叫,隨後在建置階段檢查是否已宣告每個相依性。

single 與 factory 如上所述。scoped 需要宣告作用域:請參閱作用域。viewModel 有其專屬頁面:請參閱 ViewModel。worker 則在 WorkManager 中介紹。

Single 還是 factory? ​

當物件沒有個別呼叫者專屬的狀態,且建立成本較高(如資料庫、HTTP 用戶端)時,請使用 single。當每個呼叫者需要自己的執行個體,或是物件持有的狀態不得共用時,請使用 factory。如果某個執行個體的存活時間應比 factory 長,但比整個應用程式短,則你需要作用域。

介面繫結 ​

多數情況下,取用端相依於介面,而非實作。將實作繫結至介面:

kotlin
val dataModule = module {
    single<UserRepositoryImpl>() bind UserRepository::class

    // several types at once
    single<MyServiceImpl>() binds arrayOf(ServiceA::class, ServiceB::class)
}
kotlin
@Singleton
class UserRepositoryImpl(private val database: Database) : UserRepository

繫結是自動的:Koin 會將類別繫結至其所有超型別。若只要繫結其中的部分型別,請將它們列出:

kotlin
@Singleton(binds = [UserRepository::class])
class UserRepositoryImpl(private val database: Database) : UserRepository, Closeable
kotlin
val dataModule = module {
    singleOf(::UserRepositoryImpl) bind UserRepository::class

    // or declare the interface type directly
    single<UserRepository> { UserRepositoryImpl(get()) }
}

取用端隨後請求 UserRepository,即可取得 UserRepositoryImpl 的執行個體。當有兩個定義繫結至同一個型別時,你需要一個限定詞來區分它們。

建構函式參數 ​

Koin 會從容器中解析每個建構函式參數。參數型別決定了解析的方式:

參數解析為詳細資訊
repository: UserRepositoryUserRepository 定義。若缺失則失敗
logger: Logger?若定義存在則解析該定義,否則為 null
heavy: Lazy<HeavyService>在首次存取 heavy.value 時建立注入
loggers: List<Logger>所有繫結至 Logger 的定義進階模式
@Named("local") db: Database帶有該限定詞的定義限定詞
@InjectedParam userId: String呼叫者在解析時傳入的值注入參數
@Property("api_url") url: StringKoin 屬性啟動 Koin

使用 Compiler Plugin DSL 與註解時,僅需根據建構函式簽章即可運作:

kotlin
class SyncService(
    private val repository: UserRepository,
    private val analytics: Analytics?,
    private val uploader: Lazy<Uploader>,
)

val appModule = module {
    single<SyncService>()
}
kotlin
@Singleton
class SyncService(
    private val repository: UserRepository,
    private val analytics: Analytics?,
    private val uploader: Lazy<Uploader>,
)

singleOf(::SyncService) 會透過 get() 解析每個參數。對於可為 null、lazy 或清單 (list) 參數,請使用相符的函式自行撰寫呼叫:

kotlin
val appModule = module {
    single {
        SyncService(
            repository = get(),
            analytics = getOrNull(),
            uploader = inject(),
        )
    }
}

getAll() 會傳回 List,getProperty("key") 會讀取屬性,而 params.get() 則會讀取注入的參數。

非自有的類別 ​

來自程式庫(Room、Retrofit、OkHttp)的類別無法加上註解,且通常由 builder 建立。請使用由 Koin 解析其參數的函式來宣告它們:

kotlin
import org.koin.plugin.module.dsl.create

fun database(context: Context): AppDatabase =
    Room.databaseBuilder(context, AppDatabase::class.java, "app-db").build()

fun topicDao(db: AppDatabase): TopicDao = db.topicDao()

val databaseModule = module {
    single { create(::database) }
    single { create(::topicDao) }
}

create(::function) 會像建構函式一樣解析函式參數,並享有相同的編譯期檢查。函式及其參數上的限定詞註解也能正常運作。

為頂層函式加上註解。@ComponentScan 會像尋找類別一樣找到它:

kotlin
@Singleton
fun database(context: Context): AppDatabase =
    Room.databaseBuilder(context, AppDatabase::class.java, "app-db").build()

@Singleton
fun topicDao(db: AppDatabase): TopicDao = db.topicDao()

或者將 provider 函式組織在 @Module 類別中:

kotlin
@Module
class DatabaseModule {

    @Singleton
    fun database(context: Context): AppDatabase =
        Room.databaseBuilder(context, AppDatabase::class.java, "app-db").build()

    @Singleton
    fun topicDao(db: AppDatabase): TopicDao = db.topicDao()
}
kotlin
val databaseModule = module {
    single {
        Room.databaseBuilder(androidContext(), AppDatabase::class.java, "app-db").build()
    }
    single { get<AppDatabase>().topicDao() }
}

有關在 Android 上完整的 Retrofit、Room 與序列化設定,請參閱 Android 程式庫整合。

預先建立 ​

Koin 會在首次有人請求時建立 single。若要改為在 Koin 啟動時建立它,請將其標記為 createdAtStart:

kotlin
val appModule = module {
    single<ConfigManager>() withOptions {
        createdAtStart()
    }
}
kotlin
@Singleton(createdAtStart = true)
class ConfigManager
kotlin
val appModule = module {
    single(createdAtStart = true) { ConfigManager() }
}

預先建立會在啟動 Koin 的執行緒上執行。在 Android 上,這是在 Application.onCreate() 期間的主執行緒,因此每個預先建立的定義都會增加應用程式啟動時間。請僅將其保留給在第一個畫面出現前必須存在的物件。若要將工作移出啟動階段,請參閱 Lazy 模組。

釋放回呼 ​

onClose 會在執行個體被釋放時執行:對於 single 是在 Koin 停止時,對於 scoped 則是在其作用域關閉時。

kotlin
val appModule = module {
    single<Database>() onClose { it?.close() }
}

註解沒有 onClose 參數。請在 DSL 模組中宣告此定義。

kotlin
val appModule = module {
    single { Database() } onClose { it?.close() }
}

factory 永遠不會呼叫 onClose:因為 Koin 不會保留 factory 執行個體。

覆寫定義 ​

當兩個模組宣告相同的型別時,最後載入的模組優先:

kotlin
val prodModule = module {
    single<ApiService> { ProductionApi() }
}

val testModule = module {
    single<ApiService> { FakeApi() }
}

startKoin {
    modules(prodModule, testModule) // ApiService resolves to FakeApi
}

這在測試中很有用,但若非刻意為之,則可能是錯誤的根源。若要明確指定覆寫,請在全域停用覆寫功能,並明確標記你想要覆寫的項目:

kotlin
val testModule = module {
    single<ApiService> { FakeApi() }.override()
}

startKoin {
    allowOverride(false)
    modules(prodModule, testModule)
}

使用 allowOverride(false) 時,未標記的重複項目會在啟動時失敗。