使用 Koin 与 Jetpack Compose 构建 Android 依赖注入应用:完整入门教程

原创2026-09-23 09:32:501,706 阅读
文章标签:后端

使用 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)
        }
    }
}

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

继续深入可参考以下仓库资源:

登录后查看全文
koin