Skip to content

從 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
@HiltAndroidAppApplication.onCreate() 中的 startKoin { }@KoinApplication + startKoin<T>()Application.onCreate() 中的 startKoin { }
@AndroidEntryPoint不需要:by inject()、by viewModel()不需要不需要
@Inject constructorsingle<T>() / factory<T>()類別上的 @Singleton / @FactorysingleOf(::T) / factoryOf(::T)
@Module + @InstallInmodule { }@Module + @ComponentScanmodule { }
@Providessingle { create(::fn) }函式上的 @Singleton / @Factorysingle { ... }
@Bindsbind Interface::class自動(超型別)或 binds = [...]bind Interface::class
@Singletonsingle@Singleton / @Singlesingle
@HiltViewModelviewModel<T>()@KoinViewModelviewModelOf(::T)
@HiltWorkerworker<T>()@KoinWorkerworkerOf(::T)
@Named、自訂 @Qualifiernamed("x")、參數上的 @Named@Named、自訂 @Qualifiernamed("x")
@ApplicationContextContext 參數,由 androidContext() 提供相同androidContext()
@AssistedInject注入參數@InjectedParam注入參數
自有類別中的 @Inject 欄位建構函式參數建構函式參數建構函式參數
@EntryPoint(Hilt 無法注入的架構類別)僅在該入口點使用 KoinComponent相同相同
@HiltAndroidTestKoinTestRuleKoinTestRuleKoinTestRule

作用域對應 ​

HiltKoin DSL註解生命週期
@Singleton (SingletonComponent)single@Singleton應用程式
@ActivityRetainedScopedactivityRetainedScope { }@ActivityRetainedScope在組態變更後保留
@ViewModelScopedviewModelScope { }@ViewModelScopeViewModel
@ActivityScopedactivityScope { }@ActivityScopeActivity
@FragmentScopedfragmentScope { }@FragmentScopeFragment

作用域 DSL 與註解已在 Android 作用域中詳細說明。

步驟 1:Gradle ​

移除 Hilt 外掛程式、hilt-android 以及 hilt-compiler(kapt 或 KSP)。接著新增 Koin:

kotlin
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:

kotlin
@HiltAndroidApp
class MyApplication : Application()

Koin:

kotlin
class MyApplication : Application() {
    override fun onCreate() {
        super.onCreate()
        startKoin {
            androidLogger()
            androidContext(this@MyApplication)
            modules(appModule)
        }
    }
}
kotlin
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])。

kotlin
class MyApplication : Application() {
    override fun onCreate() {
        super.onCreate()
        startKoin {
            androidLogger()
            androidContext(this@MyApplication)
            modules(appModule)
        }
    }
}

androidContext() 讓所有定義都能取得 Context。請參閱在 Android 上啟動 Koin。

步驟 3:模組與 @Provides ​

Hilt:

kotlin
@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:

kotlin
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) }
}
kotlin
@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)
}
kotlin
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:

kotlin
@Module
@InstallIn(SingletonComponent::class)
abstract class DataModule {
    @Binds
    @Singleton
    abstract fun bindUserRepository(impl: UserRepositoryImpl): UserRepository
}

Koin:

kotlin
val dataModule = module {
    single<UserRepositoryImpl>() bind UserRepository::class
}
kotlin
@Singleton
class UserRepositoryImpl(private val api: ApiService) : UserRepository

該類別會繫結至其所有的超型別。若只想繫結部分超型別,請使用 @Singleton(binds = [UserRepository::class])。

kotlin
val dataModule = module {
    singleOf(::UserRepositoryImpl) bind UserRepository::class
}

步驟 5:ViewModel ​

Hilt:

kotlin
@HiltViewModel
class UserViewModel @Inject constructor(
    private val repository: UserRepository,
    private val savedStateHandle: SavedStateHandle,
) : ViewModel()

Koin:

kotlin
class UserViewModel(
    private val repository: UserRepository,
    private val savedStateHandle: SavedStateHandle,
) : ViewModel()

val appModule = module {
    viewModel<UserViewModel>()
}
kotlin
@KoinViewModel
class UserViewModel(
    private val repository: UserRepository,
    private val savedStateHandle: SavedStateHandle,
) : ViewModel()
kotlin
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:

kotlin
@AndroidEntryPoint
class MainActivity : ComponentActivity() {
    @Inject lateinit var analytics: Analytics
}

Koin:

kotlin
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():

kotlin
// 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:

kotlin
@Qualifier
@Retention(AnnotationRetention.BINARY)
annotation class IoDispatcher

@Provides
@IoDispatcher
fun provideIoDispatcher(): CoroutineDispatcher = Dispatchers.IO

class SyncRepository @Inject constructor(
    @IoDispatcher private val dispatcher: CoroutineDispatcher,
)

Koin:

kotlin
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)的自訂註解:

kotlin
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,
)
kotlin
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 則可以直接解析:

kotlin
@Composable
fun UserScreen(viewModel: UserViewModel = koinViewModel()) {
    val analytics: Analytics = koinInject()
}

請參閱 Koin for Compose。

步驟 9:測試 ​

Hilt:

kotlin
@HiltAndroidTest
class UserRepositoryTest {
    @get:Rule
    val hiltRule = HiltAndroidRule(this)

    @Inject lateinit var repository: UserRepository

    @Before
    fun init() = hiltRule.inject()
}

Koin:

kotlin
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 會轉變為注入參數。呼叫端在執行時傳入其值:

kotlin
class UserDetailViewModel(
    @InjectedParam private val userId: String,
    private val repository: UserRepository,
) : ViewModel()

val appModule = module {
    viewModel<UserDetailViewModel>()
}
kotlin
@KoinViewModel
class UserDetailViewModel(
    @InjectedParam private val userId: String,
    private val repository: UserRepository,
) : ViewModel()
kotlin
class UserDetailViewModel(
    private val userId: String,
    private val repository: UserRepository,
) : ViewModel()

val appModule = module {
    viewModel { (userId: String) -> UserDetailViewModel(userId, get()) }
}
kotlin
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> 參數將其中一方設為延遲載入。編譯器外掛程式會在組建期回報循環相依。更多資訊請參閱疑難排解。