編譯器外掛程式設定
本頁面介紹如何安裝 Koin Compiler Plugin,這是一個支援 Compiler Plugin DSL 與註解背後的 Kotlin 編譯器外掛程式。內容涵蓋單模組、多模組與 Kotlin Multiplatform 組建、主要選項以及設定問題。若要了解此外掛程式的功能,請參閱 Koin Compiler Plugin。Koin 程式庫本身列於 Gradle Setup。
需求
- Kotlin 2.3.20 或更新版本(K2 編譯器)。
- Koin 4.2.0 或更新版本。
- Gradle 8 或更新版本。
目前版本:
此外掛程式擁有自己的版本,與 Koin 分開。koin-annotations 則遵循 Koin 的版本。
安裝
1. 宣告外掛程式
在 gradle/libs.versions.toml 中:
[versions]
koin = "4.2.2"
koin-plugin = "1.2.1"
[libraries]
koin-core = { module = "io.insert-koin:koin-core", version.ref = "koin" }
koin-annotations = { module = "io.insert-koin:koin-annotations", version.ref = "koin" }
[plugins]
koin-compiler = { id = "io.insert-koin.compiler.plugin", version.ref = "koin-plugin" }若你使用 Koin BOM,請自程式庫中移除 version.ref。該外掛程式不屬於 BOM 的一部分,並保留其自己的版本。
2. 外掛儲存庫
此外掛程式已發佈至 Maven Central 與 Gradle Plugin Portal。在 settings.gradle.kts 中:
pluginManagement {
repositories {
mavenCentral()
gradlePluginPortal()
}
}3. 套用外掛程式
在每個宣告 Koin 定義的 Gradle 模組之 build.gradle.kts 中:
plugins {
alias(libs.plugins.koin.compiler)
}
dependencies {
implementation(libs.koin.core) // 或 koin-android, koin-ktor, ...
implementation(libs.koin.annotations) // 用於註解,以及 DSL 風格中的 @Named 或 @InjectedParam
}Compiler Plugin DSL(single<T>()、factory<T>()、viewModel<T>())隨附於 Koin 程式庫中的 org.koin.plugin.module.dsl 套件。僅當你使用註解(包含 DSL 風格的參數註解)時,才需要 koin-annotations。
TIP
@KoinViewModel 與 @KoinWorker 需要在類別路徑中包含其執行階段程式庫:koin-core-viewmodel(包含在 koin-android 與 koin-compose-viewmodel 中)以及 koin-androidx-workmanager。若缺少其中任一項,組建將會失敗,並顯示指出該構件名稱的錯誤。
4. 檢查是否正常運作
為單次組建開啟外掛程式記錄:
koinCompiler {
userLogs = true
}組建輸出會列出外掛程式偵測到的每個定義。檢查完成後請再次將其關閉。接著按照 Starting Koin 中的說明,使用 startKoin { },或是針對註解使用 startKoin<MyApp>() 來啟動 Koin。
多模組專案
在每個宣告定義的 Gradle 模組中套用此外掛程式,而不僅僅是在 app 模組中:
// feature/build.gradle.kts
plugins {
alias(libs.plugins.koin.compiler)
}
dependencies {
implementation(libs.koin.core)
implementation(libs.koin.annotations)
}// app/build.gradle.kts
plugins {
alias(libs.plugins.koin.compiler)
}
dependencies {
implementation(project(":feature"))
implementation(libs.koin.android)
implementation(libs.koin.annotations)
}每個使用此外掛程式編譯的模組都會攜帶有關其定義的元資料。app 模組會讀取該元資料,以便在 startKoin 時檢查完整的關係圖。未套用此外掛程式的程式庫模組對這些檢查而言是隱形的。關於如何跨 Gradle 模組組合模組(includes、@Configuration),請參閱 Modules 與 Multi-Module Android Apps。
Kotlin Multiplatform
在共用模組(shared module)上套用一次此外掛程式,並將程式庫新增至 commonMain。不需要針對各個目標分別設定:
// shared/build.gradle.kts
plugins {
alias(libs.plugins.kotlin.multiplatform)
alias(libs.plugins.koin.compiler)
}
kotlin {
sourceSets {
commonMain.dependencies {
implementation(libs.koin.core)
implementation(libs.koin.annotations)
}
}
}專案結構請參閱 Kotlin Multiplatform Setup。
選項
koinCompiler 區塊用於設定此外掛程式。預設值適用於大多數專案:
koinCompiler {
compileSafety = true // 在組建時期驗證圖形
skipDefaultValues = true // 使用 Kotlin 預設值而不是進行注入
userLogs = false // 記錄偵測到的定義
}每個選項(包括 strictSafety、unsafeDslChecks、logSeverity 與 debugLogs)均在 Compiler Plugin Options 中說明。
Kotlin 版本相容性
每個外掛程式版本都會在一系列 Kotlin 版本上進行驗證:
| Kotlin | Koin Compiler Plugin |
|---|---|
| 2.3.20, 2.4.0, 2.4.10 | 1.2.0+ |
| 2.4.20 | 1.2.1+ |
若使用的 Kotlin 版本未列於清單中,外掛程式會印出警告訊息,且組建仍會繼續執行。
WARNING
在 Kotlin 2.4.20 上,外掛程式 1.2.0 會在 IR 產生期間因 NoSuchMethodError 而失敗。請使用 1.2.1 或更新版本。
疑難排解
找不到外掛程式
Gradle 無法解析 io.insert-koin.compiler.plugin。請檢查 settings.gradle.kts 中的 pluginManagement.repositories 是否包含 mavenCentral() 與 gradlePluginPortal()。
執行階段發生 NotImplementedError
single<T>()、factory<T>() 與 create(::T) 是由外掛程式替換的占位符號。若未將外掛程式套用至包含它們的 Gradle 模組,程式碼雖然可以編譯,但在建立模組時會擲回 NotImplementedError。請將此外掛程式套用至該模組。
錯誤的匯入
Compiler Plugin DSL 與 Constructor DSL 在不同的套件中擁有相同名稱的函式:
// Compiler Plugin DSL
import org.koin.plugin.module.dsl.*
// Constructor DSL: singleOf, factoryOf, viewModelOf
import org.koin.core.module.dsl.*
// 兩者皆有
import org.koin.dsl.module重構後出現過期結果
與其他 Kotlin IR 外掛程式(例如 Compose 編譯器)類似,Koin Compiler Plugin 在增量編譯時可能會產生過期的結果。常見現象:
- 出現不應出現的編譯安全錯誤,或是在移除定義後未顯示任何錯誤。
- 重構後在執行階段發生
NoSuchMethodError或ClassNotFoundException。
通常發生在以下變更之後:
- 修改類別上的註解(從
@Singleton變更為@Factory、新增或移除@Named)。 - 在
@ComponentScan掃描的套件之間移動類別。 - 變更模組的
includes或@Configuration標籤。 - 在另一個模組所相依的程式庫模組中新增或移除定義。
請執行清理組建:./gradlew clean build,或在 Android Studio 中點選 Build > Clean Project,接著點選 Build > Rebuild Project。
對於 module { } Lambda 運算式內部的變更,外掛程式會為包含入口點(startKoin、koinApplication、@KoinApplication)的模組開啟 strictSafety。它會在每次組建這些模組時重新執行完整的圖形檢查。請參閱 strictSafety。
回報跨模組缺少相依性
若程式庫模組確實宣告了某個相依項,但外掛程式卻回報缺少該相依項:
- 同樣地將外掛程式套用至該程式庫模組。若沒有外掛程式,該程式庫將不會攜帶任何元資料。
- 確保在組建使用該程式庫的模組之前,該程式庫已經完成組建。通常
implementation(project(":lib"))會自動處理此順序。 - 首次將外掛程式新增至程式庫後,請執行一次清理組建。
- 請使用外掛程式 1.2.1 或更新版本。早期版本遺漏了相距兩個或更多
implementation層級的定義,且會跨模組合併@Named提供者。若你先前因為錯誤的KOIN-D001報錯而關閉了compileSafety,請重新將其開啟。
遷移至 Compiler Plugin
- 從 Constructor 或 Classic DSL:套用外掛程式。你現有的
singleOf(::T)定義與get()呼叫無須任何修改即可在組建時期進行檢查。接著你可以逐個模組將其替換為single<T>()。請參閱 Choosing your style。 - 從 KSP 處理器:移除 KSP 與
koin-ksp-compiler,套用外掛程式,並將產生的.module擴充功能替換為startKoin<MyApp>()。你的註解將維持不變。請參閱 Migrating from KSP。
相關內容
- Koin Compiler Plugin:外掛程式的功能與運作原理。
- Compiler Plugin Options:所有 Gradle 選項。
- Compile-Time Safety:所有檢查項目與錯誤代碼。
- Gradle Setup:Koin 程式庫與 BOM。
- Starting Koin:型別化的啟動 API,例如
startKoin<MyApp>()。
