KSPからコンパイラプラグインへの移行
このガイドでは、Koin AnnotationsプロジェクトをKSPプロセッサ(koin-ksp-compiler)からKoinコンパイラプラグイン(Koin Compiler Plugin)へ移行する手順を説明します。アノテーションを付与したクラスはそのまま維持され、Gradle設定、Koinの起動方法、および一部のインポートのみが変更されます。コンパイラプラグインの概要や仕組みについては、Koin Compiler Plugin を参照してください。
主な変更点
| 項目 | KSPプロセッサ | コンパイラプラグイン |
|---|---|---|
| 処理方式 | KSP(コンパイル前の個別ステップ) | Kotlin K2コンパイラ内部 |
| 生成ファイル | build/generated/ksp 内で確認可能 | なし(コンパイラ内部でコードを生成) |
| KMP設定 | ターゲットごとに1つのKSP設定が必要 | 全ターゲットで1つのプラグイン |
koin-annotations のバージョン | 個別のバージョン(koin-ksp) | koin-core と同じバージョン |
| Koinの起動 | modules(AppModule().module) | startKoin<MyApp>() |
| コンパイル時チェック | KOIN_CONFIG_CHECK オプション | デフォルトで有効(完全なグラフと呼び出し箇所を検証) |
| ステータス | 非推奨(Deprecated) | 活発に開発中(Active development) |
要件
- Kotlin 2.3.20以降(K2コンパイラ)。
- Gradle 8以降。
- Koin 4.2以降。
ステップ1: Kotlinのアップデート
// build.gradle.kts
plugins {
kotlin("jvm") version "2.3.20"
}ステップ2: バージョンカタログのアップデート
変更前(KSP):
[versions]
koin = "4.0.0"
koin-ksp = "2.0.0"
ksp = "2.0.0-1.0.22"
[libraries]
koin-core = { module = "io.insert-koin:koin-core", version.ref = "koin" }
koin-annotations = { module = "io.insert-koin:koin-annotations", version.ref = "koin-ksp" }
koin-ksp-compiler = { module = "io.insert-koin:koin-ksp-compiler", version.ref = "koin-ksp" }
[plugins]
ksp = { id = "com.google.devtools.ksp", version.ref = "ksp" }変更後(コンパイラプラグイン):
[versions]
koin = "4.2.0"
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-annotations はメインのKoinプロジェクトの一部となり、koin-core と同じバージョンを使用するようになりました。最新のプラグインバージョンについては Compiler Plugin Setup を確認してください。
ステップ3: ビルド設定のアップデート
変更前(KSP):
plugins {
alias(libs.plugins.ksp)
}
dependencies {
implementation(libs.koin.core)
implementation(libs.koin.annotations)
ksp(libs.koin.ksp.compiler)
}
ksp {
arg("KOIN_CONFIG_CHECK", "true")
}変更後(コンパイラプラグイン):
plugins {
alias(libs.plugins.koin.compiler)
}
dependencies {
implementation(libs.koin.core)
implementation(libs.koin.annotations)
}
// 任意
koinCompiler {
userLogs = true // 検出されたコンポーネントをログ出力
}ksp { } ブロックは削除してください。コンパイル時チェックはデフォルトで有効になっています。すべてのプラグインオプションについては Compiler Plugin Options を参照してください。
Kotlin Multiplatform
KSPを使用している場合、ターゲットごとにプロセッサ設定が必要でした。
dependencies {
add("kspAndroid", "io.insert-koin:koin-ksp-compiler:$koin_ksp_version")
add("kspIosX64", "io.insert-koin:koin-ksp-compiler:$koin_ksp_version")
add("kspIosArm64", "io.insert-koin:koin-ksp-compiler:$koin_ksp_version")
add("kspIosSimulatorArm64", "io.insert-koin:koin-ksp-compiler:$koin_ksp_version")
}コンパイラプラグインでは、共有モジュールにプラグインを1度適用するだけで済み、すべての ksp... エントリを削除できます。
// shared/build.gradle.kts
plugins {
kotlin("multiplatform")
alias(libs.plugins.koin.compiler)
}
kotlin {
sourceSets {
commonMain.dependencies {
implementation(libs.koin.core)
implementation(libs.koin.annotations)
}
}
}ステップ4: Koinの起動方法のアップデート
KSPは各 @Module クラスに対して .module 拡張関数を生成していました。コンパイラプラグインにはそのような拡張関数はありません。代わりに @KoinApplication クラスを宣言し、型付けされたAPIを使って起動します。
変更前(KSP):
import org.koin.ksp.generated.*
@Module
@ComponentScan("com.myapp")
class AppModule
fun main() {
startKoin {
modules(AppModule().module)
}
}変更後(コンパイラプラグイン):
import org.koin.plugin.module.dsl.startKoin
@Module
@ComponentScan("com.myapp")
class AppModule
@KoinApplication(modules = [AppModule::class])
class MyApp
fun main() {
startKoin<MyApp>()
}Androidでは、ラムダ式内で通常のオプションを渡します。
@KoinApplication(modules = [AppModule::class])
class MyApp
class MyApplication : Application() {
override fun onCreate() {
super.onCreate()
startKoin<MyApp> {
androidContext(this@MyApplication)
}
}
}その他の型付けされたAPIとして、既存の startKoin { } やテストルール内で使用できる koinApplication<T>()、koinConfiguration<T>()、withConfiguration<T>() があります。単一のモジュールクラスをロードするには、通常の startKoin { } 内で module<AppModule>() を使用します。詳細は Starting Koin を参照してください。
ステップ5: インポートのアップデート
@KoinViewModel はコアアノテーションパッケージに移動しました。
// 変更前(KSP)
import org.koin.android.annotation.KoinViewModel
// 変更後(コンパイラプラグイン)
import org.koin.core.annotation.KoinViewModelimport org.koin.ksp.generated.* はすべて削除してください。
ステップ6: クリーンとリビルド
KSPによって生成されたファイルを削除し、リビルドを実行します。
rm -rf build/generated/ksp
./gradlew clean build初回のビルドでは完全なコンパイル時チェックが実行されます。KSPでは報告されなかった不足している定義がある場合、ビルドが失敗するようになります。エラーメッセージや @Provided については Compile-Time Safety を参照してください。
変更されない点
アノテーションを付与したクラスを変更する必要はありません。
@Singleton
class UserRepository(private val database: Database)
@Factory
class GetUserUseCase(private val repository: UserRepository)
@KoinViewModel
class UserViewModel(private val useCase: GetUserUseCase) : ViewModel()すべてのアノテーションは Annotations Reference に記載されています。
移行後に利用可能になる機能
以下の機能を利用するにはコンパイラプラグインが必要です。
- トップレベル関数:
@Singleton fun database(): Databaseは、クラスと同様に@ComponentScanによって検出されます(Definitions を参照)。 - モジュールの自動検出: 任意のGradleモジュール内で
@Configurationが付けられたモジュールは、明示的にリストアップすることなく@KoinApplicationによって読み込まれます。 - コンフィグレーションラベル:
@Configuration("test")と@KoinApplication(configurations = ["test"])を組み合わせることで、そのラベルが付いたモジュールのみを読み込めます(Modules を参照)。 - コンパイラプラグインDSL: DSLモジュールも併用している場合、コンパイラプラグインDSLに切り替えることができます。
| Constructor / Classic DSL | Compiler Plugin DSL |
|---|---|
singleOf(::MyService) | single<MyService>() |
factoryOf(::MyRepository) | factory<MyRepository>() |
viewModelOf(::MyViewModel) | viewModel<MyViewModel>() |
scopedOf(::MyScoped) | scoped<MyScoped>() |
workerOf(::MyWorker) | worker<MyWorker>() |
single { build(get()) } | single { create(::build) } |
コンパイラプラグインDSLは org.koin.plugin.module.dsl にあります。Constructor DSLは引き続き org.koin.core.module.dsl に、Classic DSLは org.koin.dsl に残ります。どちらも引き続き動作し、プラグインによるチェックも行われるため、移行は必須ではありません。
トラブルシューティング
KSP削除後にビルドが失敗する
古い生成コードがクラスパスに残っている可能性があります。./gradlew clean を実行し、build/generated/ksp を削除した上で、IDEのキャッシュを破棄(Invalidate Caches)してリビルドしてください。
アノテーション付きクラスが検出されない
プラグインのログを有効にして、どのクラスが検出されているかを確認してください。
koinCompiler {
userLogs = true
}@ComponentScan に指定されているパッケージが、クラスのパッケージと一致しているか確認してください。
ランタイム時に依存関係が見つからない
- そのモジュールが
@KoinApplication(modules = [...])にリストされているか、または@Configurationが付与されているか確認してください。 @ComponentScanのパッケージ指定を確認してください。- Koinの外部で作成された型の場合は、
@Providedをマークしてください(Compile-Time Safety を参照)。
チェックリスト
- [ ] Kotlinを2.3.20以降にアップデート
- [ ] Koinを4.2.0以降にアップデート
- [ ] KSPプラグインを削除
- [ ]
koin-ksp-compilerの依存関係とksp { }ブロックを削除 - [ ]
koin-annotationsにメインのKoinバージョンを使用(io.insert-koin:koin-annotations:$koin_version) - [ ] Koinコンパイラプラグインを適用(
io.insert-koin.compiler.plugin) - [ ]
@KoinViewModelのインポートをorg.koin.core.annotationに変更 - [ ]
@KoinApplicationクラスを作成し、modules(X().module)をstartKoin<MyApp>()に置き換え - [ ]
import org.koin.ksp.generated.*を削除 - [ ] (任意)DSLモジュールを
org.koin.plugin.module.dsl.*およびsingle<X>()に切り替え - [ ] クリーンとリビルドを実行(
rm -rf build/generated/ksp && ./gradlew clean build)
関連情報
- Compiler Plugin Setup: プラグインの導入方法とバージョンの選定。
- Compile-Time Safety: プラグインが検証する内容とエラーコード。
- Starting Koin:
startKoin<T>()およびその他の型付きAPI。 - Compiler Plugin Options: 各種Gradleオプション。
- KSP Processor Setup: 参考用の非推奨KSPセットアップガイド。
