從 Hilt 遷移
本指南將逐步帶領你將 Android 應用程式從 Dagger Hilt 遷移至 Koin:Gradle、Application 類別、模組、繫結 (bindings)、ViewModel、入口點、限定詞、Compose 以及測試。每個 Koin 範例均提供三種 Koin 風格;若你不確定該選擇哪一種,請閱讀選擇你的風格。關於這兩種架構的比較,請參閱 Koin 與 Hilt 比較。
NOTE
若要參考完整的實際遷移案例,請閱讀 Migrating Now in Android to Koin:Google 擁有 30 個 Gradle 模組的範例應用程式,從 Hilt 遷移至 Koin Annotations。
概念對應
| Hilt | 編譯器外掛程式 DSL | 註解 | 建構函式 / 傳統 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 | 注入參數 | @InjectedParam | 注入參數 |
自有類別中的 @Inject 欄位 | 建構函式參數 | 建構函式參數 | 建構函式參數 |
@EntryPoint(Hilt 無法注入的架構類別) | 僅在該入口點使用 KoinComponent | 相同 | 相同 |
@HiltAndroidTest | KoinTestRule | KoinTestRule | KoinTestRule |
作用域對應
| Hilt | Koin DSL | 註解 | 生命週期 |
|---|---|---|---|
@Singleton (SingletonComponent) | single | @Singleton | 應用程式 |
@ActivityRetainedScoped | activityRetainedScope { } | @ActivityRetainedScope | 在組態變更後保留 |
@ViewModelScoped | viewModelScope { } | @ViewModelScope | ViewModel |
@ActivityScoped | activityScope { } | @ActivityScope | Activity |
@FragmentScoped | fragmentScope { } | @FragmentScope | Fragment |
作用域 DSL 與註解已在 Android 作用域中詳細說明。
步驟 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
}若要使用編譯器外掛程式 DSL 或註解,還需套用 Koin 編譯器外掛程式。它在 Kotlin 編譯器內部執行,並取代 Koin 原本所需的 kapt 或 KSP。產物的完整清單請參閱 Gradle 設定。
步驟 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。請參閱在 Android 上啟動 Koin。
步驟 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)。關於程式庫物件的更多資訊,請參閱定義。
步驟 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 會將 SavedStateHandle 提供給 ViewModel 定義。在 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 以及其他元件請參閱入口點。
在你自己的類別中(repository、service、use case、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 是為了處理 Hilt 無法直接注入的架構類別(例如 ContentProvider 或程式庫回呼)。僅在此類入口點上實作 KoinComponent 並呼叫 by inject()。請勿使用 KoinComponent 來取代應用程式自有類別中的 @Inject 欄位。
步驟 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>())與所有其他選項請參閱限定詞。Hilt 的 @ApplicationContext 不需要限定詞:Context 參數會自動接收傳遞給 androidContext() 的 context。
步驟 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 測試執行器。請參閱單元測試與 Android 插樁測試。
使用 @Inject 漸進式遷移
搭配註解使用時,編譯器外掛程式會讀取 JSR-330 註解:在 @ComponentScan 涵蓋的套件中,帶有 @Inject constructor 的類別會成為 factory,而標記有 @Singleton(來自 jakarta.inject 或 javax.inject)的類別則會成為 single。你可以保持這些類別不變,逐一遷移各個 Gradle 模組。請參閱 JSR-330 註解。
多模組專案
每個 Gradle 模組宣告自己的 Koin 模組,而應用程式模組在 startKoin 中載入所有這些模組。不需要配置元件階層,也不需要用於跨模組存取的 @EntryPoint::feature:home 中的定義可以使用應用程式載入的任何定義。
搭配註解時,請在每個功能模組類別上加上 @Module、@ComponentScan 與 @Configuration 標籤。應用程式模組中的 @KoinApplication 無需手動列出即可自動找到它們。
模組組織、可見性與功能模組已在多模組應用程式中詳細說明。
常見模式
輔助注入 (Assisted injection)
Hilt 的 @AssistedInject 與 @AssistedFactory 會轉變為注入參數。呼叫端在執行時傳入其值:
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") }請參閱注入參數。
Lazy 與 Provider
dagger.Lazy<T>:使用 Kotlin 的Lazy<T>建構函式參數,或在 Android 入口點中使用by inject()(請參閱注入)。Provider<T>:若要在每次呼叫時都從自有類別建立新的執行個體,請使用進階模式中的 provider 模式。
WorkManager
@HiltWorker worker 會成為 worker 定義,而 HiltWorkerFactory 在 startKoin 中會改用 workManagerFactory()。請參閱 WorkManager。
檢查表
- [ ] Gradle:移除 Hilt 外掛程式、
hilt-android與hilt-compiler。新增 Koin,若有使用則一併新增編譯器外掛程式。如果沒有其他工具需要,請移除 kapt。 - [ ] Application:移除
@HiltAndroidApp,在onCreate()中透過androidContext()啟動 Koin。 - [ ] 模組:將
@Module/@InstallIn/@Provides/@Binds轉換為 Koin 模組。 - [ ] ViewModel:移除
@HiltViewModel,宣告它們,並使用by viewModel()/koinViewModel()。 - [ ] 入口點:移除
@AndroidEntryPoint,在 Android 元件中使用by inject()。將自有類別的@Inject欄位移至建構函式參數。僅在 Koin 無法建立的架構類別中將@EntryPoint替換為KoinComponent。 - [ ] 限定詞:保留自訂
@Qualifier註解(註解風格)或改用named()。 - [ ] Worker:替換
@HiltWorker與HiltWorkerFactory。 - [ ] 測試:移除
@HiltAndroidTest、HiltAndroidRule以及 Hilt 測試執行器,改用KoinTestRule。 - [ ] 組建:搭配編譯器外掛程式時,組建成功即代表相依圖完整。若未使用,請新增 verify() 測試。
- [ ] 執行:啟動應用程式與測試套件。
疑難排解
NoDefinitionFoundException
Koin 找不到所請求型別的定義。請檢查宣告該型別的模組是否已在 startKoin 中載入(或透過 @Configuration 找到),並確認所請求的型別與已宣告或繫結的型別相符。原本只有 @Inject constructor 且由 Hilt 注入的類別也需要 Koin 定義,除非 @ComponentScan 透過其 JSR-330 註解自動納入該類別。
同一型別有兩個定義導致取得錯誤的執行個體
在 Hilt 中,缺少限定詞會導致組建錯誤。而在 Koin 中,最後載入的定義會覆蓋先前的定義,除非你在啟動 Koin 時設定了 allowOverride(false)。請在兩個定義以及注入點都加上限定詞。
循環相依
兩個類別互相相依。請進行重構以打破循環,或使用 Lazy<T> 參數將其中一方設為延遲載入。編譯器外掛程式會在組建期回報循環相依。更多資訊請參閱疑難排解。
相關內容
- Koin 與 Hilt 比較:這兩種架構有何不同。
- JSR-330 註解:在遷移期間保留
@Inject與@Singleton。 - 在 Android 上啟動 Koin:
startKoin、androidContext()與日誌記錄。 - Android 作用域:Activity、Fragment 與 ViewModel 作用域。
- 單元測試:替換 Hilt 測試規則。
- 編譯期安全性:編譯器外掛程式檢查的項目。
