选择你的风格
Koin 提供了两种声明定义(definition)的风格,两者填充的是同一个容器:在你的类上使用注解,或者在 module { } 代码块中使用 Koin DSL。DSL 包含三种形式:编译器插件 DSL(single<T>())、构造函数 DSL(singleOf(::T))以及传统 DSL(single { T(get()) })。风格的选择仅会改变你编写模块的方式,并不会改变 Koin 在运行时的运作机制。本页面展示了每种风格、它们的要求与权衡,并给出了默认推荐方案。我们假设你已经了解什么是定义和模块(参见核心概念)。
各种风格的直观对比
以下是使用每种风格编写的同一个模块:
import org.koin.dsl.module
import org.koin.plugin.module.dsl.*
val appModule = module {
single<ApiService>()
single<UserRepositoryImpl>() bind UserRepository::class
viewModel<UserViewModel>()
}你只需指定类型。Koin 编译器插件会读取其构造函数并生成装配代码。
@Singleton
class ApiService
@Singleton
class UserRepositoryImpl(private val api: ApiService) : UserRepository
@KoinViewModel
class UserViewModel(private val repository: UserRepository) : ViewModel()
@Module
@ComponentScan("com.example.app")
class AppModule你只需为每个类添加注解。@ComponentScan 会将它们收集到一个模块中,然后编译器插件生成装配代码。接口会自动进行绑定。
构造函数 DSL,使用构造函数引用:
import org.koin.dsl.module
import org.koin.core.module.dsl.*
val appModule = module {
singleOf(::ApiService)
singleOf(::UserRepositoryImpl) bind UserRepository::class
viewModelOf(::UserViewModel)
}传统 DSL,手动编写构造函数调用:
val appModule = module {
single { ApiService() }
single<UserRepository> { UserRepositoryImpl(get()) }
viewModel { UserViewModel(get()) }
}这两种形式均可在没有编译器插件的情况下工作。当应用了该插件后,它们在构建期同样会接受检查。
要求
| 编译器插件 DSL | 注解 | 构造函数 / 传统 DSL | |
|---|---|---|---|
| Koin 版本 | 4.2.0+ | 4.2.0+ | 任意 |
| Kotlin 版本 | 2.3.20+ (K2) | 2.3.20+ (K2) | 你的 Koin 版本所支持的任意版本 |
| Gradle 插件 | io.insert-koin.compiler.plugin(必需) | io.insert-koin.compiler.plugin(必需) | 可选:添加编译期检查 |
| 额外依赖 | 仅参数注解需要 koin-annotations(@Named、@InjectedParam) | koin-annotations | 无 |
| 导入项 | org.koin.plugin.module.dsl.* | org.koin.core.annotation.* | org.koin.core.module.dsl.*(构造函数),org.koin.dsl.*(传统) |
每个编译器插件版本都会在一系列 Kotlin 版本上进行验证。插件 1.2.1 已在 Kotlin 2.3.20、2.4.0、2.4.10 和 2.4.20 上完成验证。安装步骤请参见编译器插件设置。
WARNING
编译器插件 DSL 函数(single<T>()、factory<T>()、create(::T))均为存根。若未应用 Gradle 插件,代码虽能编译,但运行时会抛出 NotImplementedError。请在每个使用它们的 Gradle 模块中应用该插件。
权衡
编译器插件 DSL
- 编译期检查:整个依赖图以及每个
get()调用站点都会在构建期进行验证。 - 无需装配代码:没有
get(),没有构造函数引用。添加构造函数参数无需修改模块代码。 - 显式模块:你可以在一处看到模块的所有定义,并且可以在它们周围使用 Kotlin 代码(条件判断、循环)。
- 参数注解:限定符和注入参数声明在类上(
@Named、@InjectedParam),因此该类需要依赖koin-annotations。 - Kotlin 耦合:你需要较新的 K2 编译器,且每次 Kotlin 发布新版本可能都需要对应发布新的插件版本。
注解
- 编译期检查:与编译器插件 DSL 相同。
- 定义紧邻类:生命周期和绑定关系在编写类的地方一目了然。对于来自 Hilt、Dagger 或 Spring 的团队来说,这种模式非常熟悉。
- 自动绑定:类会自动绑定到其所有的超类型,除非你显式列出了
binds。 - 扫描配置:定义是通过软件包来查找的。你需要配置带有正确软件包路径的
@Module和@ComponentScan,并使用@Configuration或@KoinApplication跨 Gradle 模块组装各个模块。位于扫描软件包之外的类不会成为模块的一部分。仅当有其他定义需要它时,编译期检查才会报错。 - 功能空白:某些选项仅在 DSL 中可用,例如
onClose回调。你必须在 DSL 模块中编写这些定义。 - Kotlin 耦合:与编译器插件 DSL 相同。
构造函数 DSL 与传统 DSL
- 随处可用:编译器插件是可选的,除 Koin 本身的要求外没有其他 Kotlin 版本限制。
- 配合插件进行编译期检查:自编译器插件 1.2.0 起,应用插件后会像检查
single<T>()一样检查singleOf(::T)、factoryOf(::T)、scopedOf(::T)和viewModelOf(::T),并通过手写 lambda 的get()调用对其进行检查。现有模块无需重写即可获得编译期检查能力。 - 完全控制(传统 DSL):lambda 是纯粹的 Kotlin 代码,因此你可以在运行时调用构建器、读取配置或选择具体实现。
- 没有插件时的运行时错误:缺失的定义会在代码运行时才被发现。可在单元测试中使用
verify()尽早捕获此类错误。 - 需要维护装配代码:
single { UserRepository(get(), get()) }必须手动跟随构造函数的变更进行修改。singleOf(::UserRepository)会自动跟随变更,但对于可空、延迟加载(lazy)或带有限定符的形参,仍需要显式调用。
该选择哪一种
为项目选定一种风格并明确规范:注解风格或 DSL 风格。
对于使用 Kotlin 2.3.20 或更高版本的新项目,推荐使用编译器插件 DSL。它能提供编译期检查,使你的类与依赖注入解耦,并保持模块为显式的 Kotlin 代码。如果你的团队更倾向于直接在类上声明定义(类似于 Hilt 或 Dagger),请使用注解:它们拥有相同的检查机制,并且兼容 JSR-330(@Inject、@Singleton、@Named)。
在以下情况下,请保留构造函数或传统 DSL:你无法使用较新的 Kotlin 版本;你正在构建一个不得强制要求使用者引入编译器插件的库;或者现有模块运行良好且你不想对其进行改动。你可以直接应用编译器插件,无需重写即可为它们添加编译期检查。凡是定义需要自定义逻辑的地方,均可使用传统 DSL 的 lambda。
混用风格
所有风格生成的定义都是完全相同的,因此一个项目可以同时使用多种风格。但建议每个项目优先保持单一风格。如果你同时混用注解和 DSL,请确保每个模块内部保持单一风格。常见场景包括:
- 在一个模块中混用编译器插件 DSL 与传统 DSL:大多数定义使用
single<T>(),在需要自定义逻辑的地方使用 lambda。这两者都是 DSL 的形式,因此这不属于混用风格。 - 以注解为主,辅以少数 DSL 模块:从你的
@KoinApplication类开始,在配置块中添加 DSL 模块。 - 以 DSL 启动,配合注解模块:将
@Module类加载到常规的startKoin中。
import org.koin.plugin.module.dsl.module
import org.koin.plugin.module.dsl.startKoin
// 基于注解的应用程序,外加 DSL 模块
startKoin<MyApp> {
modules(legacyModule)
}
// 基于 DSL 的应用程序,外加注解模块
startKoin {
modules(appModule)
module<NetworkModule>()
}@Module(includes = [...]) 和 @KoinApplication(modules = [...]) 仅接受 @Module 类,不接受 DSL 的 module { } 值。有关完整规则,请参阅模块和启动 Koin。
KSP 处理器已被弃用
在编译器插件推出之前,注解是由 KSP 处理器 koin-ksp-compiler 进行处理的。该处理器已被弃用,并将在未来的 Koin 版本中移除。注解本身并未被弃用:koin-annotations 是 Koin 主项目的一部分,随每个 Koin 版本一同发布。如果你目前正在使用 KSP,你的注解类无需更改,仅需修改构建配置和启动代码。详情请参见从 KSP 迁移到编译器插件。
页面中的选项卡
本文档中的代码示例均使用相同的三个选项卡:编译器插件 DSL、注解、构造函数 / 传统 DSL。当你选择某个选项卡时,该选择会保存在你的浏览器中并应用到所有页面。在所有风格中写法完全相同的示例(例如在 Activity 中使用 by inject()),将直接显示一次,不提供选项卡。
