使用 Koin 与 Jetpack Compose 构建 Android 依赖注入应用:完整入门教程
使用 Koin 与 Jetpack Compose 构建 Android 依赖注入应用:完整入门教程
本篇教程面向需要快速上手的 Android 开发者,讲解如何将 Koin 依赖注入(DI)框架与 Jetpack Compose 声明式 UI 相结合:从 Gradle 依赖配置、组件(Repository / Service / ViewModel)的模块化声明,到在 Compose 界面中通过 koinViewModel() 获取 ViewModel 的完整链路。学完本篇,你将能独立搭建一个"用户管理 + 问候消息"的 Compose 示例应用,并理解 Classic DSL 与 Compiler Plugin DSL 两种模块声明方式的差异。全文基于当前仓库的官方快速入门文档展开,并辅以仓库内真实源码(koin-androidx-compose 模块)与示例工程(sample-android-compose)作为实现佐证。
环境与前置要求
- 一个支持 Jetpack Compose 的 Android 工程(启用
buildFeatures { compose = true }); - Kotlin 与 Gradle 构建环境;
- 如果使用 Koin Compiler Plugin DSL(本教程主推的
single<T>()/viewModel<T>()写法),需要 Kotlin 2.x(K2 编译器)与 Gradle 8.x+,具体安装步骤见 Compiler Plugin Setup。
仓库中的真实示例工程 examples/sample-android-compose/build.gradle 给出了完整的工程配置样板:apply plugin: 'com.android.application' + apply plugin: 'kotlin-android' + apply plugin: 'org.jetbrains.kotlin.plugin.compose',并将 namespace 设为 org.koin.sample.androidx.compose,minSdkVersion 23,同时在 buildFeatures 中开启 compose true。你可以对照该文件检查自己的工程配置。
Gradle 配置:添加 Koin Android 与 Koin Compose 依赖
在模块级 build.gradle 的 dependencies 中添加两个依赖:
dependencies {
// Koin for Android
implementation("io.insert-koin:koin-android:$koin_version")
// Koin for Jetpack Compose
implementation("io.insert-koin:koin-androidx-compose:$koin_version")
}
koin-android:提供 Android 平台的 Koin 核心能力(startKoin、androidContext()、androidLogger()等);koin-androidx-compose:提供 Compose 专用集成,核心 API 即koinViewModel()。
关于依赖包的选择,仓库文档 Koin for Compose 补充说明:koin-androidx-compose 是面向 Android-only 项目的便捷聚合包,内部已包含多平台的 koin-compose 与 koin-compose-viewmodel;而 Compose Multiplatform 项目则应直接使用 io.insert-koin:koin-compose 与 io.insert-koin:koin-compose-viewmodel。仓库示例工程还额外引入了导航集成包 koin-androidx-compose-navigation 与 koin-compose-viewmodel-navigation(见 examples/sample-android-compose/build.gradle),按需添加即可。
应用架构总览
本教程示例应用的目标是:管理一组用户(User),并在 MainActivity 中通过 ViewModel + Jetpack Compose UI 展示。组件依赖链如下:
Users -> UserRepository -> UserService -> UserViewModel -> MainActivity (Compose UI)
数据从最底层的 UserRepository(数据访问)逐层向上传递,最终由 Compose 界面消费,形成清晰的单向依赖:
UserRepository负责用户数据的增删查(持有内存数据集合);UserService封装业务操作(查找用户、加载示例数据、生成问候语);UserViewModel作为界面状态载体,通过构造器注入UserService;MainActivity(ComponentActivity)通过setContent挂载 Compose UI,UI 内用koinViewModel()获取 ViewModel。
数据层:User 数据类与 UserRepository
首先定义用户实体——一个简单的 Kotlin 数据类:
data class User(val name: String, val email: String)
接着编写数据访问组件。先定义接口 UserRepository,再给出其实现 UserRepositoryImpl:
interface UserRepository {
fun findUserOrNull(name: String): User?
fun addUsers(users: List<User>)
}
class UserRepositoryImpl : UserRepository {
private val _users = arrayListOf<User>()
override fun findUserOrNull(name: String): User? {
return _users.firstOrNull { it.name == name }
}
override fun addUsers(users: List<User>) {
_users.addAll(users)
}
}
实现要点:
_users是私有内存集合,模拟持久化存储;findUserOrNull按名称线性查找,未命中返回null;addUsers批量追加用户。
仓库示例工程中的 examples/sample-android-compose/src/main/java/org/koin/sample/androidx/compose/data/UserRepository.kt 提供了与之类似的真实实现(含 getUsers() 读取方法),可作为扩展参考。
业务层:UserService 组件
UserService 是介于数据层与 UI 层之间的业务门面,同样采用"接口 + 实现"的写法:
interface UserService {
fun getUserOrNull(name: String): User?
fun loadUsers()
fun prepareHelloMessage(user: User?): String
}
class UserServiceImpl(
private val userRepository: UserRepository
) : UserService {
override fun getUserOrNull(name: String): User? = userRepository.findUserOrNull(name)
override fun loadUsers() {
userRepository.addUsers(listOf(
User("Alice", "alice@example.com"),
User("Bob", "bob@example.com"),
User("Charlie", "charlie@example.com")
))
}
override fun prepareHelloMessage(user: User?): String {
return user?.let { "Hello '${user.name}' (${user.email})! 👋" } ?: "❌ User not found"
}
}
关键点:
UserServiceImpl的构造函数接收UserRepository——这正是 Koin 将要自动注入(auto-wiring)的依赖;loadUsers()预置了 Alice、Bob、Charlie 三个示例用户;prepareHelloMessage()根据用户是否存在返回不同的问候/报错文案。
仓库示例 examples/sample-android-compose/src/main/java/org/koin/sample/androidx/compose/viewmodel/UserViewModel.kt 中的 ViewModel 也是以构造器方式接收 UserRepository,与这里的注入模式一致。
声明 Koin 模块
Koin 模块(module)是集中定义"哪些组件可被注入"的地方。先创建一个空的模块:
val appModule = module {
}
本示例需要 UserRepository 与 UserService 的单例(整个应用生命周期内只创建一份实例)。使用 Koin Compiler Plugin DSL(本教程主推写法)声明如下:
val appModule = module {
single<UserRepositoryImpl>() bind UserRepository::class
single<UserServiceImpl>() bind UserService::class
}
语法拆解:
single<T>():声明类型T为单例定义,构造器依赖由编译期自动解析(无需手写{ UserServiceImpl(get()) });bind UserRepository::class:将实现类绑定到接口类型上,这样后续注入UserRepository接口时,Koin 能找到UserRepositoryImpl实现。
:::info
本教程使用的 Koin Compiler Plugin DSL(single<T>()、viewModel<T>())在编译期完成自动装配(auto-wiring),需要先完成 Compiler Plugin Setup 配置(在 build.gradle.kts 中应用 io.insert-koin.compiler.plugin 插件、确保 Kotlin 2.3.20+)。其 DSL 位于包 org.koin.plugin.module.dsl。
:::
仓库示例 examples/sample-android-compose/src/main/java/org/koin/sample/androidx/compose/di/appModule.kt 展示了等价的功能型 DSL 写法(singleOf(::UserRepository)、factoryOf(::MyFactory)、scope 声明等),两者最终都归结为 module { } 内的定义集合。
用 ViewModel 展示用户
编写 UserViewModel,它继承 androidx.lifecycle.ViewModel,构造器接收 UserService:
class UserViewModel(private val userService: UserService) : ViewModel() {
fun sayHello(name: String): String {
val user = userService.getUserOrNull(name)
val message = userService.prepareHelloMessage(user)
return "[UserViewModel] $message"
}
}
UserService is referenced in UserViewModel's constructor
将 UserViewModel 加入模块。与 single 不同,它被声明为 viewModel 定义——ViewModel 实例不常驻内存,而是跟随 Android 生命周期托管(避免内存泄漏):
val appModule = module {
single<UserRepositoryImpl>() bind UserRepository::class
single<UserServiceImpl>() bind UserService::class
viewModel<UserViewModel>()
}
在 Jetpack Compose 中注入 ViewModel
使用 Compose 时,Activity 基类选择 ComponentActivity 而非 AppCompatActivity,UI 用 @Composable 函数声明式构建,而非 XML 布局。UserViewModel 在创建时由 Koin 解析其构造器中的 UserService 实例;要在 Compose UI 中拿到它,使用 koinViewModel() 函数:
class MainActivity : ComponentActivity() {
override fun onCreate(savedInstanceState: Bundle?) {
super.onCreate(savedInstanceState)
setContent {
MaterialTheme {
MainScreen()
}
}
}
}
@OptIn(ExperimentalMaterial3Api::class)
@Composable
fun MainScreen(
viewModel: UserViewModel = koinViewModel()
) {
var nameInput by remember { mutableStateOf("") }
var greetingMessage by remember { mutableStateOf("") }
Scaffold(
topBar = {
TopAppBar(
title = { Text("Koin Sample") }
)
}
) { paddingValues ->
Column(
modifier = Modifier
.fillMaxSize()
.padding(paddingValues)
.padding(16.dp),
verticalArrangement = Arrangement.spacedBy(16.dp),
horizontalAlignment = Alignment.CenterHorizontally
) {
OutlinedTextField(
value = nameInput,
onValueChange = { nameInput = it },
label = { Text("Enter name") },
modifier = Modifier.fillMaxWidth()
)
Button(
onClick = {
val userName = nameInput.trim().ifEmpty { "Alice" }
greetingMessage = viewModel.sayHello(userName)
},
modifier = Modifier.fillMaxWidth()
) {
Text("Say Hello")
}
if (greetingMessage.isNotEmpty()) {
Text(
text = greetingMessage,
style = MaterialTheme.typography.bodyLarge,
textAlign = TextAlign.Center,
modifier = Modifier.fillMaxWidth()
)
}
}
}
}
运行流程:用户在输入框键入姓名 → 点击 "Say Hello" → viewModel.sayHello(userName) 经 UserService 查找用户并生成问候语 → 文案渲染在界面中央。输入为空时默认查询 "Alice"。
:::info
koinViewModel() 从 Koin 中获取 ViewModel 实例,并自动将其绑定到 Compose 生命周期。这是 Compose 场景下专属的注入方式,取代了传统 Android View 中使用的 by viewModel() 委托。
:::
关键 Compose 概念速览
| 概念 | 说明 |
|---|---|
| ComponentActivity | Compose 应用的 Activity 基类(替代 AppCompatActivity) |
| setContent | 将 Composable 内容设置为 Activity 的 UI |
| @Composable | 声明式构建 UI 的函数 |
| remember & mutableStateOf | Compose 状态管理,驱动响应式 UI 更新 |
| koinViewModel() | Koin 的 Compose 集成,用于 ViewModel 注入 |
仓库示例工程的 examples/sample-android-compose/src/main/java/org/koin/sample/androidx/compose/MainActivity.kt 展示了在此基础上叠加 Navigation Compose(NavHost + composable)的进阶用法,可作为扩展学习材料。
启动 Koin
在应用入口 MainApplication(继承 Application)的 onCreate() 中调用 startKoin() 启动 Koin:
class MainApplication : Application(){
override fun onCreate() {
super.onCreate()
startKoin{
androidLogger()
androidContext(this@MainApplication)
modules(appModule)
}
}
}
androidLogger():启用 Android 日志输出(仓库示例中还可用androidLogger(Level.DEBUG)指定日志级别,见 examples/sample-android-compose/src/main/java/org/koin/sample/androidx/compose/MainApplication.kt);androidContext(...):向 Koin 注入 AndroidContext,供需要 Context 的组件使用;modules(appModule):加载给定的模块列表。
:::info
startKoin 中的 modules() 函数用于加载传入的模块集合;示例工程中 modules(appModule) 即加载本教程声明的 appModule。
:::
注意:需要在 AndroidManifest.xml 中将 MainApplication 注册为 android:name,确保应用启动时执行初始化。
Classic DSL 与 Compiler Plugin DSL 对比
同一模块有两种等价声明方式。Classic DSL(手动装配,逐一手写构造调用):
val appModule = module {
single<UserRepository> { UserRepositoryImpl() }
single<UserService> { UserServiceImpl(get()) }
viewModel { UserViewModel(get()) }
}
Compiler Plugin DSL(编译期自动装配,语法更简洁):
val appModule = module {
single<UserRepositoryImpl>() bind UserRepository::class
single<UserServiceImpl>() bind UserService::class
viewModel<UserViewModel>()
}
:::tip
Compiler Plugin DSL 需要先配置 Koin Compiler Plugin。它带来编译期依赖解析(compile-time dependency resolution)与更干净的语法:构造器参数由编译器推断注入,省去手写 { ... } 与 get() 调用,且依赖缺失会在构建阶段报错而非运行时崩溃。
:::
两种写法各有适用场景:Classic DSL 不依赖编译插件、上手门槛低;Compiler Plugin DSL 适合 Kotlin 2.x 新项目,配合官方 Compile-Time Safety 能力,可在 A2(模块内)/ A3(全图)/ A4(调用点)三个层面校验依赖图完整性。
Compose 与 XML Views 对比
本教程实现的功能与 Android ViewModel 教程 完全相同,只是 UI 层从 XML 布局换成了 Jetpack Compose。两者对照如下:
| Aspect | XML Views | Jetpack Compose |
|---|---|---|
| Activity Base | AppCompatActivity |
ComponentActivity |
| UI Definition | XML layout files | @Composable functions |
| ViewModel Injection | by viewModel() delegate |
koinViewModel() function |
| State Management | LiveData/StateFlow | remember + mutableStateOf |
| UI Updates | View binding + observers | Automatic recomposition |
:::tip 若希望以注解方式(Koin Annotations)配合 Compose 使用,可参考 Compose Multiplatform Annotations 教程。 :::
深入原理:koinViewModel() 源码解析
koinViewModel() 的定义位于 koin-androidx-compose 模块的 ViewModel.kt:
@OptIn(KoinInternalApi::class)
@Composable
inline fun <reified T : ViewModel> koinViewModel(
qualifier: Qualifier? = null,
viewModelStoreOwner: ViewModelStoreOwner = LocalViewModelStoreOwner.current ?: error("No ViewModelStoreOwner was provided via LocalViewModelStoreOwner"),
key: String? = null,
extras: CreationExtras = defaultExtras(viewModelStoreOwner),
scope: Scope = currentKoinScope(),
noinline parameters: ParametersDefinition? = null,
): T {
return resolveViewModel(
T::class, viewModelStoreOwner.viewModelStore, key, extras, qualifier, scope, parameters
)
}
从源码结构可以梳理出几个关键事实:
- 它是
inline + reified的@Composable函数,泛型T必须是ViewModel子类,直接调用koinViewModel<UserViewModel>()即可获得类型安全解析; - 默认从
LocalViewModelStoreOwner.current获取ViewModelStoreOwner(若 Compose 环境未提供会直接报错提示),并将viewModelStore、key、extras、qualifier、scope、parameters一并传给resolveViewModel; - 它支持可选参数:
qualifier(限定符)、key(ViewModel 键)、extras(CreationExtras,默认来自 ViewModelStoreOwner)、scope(Koin 作用域,默认当前 Compose 作用域)、parameters(动态注入参数); defaultExtras(viewModelStoreOwner)负责将 Android 的SavedStateHandle等能力接入 Koin 的 ViewModel 解析链路。
这意味着除了最基础的默认调用,你还可以按需传入 qualifier 与 parameters 实现多实例 ViewModel 或带参注入,这是 by viewModel() 在 Compose 场景下的完整替代方案。
小结与进一步探索
至此,一个基于 Koin + Jetpack Compose 的完整 Android 应用已经跑通:数据层(UserRepository)→ 业务层(UserService)→ 状态层(UserViewModel)→ UI 层(Compose MainScreen),全程由 Koin 负责构造与注入,UI 侧只需一行 koinViewModel()。
继续深入可参考以下仓库资源:
- 依赖注入基础概念:What is Dependency Injection 与 What is Koin;
- Koin Compose 完整 API:Koin for Compose(
koinInject()、KoinApplication、Compose 作用域等); - Compose 下 ViewModel 的进阶用法:Compose ViewModel;
- Compiler Plugin 安装与配置:Compiler Plugin Setup;
- 可直接运行的完整示例工程:examples/sample-android-compose。