Koin for Compose 实战指南:Jetpack Compose 与 Compose Multiplatform 依赖注入全解析

原创2026-09-23 14:28:461,386 阅读
文章标签:后端

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:

  1. 先调用 rememberKoinMPApplication(configuration, logLevel) 创建 Koin 实例;
  2. 再通过 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 应用
登录后查看全文
koin