Hiltからの移行
このガイドでは、Gradle、Application クラス、モジュール、バインディング、ViewModel、エントリーポイント、クォリファイア、Compose、テストと、ステップごとにAndroidアプリをDagger HiltからKoinへと移行します。各Koinサンプルには3つのKoinスタイルが用意されています。どれを選ぶべきか迷った場合は、Choosing your style(スタイルの選択)をお読みください。2つのフレームワークの比較については、Koin vs Hilt を参照してください。
NOTE
実際のアプリでの完全な移行事例については、Migrating Now in Android to Koin をお読みください。30個のGradleモジュールを持つGoogleのサンプルアプリをHiltからKoin Annotationsへと移行した事例です。
概念のマッピング
| Hilt | Compiler Plugin DSL | Annotations | Constructor / Classic DSL |
|---|---|---|---|
@HiltAndroidApp | Application.onCreate() 内の startKoin { } | @KoinApplication + startKoin<T>() | Application.onCreate() 内の startKoin { } |
@AndroidEntryPoint | 不要: by inject(), by viewModel() | 不要 | 不要 |
@Inject constructor | single<T>() / factory<T>() | クラスに @Singleton / @Factory | singleOf(::T) / factoryOf(::T) |
@Module + @InstallIn | module { } | @Module + @ComponentScan | module { } |
@Provides | single { create(::fn) } | 関数に @Singleton / @Factory | single { ... } |
@Binds | bind Interface::class | 自動(スーパータイプ)または binds = [...] | bind Interface::class |
@Singleton | single | @Singleton / @Single | single |
@HiltViewModel | viewModel<T>() | @KoinViewModel | viewModelOf(::T) |
@HiltWorker | worker<T>() | @KoinWorker | workerOf(::T) |
@Named, カスタム @Qualifier | named("x"), パラメータに @Named | @Named, カスタム @Qualifier | named("x") |
@ApplicationContext | Context パラメータ(androidContext() により提供) | 同様 | androidContext() |
@AssistedInject | 注入パラメータ(Injected parameters) | @InjectedParam | 注入パラメータ(Injected parameters) |
自作クラス内の @Inject フィールド | コンストラクタパラメータ | コンストラクタパラメータ | コンストラクタパラメータ |
@EntryPoint(Hiltが注入できないフレームワーククラス) | そのエントリーポイントでのみ KoinComponent | 同様 | 同様 |
@HiltAndroidTest | KoinTestRule | KoinTestRule | KoinTestRule |
スコープのマッピング
| Hilt | Koin DSL | Annotations | ライフタイム |
|---|---|---|---|
@Singleton (SingletonComponent) | single | @Singleton | アプリケーション |
@ActivityRetainedScoped | activityRetainedScope { } | @ActivityRetainedScope | 構成変更(Configuration changes)をまたいで生存 |
@ViewModelScoped | viewModelScope { } | @ViewModelScope | ViewModel |
@ActivityScoped | activityScope { } | @ActivityScope | Activity |
@FragmentScoped | fragmentScope { } | @FragmentScope | Fragment |
スコープDSLとアノテーションの詳細は、Android Scopes で解説されています。
ステップ 1: Gradle
Hiltプラグイン、hilt-android、および hilt-compiler(kaptまたはKSP)を削除します。その後、Koinを追加します:
dependencies {
implementation(platform("io.insert-koin:koin-bom:$koin_version"))
implementation("io.insert-koin:koin-android")
implementation("io.insert-koin:koin-androidx-compose") // Composeを使用する場合
}Compiler Plugin DSLまたはアノテーションを使用する場合は、Koin Compiler Plugin も適用してください。これはKotlinコンパイラ内で動作し、KoinにおけるkaptやKSPの代わりとなります。アーティファクトの完全な一覧は Gradle Setup にあります。
ステップ 2: Application クラス
Hilt:
@HiltAndroidApp
class MyApplication : Application()Koin:
class MyApplication : Application() {
override fun onCreate() {
super.onCreate()
startKoin {
androidLogger()
androidContext(this@MyApplication)
modules(appModule)
}
}
}import org.koin.plugin.module.dsl.startKoin
@KoinApplication
class MyApplication : Application() {
override fun onCreate() {
super.onCreate()
startKoin<MyApplication> {
androidLogger()
androidContext(this@MyApplication)
}
}
}@KoinApplication は、@Configuration がタグ付けされたすべてのモジュールを読み込みます。モジュールを明示的に指定する場合は、@KoinApplication(modules = [AppModule::class]) を使用します。
class MyApplication : Application() {
override fun onCreate() {
super.onCreate()
startKoin {
androidLogger()
androidContext(this@MyApplication)
modules(appModule)
}
}
}androidContext() は、すべての定義で Context を利用できるようにします。Starting Koin on Android を参照してください。
ステップ 3: モジュールと @Provides
Hilt:
@Module
@InstallIn(SingletonComponent::class)
object NetworkModule {
@Provides
@Singleton
fun provideOkHttpClient(): OkHttpClient = OkHttpClient.Builder().build()
@Provides
@Singleton
fun provideApiService(client: OkHttpClient): ApiService =
Retrofit.Builder()
.baseUrl("https://api.example.com")
.client(client)
.build()
.create(ApiService::class.java)
}Koin:
import org.koin.plugin.module.dsl.create
fun okHttpClient(): OkHttpClient = OkHttpClient.Builder().build()
fun apiService(client: OkHttpClient): ApiService =
Retrofit.Builder()
.baseUrl("https://api.example.com")
.client(client)
.build()
.create(ApiService::class.java)
val networkModule = module {
single { create(::okHttpClient) }
single { create(::apiService) }
}@Module
class NetworkModule {
@Singleton
fun okHttpClient(): OkHttpClient = OkHttpClient.Builder().build()
@Singleton
fun apiService(client: OkHttpClient): ApiService =
Retrofit.Builder()
.baseUrl("https://api.example.com")
.client(client)
.build()
.create(ApiService::class.java)
}val networkModule = module {
single { OkHttpClient.Builder().build() }
single {
Retrofit.Builder()
.baseUrl("https://api.example.com")
.client(get())
.build()
.create(ApiService::class.java)
}
}@InstallIn は存在しません。定義のライフタイムは、インストールされるコンポーネントからではなく、その定義の型(single、factory、scoped)によって決まります。@Inject constructor を持つクラスは、single<T>() / factory<T>()、クラスへのアノテーション、または singleOf(::T) に置き換わります。ライブラリオブジェクトの詳細は Definitions を参照してください。
ステップ 4: インターフェースのバインディング
Hilt:
@Module
@InstallIn(SingletonComponent::class)
abstract class DataModule {
@Binds
@Singleton
abstract fun bindUserRepository(impl: UserRepositoryImpl): UserRepository
}Koin:
val dataModule = module {
single<UserRepositoryImpl>() bind UserRepository::class
}@Singleton
class UserRepositoryImpl(private val api: ApiService) : UserRepositoryクラスはそのすべてのスーパータイプにバインドされます。一部のみをバインドする場合は、@Singleton(binds = [UserRepository::class]) を使用します。
val dataModule = module {
singleOf(::UserRepositoryImpl) bind UserRepository::class
}ステップ 5: ViewModel
Hilt:
@HiltViewModel
class UserViewModel @Inject constructor(
private val repository: UserRepository,
private val savedStateHandle: SavedStateHandle,
) : ViewModel()Koin:
class UserViewModel(
private val repository: UserRepository,
private val savedStateHandle: SavedStateHandle,
) : ViewModel()
val appModule = module {
viewModel<UserViewModel>()
}@KoinViewModel
class UserViewModel(
private val repository: UserRepository,
private val savedStateHandle: SavedStateHandle,
) : ViewModel()class UserViewModel(
private val repository: UserRepository,
private val savedStateHandle: SavedStateHandle,
) : ViewModel()
val appModule = module {
viewModelOf(::UserViewModel)
}KoinはViewModelの定義に SavedStateHandle を提供します。ActivityやFragmentでは、by viewModels() を by viewModel() に置き換えてください。Composeでは、hiltViewModel() を koinViewModel() に置き換えます。Android ViewModel を参照してください。
ステップ 6: Activity、Fragment、その他のエントリーポイント
Hilt:
@AndroidEntryPoint
class MainActivity : ComponentActivity() {
@Inject lateinit var analytics: Analytics
}Koin:
class MainActivity : ComponentActivity() {
private val analytics: Analytics by inject()
}@AndroidEntryPoint を削除します。フレームワークによって生成されるActivity、Fragment、その他のAndroidコンポーネントでは、@Inject lateinit var のフィールドは by inject()(遅延)または get()(即時)に置き換わります。これはどのスタイルでも同様です。ServiceやBroadcastReceiverなどの他のコンポーネントについては、Entry Points で解説されています。
自身で作成したクラス(リポジトリ、サービス、ユースケース、ViewModel)では、@Inject フィールドをコンストラクタパラメータに移動し、ステップ 3 のようにクラスを宣言します。これらのクラスが get() や by inject() を呼び出すことはありません:
// Hilt: 自作クラスでのフィールドインジェクション
class SyncService @Inject constructor() {
@Inject lateinit var repository: UserRepository
}
// Koin: コンストラクタインジェクション
class SyncService(private val repository: UserRepository)Hiltの @EntryPoint は、ContentProvider やライブラリのコールバックなど、Hiltが注入できないフレームワーククラスのために存在します。そのようなエントリーポイントでのみ KoinComponent を実装し、by inject() を呼び出します。アプリクラス内の @Inject フィールドを置き換えるために KoinComponent を使用しないでください。
ステップ 7: クォリファイア
Hilt:
@Qualifier
@Retention(AnnotationRetention.BINARY)
annotation class IoDispatcher
@Provides
@IoDispatcher
fun provideIoDispatcher(): CoroutineDispatcher = Dispatchers.IO
class SyncRepository @Inject constructor(
@IoDispatcher private val dispatcher: CoroutineDispatcher,
)Koin:
import org.koin.core.annotation.Named
class SyncRepository(
@Named("io") private val dispatcher: CoroutineDispatcher,
)
val dispatcherModule = module {
single<CoroutineDispatcher>(named("io")) { Dispatchers.IO }
single<SyncRepository>()
}既存のクォリファイアアノテーションをそのまま保持できます。Koinは @Qualifier(Koin独自、jakarta.inject、または javax.inject)が付与されたカスタムアノテーションを読み取ります:
import javax.inject.Qualifier
@Qualifier
@Retention(AnnotationRetention.BINARY)
annotation class IoDispatcher
@Module
class DispatcherModule {
@Singleton
@IoDispatcher
fun ioDispatcher(): CoroutineDispatcher = Dispatchers.IO
}
@Singleton
class SyncRepository(
@IoDispatcher private val dispatcher: CoroutineDispatcher,
)val dispatcherModule = module {
single<CoroutineDispatcher>(named("io")) { Dispatchers.IO }
single { SyncRepository(get(named("io"))) }
}型クォリファイア(named<IoDispatcher>())やすべてのオプションについては、Qualifiers に記載されています。Hiltの @ApplicationContext に対応するクォリファイアは不要です。Context パラメータは androidContext() に渡されたコンテキストを受け取ります。
ステップ 8: Compose
HiltではComposableからViewModel以外の依存関係にアクセスするためにエントリーポイントが必要ですが、Koinでは直接解決できます:
@Composable
fun UserScreen(viewModel: UserViewModel = koinViewModel()) {
val analytics: Analytics = koinInject()
}Koin for Compose を参照してください。
ステップ 9: テスト
Hilt:
@HiltAndroidTest
class UserRepositoryTest {
@get:Rule
val hiltRule = HiltAndroidRule(this)
@Inject lateinit var repository: UserRepository
@Before
fun init() = hiltRule.inject()
}Koin:
class UserRepositoryTest : KoinTest {
@get:Rule
val koinTestRule = KoinTestRule.create {
modules(appModule, testModule)
}
private val repository: UserRepository by inject()
}Hiltの @TestInstallIn や @UninstallModules は、本番モジュールの後に読み込まれるテストモジュールに置き換わります。HiltTestApplication とHiltテストランナーを削除してください。Unit Testing および Android Instrumented Testing を参照してください。
@Inject を使用した段階的な移行
アノテーションを使用する場合、Compiler PluginはJSR-330アノテーションを読み取ります。@ComponentScan の対象パッケージ内では、@Inject constructor を持つクラスはファクトリになり、@Singleton(jakarta.inject または javax.inject)が付与されたクラスはシングルになります。これらのクラスを変更せずに維持したまま、Gradleモジュール単位で段階的に移行できます。JSR-330 Annotations を参照してください。
マルチモジュールプロジェクト
各Gradleモジュールは独自のKoinモジュールを宣言し、アプリモジュールが startKoin 内ですべてを読み込みます。設定すべきコンポーネント階層はなく、モジュール間アクセス用の @EntryPoint も不要です。:feature:home 内の定義は、アプリによって読み込まれた任意の定義を使用できます。
アノテーションを使用する場合、各機能モジュールクラスに @Module、@ComponentScan、@Configuration を付与します。アプリモジュールの @KoinApplication は、明示的に列挙することなくそれらを自動検出します。
モジュールの構成、可視性、機能モジュールについては、Multi-Module Apps で解説されています。
よくあるパターン
アシステッドインジェクション(Assisted injection)
Hiltの @AssistedInject と @AssistedFactory は、注入パラメータ(Injected parameters)に置き換わります。呼び出し元が実行時の値を渡します:
class UserDetailViewModel(
@InjectedParam private val userId: String,
private val repository: UserRepository,
) : ViewModel()
val appModule = module {
viewModel<UserDetailViewModel>()
}@KoinViewModel
class UserDetailViewModel(
@InjectedParam private val userId: String,
private val repository: UserRepository,
) : ViewModel()class UserDetailViewModel(
private val userId: String,
private val repository: UserRepository,
) : ViewModel()
val appModule = module {
viewModel { (userId: String) -> UserDetailViewModel(userId, get()) }
}val viewModel: UserDetailViewModel by viewModel { parametersOf("user-42") }Injected Parameters を参照してください。
Lazy と Provider
dagger.Lazy<T>: KotlinのLazy<T>コンストラクタパラメータを使用するか、Androidエントリーポイントでby inject()を使用します(Injection を参照)。Provider<T>: 自作クラスからの呼び出しごとに新しいインスタンスを生成するには、Advanced Patterns のプロバイダパターンを使用します。
WorkManager
@HiltWorker ワーカーは worker 定義に置き換わり、HiltWorkerFactory は startKoin 内の workManagerFactory() に置き換わります。WorkManager を参照してください。
チェックリスト
- [ ] Gradle: Hiltプラグイン、
hilt-android、hilt-compilerを削除する。Koinを追加し、使用する場合は Compiler Plugin も追加する。他に必要がなければkaptを削除する。 - [ ] Application:
@HiltAndroidAppを削除し、onCreate()でandroidContext()を指定してKoinを開始(startKoin)する。 - [ ] モジュール:
@Module/@InstallIn/@Provides/@BindsをKoinモジュールに変換する。 - [ ] ViewModel:
@HiltViewModelを削除し、ViewModelを宣言して、by viewModel()/koinViewModel()を使用する。 - [ ] エントリーポイント:
@AndroidEntryPointを削除し、Androidコンポーネントではby inject()を使用する。自作クラスの@Injectフィールドはコンストラクタパラメータに移動する。Koinが生成できないフレームワーククラスでのみ@EntryPointをKoinComponentに置き換える。 - [ ] クォリファイア: カスタム
@Qualifierアノテーションを維持する(アノテーションスタイル)、またはnamed()に切り替える。 - [ ] ワーカー:
@HiltWorkerとHiltWorkerFactoryを置き換える。 - [ ] テスト:
@HiltAndroidTest、HiltAndroidRule、Hiltテストランナーを削除し、KoinTestRuleを使用する。 - [ ] ビルド: Compiler Plugin を使用している場合、ビルドが成功すればグラフが完全であることを意味する。使用していない場合は、verify() テストを追加する。
- [ ] 実行: アプリとテストスイートを実行する。
トラブルシューティング
NoDefinitionFoundException
リクエストされた型の定義がKoin内に見つかりません。その定義を宣言しているモジュールが startKoin で読み込まれているか(または @Configuration で検出されているか)、およびリクエストされた型が宣言またはバインドされた型と一致しているかを確認してください。@Inject constructor のみを持っていてHiltによって注入されていたクラスも、@ComponentScan がJSR-330アノテーション経由で検出しない限り、Koinの定義が必要です。
同一の型に対して2つの定義がある場合に誤ったインスタンスが返される
Hiltではクォリファイアの指定漏れはビルドエラーになります。Koinでは、allowOverride(false) を指定してKoinを開始しない限り、最後に読み込まれた定義が優先されます。両方の定義と注入ポイントに クォリファイア を追加してください。
循環依存
2つのクラスが相互に依存しています。循環を解消するようにリファクタリングするか、片方を Lazy<T> パラメータにして遅延初期化してください。Compiler Pluginはビルド時に循環依存を報告します。詳細は Troubleshooting を参照してください。
関連情報
- Koin vs Hilt: 2つのフレームワークの違い。
- JSR-330 Annotations: 移行中に
@Injectと@Singletonを維持する方法。 - Starting Koin on Android:
startKoin、androidContext()、ロギングについて。 - Android Scopes: Activity、Fragment、ViewModelのスコープ。
- Unit Testing: Hiltテストルールの置き換え。
- Compile-Time Safety: Compiler Plugin が検証する内容。
