Skip to content

Koin 编译器插件 ​

Koin 编译器插件(Koin Compiler Plugin)是一个运行在 Kotlin 编译器 (K2) 内部的 Kotlin 编译器插件。它负责为你定义的依赖编写构造函数装配代码,并在构建期检查依赖图。它同时为 Compiler Plugin DSL 和注解提供支持。本页将说明它的功能与实现原理。如需安装,请参阅编译器插件安装。若要将其与 Constructor DSL 和 Classic DSL 进行对比,请参阅选择你的风格。

它对你的代码做了什么 ​

你只需编写类型,插件负责编写构造函数调用:

kotlin
class UserRepository(private val api: ApiService, private val cache: UserCache)

val appModule = module {
    single<UserRepository>()
}
kotlin
@Singleton
class UserRepository(private val api: ApiService, private val cache: UserCache)

Classic DSL 不需要该插件:装配代码由你自行编写。Constructor DSL (singleOf(::T)) 同样也不需要它。

kotlin
val appModule = module {
    single { UserRepository(get(), get()) }
}

如果应用了该插件,它仍会在构建期检查这些 get() 调用和 singleOf(::T) 定义。

在编译期间,插件会将 single<UserRepository>()(或带有 @Singleton 的类)替换为等效的以下代码:

kotlin
single { UserRepository(get(), get()) }

生成的代码与 Classic DSL 所使用的运行时代码完全相同。在运行时没有任何变化:定义会被放入同一个容器中,并且 Koin 会以相同的方式解析它们。各个形参类型均会得到妥善处理:可空类型使用 getOrNull(),Lazy<T> 使用 inject(),List<T> 使用 getAll(),而带有注解的形参(@Named、@InjectedParam、@Property)则使用对应的调用。完整对照表请参阅定义。

在 DSL 风格中,由模块指明类在哪里注册,而类形参上的注解则指明它们如何被解析:

kotlin
class UserPresenter(
    @InjectedParam val userId: String,
    @Named("remote") val api: ApiService,
    val repository: UserRepository,
)

val appModule = module {
    factory<UserPresenter>()
}

工作原理 ​

该插件挂钩到 Kotlin K2 编译器的两个阶段:

text
Kotlin 源代码
     │
     ▼
  FIR (前端)       查找 @Module、@ComponentScan、@Configuration 并声明
                   生成的模块属性与跨模块提示 (cross-module hints)
     │
     ▼
  IR (后端)        1. 收集带注解的定义并填充模块
                   2. 重写 DSL 调用:single<T>() 变为 single { T(get()) }
                   3. 在入口点 (startKoin, @KoinApplication) 处组装
                      完整依赖图并进行验证
                   4. 验证 get()、inject()、koinViewModel() 调用站点
     │
     ▼
  字节码 (JVM, Android, Native, JS, Wasm)

你的项目中不会生成任何源文件。为了能够跨 Gradle 模块感知定义,插件会向每个编译后的模块中添加微小的合成标记函数(“hints”)。下游模块读取这些标记函数,即可找到其依赖项中声明的定义。这就是为什么每个声明了 Koin 定义的 Gradle 模块都必须应用该插件。

验证内容 ​

插件会在各个 Koin 入口点验证依赖图:startKoin、koinApplication、@KoinApplication、KoinApplication.withConfiguration<T>() 以及 Ktor 的 install(Koin) {}。对于每个定义,它都会检查每个非空构造函数形参是否都具有匹配的定义,且具备正确的限定符并处于可达的作用域内。它还会检查每一个 get<T>()、inject<T>() 和 koinViewModel<T>() 调用。

缺失依赖项将导致构建失败:

text
[Koin][KOIN-D001] Missing dependency: ApiService
  required by: UserRepository (parameter 'api')
  in module: ...

完整的检查列表、错误代码以及 @Provided 逃生通道请参阅编译期安全性。

限制 ​

  • 运行时加载的模块:后续通过 loadKoinModules() 添加的模块不在插件所能感知的依赖图中。它们提供的类型必须标记为 @Provided。
  • 单独的库模块:没有 Koin 入口点的 Gradle 模块不会单独进行验证。它会在应用程序模块对其进行组装时进行检查。
  • 增量编译:与其他 IR 编译器插件一样,某些更改(在被扫描的包之间移动类、更改限定符)可能会残留过时的结果。执行一次全新构建(clean build)即可解决此类问题。详情请参阅编译器插件安装。
  • Kotlin 版本:该插件使用了在 Kotlin 各版本间可能会发生变化的编译器 API。每个插件版本均在一系列 Kotlin 版本上经过验证,使用其他版本将会打印警告。

环境要求 ​

  • Kotlin 2.3.20 或更高版本(K2 编译器)。插件 1.2.1 版已在 Kotlin 2.3.20、2.4.0、2.4.10 和 2.4.20 上完成验证。
  • Koin 4.2.0 或更高版本。
  • Gradle 插件 io.insert-koin.compiler.plugin,需应用在每个声明了定义的 Gradle 模块中。

Compiler Plugin DSL 位于 org.koin.plugin.module.dsl 包中,随 koin-core 一起分发。Classic DSL 保留在 org.koin.dsl 中,Constructor DSL 保留在 org.koin.core.module.dsl 中。

该插件取代了已弃用的 KSP 处理器 koin-ksp-compiler,并支持相同的注解。请参阅从 KSP 迁移。源代码位于 GitHub:InsertKoinIO/koin-compiler-plugin。