Koin for Compose 实战指南:Jetpack Compose 与 Compose Multiplatform 依赖注入全解析
Koin for Compose 实战指南:Jetpack Compose 与 Compose Multiplatform 依赖注入全解析
Koin 为 Jetpack Compose 与 Compose Multiplatform(Android / iOS / Desktop / Web)提供了完整的依赖注入支持,通过 koin-compose、koin-compose-viewmodel 等专门封装包,让 Composable 函数可以直接以 koinInject()、koinViewModel() 等组合函数完成注入,并与组合(Composition)生命周期深度绑定。本文以官方文档 docs/reference/koin-compose/compose.md 为主体骨架,结合仓库源码与示例工程,系统讲解包选型、Koin 启动方式、基础注入、模块定义、动态模块与作用域等核心能力,读完后你将能够在 Android 与跨平台 Compose 项目中正确、高效地接入 Koin。
包结构总览与选型
Koin 针对不同 Compose 使用场景拆分出多个包,各自职责如下:
| 包名 | 使用场景 |
|---|---|
koin-compose |
基础 Compose API(多平台) |
koin-compose-viewmodel |
ViewModel 注入(多平台) |
koin-compose-viewmodel-navigation |
ViewModel + Navigation 2.x |
koin-compose-navigation3 |
Navigation 3 集成(多平台) |
koin-androidx-compose |
Android 便捷封装(包含 koin-compose + koin-compose-viewmodel) |
其中所有 Compose API 都定义在 koin-compose 与 koin-compose-viewmodel 中;koin-androidx-compose 只是一个便捷包装包,面向 Android 工程把两者一并带入。
从源码结构看,koin-compose 的核心 API 分布在 projects/compose/koin-compose/src/commonMain/kotlin/org/koin/compose 下:Inject.kt(koinInject)、KoinApplication.kt(组合级启动与上下文)、module/(动态模块)、scope/(作用域);而 ViewModel 注入集中在 projects/compose/koin-compose-viewmodel/src/commonMain/kotlin/org/koin/compose/viewmodel/ViewModel.kt。
该用哪个包?
Android-only 工程,三选一或组合使用:
// 方案 1:Android 便捷包(已包含 koin-compose + koin-compose-viewmodel)
implementation("io.insert-koin:koin-androidx-compose:$koin_version")
// 方案 2:直接使用多平台包
implementation("io.insert-koin:koin-compose:$koin_version")
implementation("io.insert-koin:koin-compose-viewmodel:$koin_version")
// 可选:Navigation 集成
implementation("io.insert-koin:koin-androidx-compose-navigation:$koin_version")
Compose Multiplatform 工程(Android/iOS/Desktop 共享 UI),在 commonMain 中声明:
commonMain.dependencies {
implementation("io.insert-koin:koin-compose:$koin_version")
implementation("io.insert-koin:koin-compose-viewmodel:$koin_version")
// 可选:Navigation 集成
implementation("io.insert-koin:koin-compose-viewmodel-navigation:$koin_version")
}
koin_version 为当前使用的 Koin 版本号。仓库自身的版本目录 projects/gradle/libs.versions.toml 也印证了多平台 Compose 依赖的搭配方式:AndroidX Compose / JetBrains Compose(jb-compose)以及 org.jetbrains.androidx.lifecycle:lifecycle-viewmodel-compose 等运行时依赖由各模块按平台分别解析。
平台支持矩阵
| 平台 | Compose 类型 | 状态 |
|---|---|---|
| Android | Jetpack Compose | 完整支持 |
| iOS | Compose Multiplatform | 完整支持 |
| Desktop | Compose Desktop | 完整支持 |
| Web | Compose for Web | 实验性 |
启动 Koin:两种方式与背后的组合生命周期机制
方式一:startKoin(Android-only 或外部初始化)
在 Compose 之外完成 Koin 初始化,获得完全控制权,适合需要自定义配置或与其它框架集成(如 Ktor、WorkManager)的场景:
// Android Application 类
class MyApplication : Application() {
override fun onCreate() {
super.onCreate()
startKoin {
androidContext(this@MyApplication)
androidLogger()
modules(appModule)
}
}
}
// Compose UI 直接使用 Koin
@Composable
fun App() {
val viewModel = koinViewModel<MyViewModel>()
}
这种方式的示例可参考仓库中的 examples/sample-android-compose/src/main/java/org/koin/sample/androidx/compose/MainApplication.kt,其中还设置了 androidLogger(Level.DEBUG) 便于调试。
适用场景:需要完全控制 Koin 生命周期、自定义配置或与其它框架集成。
方式二:KoinApplication(由 Compose 管理)
让 Compose 自动完成 Koin 的创建、启动与停止:
@Composable
fun App() {
KoinApplication(configuration = koinConfiguration {
modules(appModule)
}) {
MyScreen()
}
}
优势:
- 无需外部初始化(不需要 Application 类);
- Android 上自动注入
androidContext与androidLogger; - 依据组合生命周期自动 start/stop;
- Android 上自动处理配置变更。
适用场景:希望以最简方式接入、且不需要太多控制的场景。
注意:KoinMultiplatformApplication 已弃用,请改用 KoinApplication + koinConfiguration。
源码层面的工作原理
KoinApplication(configuration: KoinConfiguration, logLevel: Level, content) 的实现位于 projects/compose/koin-compose/src/commonMain/kotlin/org/koin/compose/KoinApplication.kt:
- 先调用
rememberKoinMPApplication(configuration, logLevel)创建 Koin 实例; - 再通过
CompositionLocalProvider把 Koin 与根 Scope 包装进LocalKoinApplicationContext和LocalKoinScopeContext两个 CompositionLocal,供整棵组合树读取。
其中 rememberKoinMPApplication(RememberKoinApplication.kt)会先调用平台 expect 函数 composeMultiplatformConfiguration 合并平台配置,再交由 CompositionKoinApplicationLoader 处理。Android 上的实际实现(KoinApplication.android.kt)会自动补充:
koinConfiguration {
androidContext(appContext) // 从 LocalContext 获取 applicationContext
androidLogger(loggerLevel)
includes(config)
}
CompositionKoinApplicationLoader(CompositionKoinApplicationLoader.kt)实现了 RememberObserver 接口:组合进入时若发现全局尚无 Koin 上下文则执行 startKoin(koinApplication);组合被 onAbandoned 时停止 Koin 上下文;onForgotten 时仅释放引用而不提前 stop。这就是“由 Compose 托管 Koin 生命周期”的底层机制。
此外,KoinApplicationPreview(同样在 KoinApplication.kt)为 Android Studio Preview 提供了轻量级本地 Koin 上下文,避免在预览中与全局上下文冲突。示例工程 examples/sample-android-compose/src/main/java/org/koin/sample/androidx/compose/App.kt 中有 KoinApplicationPreview(application = { modules(appModule) }) { ... } 配合 @Preview 的完整用法。
基础注入:koinInject 与 koinViewModel
koinInject() —— 获取任意依赖
在任意 Composable 中注入 Koin 管理的依赖:
@Composable
fun UserScreen() {
val repository = koinInject<UserRepository>()
// Use repository...
}
最佳实践 —— 作为默认参数注入,使 Composable 在不依赖 Koin 的情况下也能测试:
@Composable
fun UserScreen(
repository: UserRepository = koinInject()
) {
// Testable without Koin
}
koinInject 的 remember 机制
koinInject 的三个重载均定义在 projects/compose/koin-compose/src/commonMain/kotlin/org/koin/compose/Inject.kt:
- 无参数版本:
remember(qualifier, scope) { scope.get(T::class, qualifier) },实例在重组合(recomposition)期间被记住; ParametersDefinition版本(lambda 形式):会先把参数展开为ParametersHolder,再以remember(qualifier, scope, p)缓存,参数变化会触发重新解析;ParametersHolder版本(parametersOf()直传):同样被remember缓存,官方注释明确建议在频繁重组合时优先使用这一形式以提升性能。
默认 scope 来自 currentKoinScope(),即 LocalKoinScopeContext 提供的当前组合作用域(见 KoinApplication.kt)。当 Scope 已关闭时,底层 ComposeContextWrapper(ComposeContextWrapper.kt)会自动回退到默认根上下文,从而优雅应对配置变更等场景。
koinViewModel() —— 获取 ViewModel
注入带完整生命周期管理的 ViewModel:
@Composable
fun UserScreen() {
val viewModel = koinViewModel<UserViewModel>()
val state by viewModel.state.collectAsState()
}
多平台版本的 koinViewModel 实现在 projects/compose/koin-compose-viewmodel/src/commonMain/kotlin/org/koin/compose/viewmodel/ViewModel.kt,签名完整支持 qualifier、viewModelStoreOwner(默认取 LocalViewModelStoreOwner.current)、key、extras、scope 与 parameters,最终委托给 org.koin.viewmodel.resolveViewModel 完成解析。Android 版实现(koin-androidx-compose 的 ViewModel.kt)与之等价,行为一致。
带参数的注入
传递运行时参数:
@Composable
fun DetailScreen(itemId: String) {
val viewModel = koinViewModel<DetailViewModel> {
parametersOf(itemId)
}
}
当 Composable 频繁重组合时,建议使用显式 parameters 形式以获得更好性能(参数只求值一次并被 remember,不会在每次重组合时重新展开 lambda):
@Composable
fun DetailScreen(itemId: String) {
val viewModel = koinViewModel<DetailViewModel>(
parameters = parametersOf(itemId)
)
}
同样的性能考量也适用于 koinInject,详见 docs/reference/koin-compose/compose-lifecycle.md 中“Performance with Parameters”一节。示例工程 examples/sample-android-compose/.../App.kt 展示了 koinViewModel(parameters = { parametersOf(parentStatus) }) 与 koinInject(parametersHolder = parametersOf("stable_status")) 两种实战用法。
定义模块:三种 DSL 风格
Compiler Plugin DSL(编译期自动装配)
val appModule = module {
single<UserRepository>()
viewModel<UserViewModel>()
}
该 DSL 需要启用 Koin Compiler Plugin(见 docs/setup/compiler-plugin.md),由编译器在编译期完成依赖解析,语法最简洁。
Annotations(注解 + KSP)
@Singleton
class UserRepository
@KoinViewModel
class UserViewModel(
private val repository: UserRepository
) : ViewModel()
注解方式由 Koin Annotations(KSP 编译器)在编译期生成模块与装配代码,配合 @Module、@ComponentScan、@Configuration 可实现自动模块发现。完整的 Compose Multiplatform 注解示例见 docs/quickstart/compose-multiplatform-annotations.md。
Classic DSL(经典手动装配)
val appModule = module {
singleOf(::UserRepository)
viewModelOf(::UserViewModel)
}
经典 DSL 通过构造器引用 singleOf / viewModelOf 声明定义,无需编译插件即可运行。示例工程 examples/sample-android-compose/.../di/appModule.kt 正是这种风格,并包含 factoryOf(::MyFactory)、scope<MyFactory> { ... } 等更多定义形式。
动态模块:rememberKoinModules
在 Composable 进入组合时按需加载模块,离开组合时按配置卸载,适用于特性模块、懒加载与按需依赖:
val featureModule = module {
factory<FeatureRepository>()
viewModel<FeatureViewModel>()
}
@Composable
fun FeatureScreen() {
// 进入组合时加载模块
rememberKoinModules(featureModule)
val viewModel = koinViewModel<FeatureViewModel>()
}
rememberKoinModules(projects/compose/koin-compose/src/commonMain/kotlin/org/koin/compose/module/RememberModules.kt)内部使用 CompositionKoinModuleLoader(CompositionKoinModuleLoader.kt)在 remember 中完成 koin.loadModules(modules);当 unloadOnForgotten / unloadOnAbandoned 开启时,组合退出或失败会调用 koin.unloadModules(modules) 卸载模块,防止内存泄漏。模块可以一次传入多个,也可以与 lazyModule、导航(NavHost 目的地内加载)组合使用。详细用法与卸载选项见 docs/reference/koin-compose/compose-modules.md。
作用域:KoinScope 与相关 API
KoinScope 创建绑定 Composable 生命周期的 Koin 作用域,离开组合时自动关闭:
KoinScope(scopeOf<FeatureScope>()) {
// 所有子组合均可访问 scoped 依赖
FeatureContent()
}
其底层实现(projects/compose/koin-compose/src/commonMain/kotlin/org/koin/compose/scope/KoinScope.kt)提供三种重载:按 Koin.() -> Scope lambda、按 ScopeID、按 ScopeID + Qualifier 创建作用域,并统一通过 OnKoinScope 将 scope 注入 LocalKoinScopeContext 且以 rememberKoinScope 管理生命周期。
UnboundKoinScope(UnboundKoinScope.kt)则不绑定组合生命周期,直接把已存在的 Scope 提供给子组合——它被标注为 Delicate API,Scope 需要外部手动关闭,适用于由外部系统管理、或跨多棵组合树共享的 Scope。此外还有面向 Android 的 KoinActivityScope / KoinFragmentScope(koin-androidx-compose 的 KoinAndroidScope.kt)、Activity 级注入 koinActivityInject(KoinActivityInject.kt)以及导航级 KoinNavigationScope(要求 koin-compose-viewmodel-navigation)。各作用域 API 的对比与最佳实践见 docs/reference/koin-compose/compose-scopes.md。
快速参考表
| 函数 | 用途 |
|---|---|
koinInject<T>() |
注入任意依赖 |
koinViewModel<T>() |
注入 ViewModel |
koinNavViewModel<T>() |
携带 Navigation 参数的 ViewModel(注意:新版建议直接用 koinViewModel,koinNavViewModel 已标记弃用,见 NavViewModel.kt) |
koinActivityViewModel<T>() |
Activity 作用域的 ViewModel(Android,见 ViewModelExt.kt) |
rememberKoinModules() |
随组合加载模块 |
KoinScope {} |
创建作用域上下文 |
示例工程对照
仓库提供了可直接对照学习的完整示例:
- examples/sample-android-compose:Android Jetpack Compose 全功能示例,覆盖
startKoin启动、koinViewModel/koinInject/ 参数注入、KoinApplicationPreview、rememberKoinModules、KoinScope、KoinActivityScope、Type-Safe 导航与 String 导航,并在MainActivity中演示了隔离上下文(assert(getKoin().getOrNull<SDKData>() == null)); - examples/sample-desktop-compose:Compose Desktop 示例,展示
KoinApplication(application = { modules(mod); printLogger(Level.DEBUG) })与koinInject的桌面端用法(Main.kt)。
相关文档导航
| 主题 | 说明 |
|---|---|
| ViewModel | 全部 ViewModel 注入 API |
| 生命周期与状态 | 重组合、状态、副作用与稳定性 |
| 动态模块 | rememberKoinModules、懒加载 |
| 作用域 | KoinScope、KoinNavigationScope、UnboundKoinScope |
| 测试 | Preview、单元测试 |
| 隔离上下文 | SDK 隔离 |
| Navigation 3 | 类型安全导航(多平台) |
| 核心 ViewModel | ViewModel 声明 DSL |
| Android ViewModel | Android 专属特性 |
| KMP 配置 | 多平台工程配置 |
| 快速上手:Android Compose | 10 分钟完成一个 Compose + Koin 应用 |