KoinComponent
KoinComponent 是一个让类能够访问 Koin 容器的接口,使其可以调用 get() 和 by inject()。本页面介绍了何时需要它、如何使用它,以及为什么更推荐使用构造函数注入。有关检索函数本身的说明,请参阅 Injection。
何时使用 KoinComponent
对于非 Koin 创建且自身没有 Koin 扩展的类,请使用 KoinComponent:
- 入口点:
main()类、CLI 命令、由框架或反射创建的类。 - 没有 Koin 扩展的 Android 类:
BroadcastReceiver、ContentProvider、自定义View。参见 Android Entry Points。 - 你无法控制其构造函数的回调和监听器。
- 尚无法迁移到构造函数注入的旧版代码。
以下情况无需使用它:
- 在模块中声明的类:仓库、服务、用例、ViewModel。Koin 会通过构造函数传递它们的依赖项。
Activity、Fragment和Service:Koin Android 直接在它们上面提供了by inject()和by viewModel()。- Composable:使用
koinInject(),参见 Koin for Compose。
使用 KoinComponent
实现该接口,然后调用 get() 或 by inject():
import org.koin.core.component.KoinComponent
import org.koin.core.component.get
import org.koin.core.component.inject
class SyncCommand : KoinComponent {
// 惰性加载:首次访问时解析
private val syncService: SyncService by inject()
// 立即加载:创建 SyncCommand 时解析
private val logger: Logger = get()
fun run() {
logger.info("Starting sync")
syncService.sync()
}
}
fun main() {
startKoin {
modules(appModule)
}
SyncCommand().run()
}无论采用哪种编写风格,代码都是相同的:KoinComponent 仅用于检索实例,定义可以使用任意风格进行声明。
get() 和 inject() 是扩展函数:从 org.koin.core.component 导入它们。它们接受限定符和形参代码块,就像所有检索函数一样(参见 Injection)。
KoinComponent 本身只有一个函数 getKoin(),它返回 Koin 实例。其他所有操作都可以通过它完成:
class FeatureLoader : KoinComponent {
fun optionalTracker(): Tracker? = getKoin().getOrNull()
fun apiUrl(): String = getKoin().getProperty("server_url", "https://api.example.com")
fun allPlugins(): List<Plugin> = getKoin().getAll()
}可空检索和 getAll() 在 Injection 中有详细介绍。属性在 Starting Koin 中有详细介绍。
自定义 Android View
自定义 View 是由布局填充器(layout inflater)创建的,因此 Koin 无法传递构造函数形参。KoinComponent 非常适合此类场景:
class ChartView @JvmOverloads constructor(
context: Context,
attrs: AttributeSet? = null,
) : View(context, attrs), KoinComponent {
private val formatter: ChartFormatter by inject()
fun setData(points: List<DataPoint>) {
val formatted = formatter.format(points)
// 绘制
}
}在 View 中应使用 by inject():布局编辑器在创建视图时并没有运行中的 Koin 容器,在此处如果使用立即加载的 get() 将会失败。
KoinComponent 使用哪个容器
默认情况下,getKoin() 返回通过 startKoin 启动的全局容器。如果尚未调用 startKoin,get() 会抛出 IllegalStateException("KoinApplication has not been started")。
运行自身隔离容器的库或 SDK 可以重写 getKoin() 来返回其专属容器:
object SdkKoinContext {
val koinApp = koinApplication { modules(sdkModule) }
}
abstract class SdkComponent : KoinComponent {
override fun getKoin(): Koin = SdkKoinContext.koinApp.koin
}
class SdkClient : SdkComponent() {
private val api: SdkApi by inject() // 从 SDK 容器中解析
}完整模式请参阅 Context Isolation。
对于拥有作用域的类,请改为实现 KoinScopeComponent:此时 get() 和 inject() 将从该作用域中解析。参见 Scopes。
为什么更推荐构造函数注入
比较同一个类的两个版本:
// 依赖于 Koin,依赖项隐藏在类体中
class UserService : KoinComponent {
private val repository: UserRepository by inject()
}
// 普通 Kotlin 类,依赖项在构造函数中清晰可见
class UserService(private val repository: UserRepository)
val appModule = module {
single<UserRepository>()
single<UserService>()
}// 依赖于 Koin,依赖项隐藏在类体中
class UserService : KoinComponent {
private val repository: UserRepository by inject()
}
// 普通 Kotlin 类,依赖项在构造函数中清晰可见
@Singleton
class UserService(private val repository: UserRepository)// 依赖于 Koin,依赖项隐藏在类体中
class UserService : KoinComponent {
private val repository: UserRepository by inject()
}
// 普通 Kotlin 类,依赖项在构造函数中清晰可见
class UserService(private val repository: UserRepository)
val appModule = module {
singleOf(::UserRepository)
singleOf(::UserService)
}构造函数版本在四个方面更具优势:
- 依赖项清晰可见:构造函数直接列出该类所需的内容。使用
KoinComponent时,则必须查阅类体。 - 脱离 Koin 运行测试:你可以直接创建
UserService(FakeUserRepository())。而KoinComponent版本则需要一个包含假定义的运行中容器。 - 构建时检查:编译器插件会根据依赖图验证所声明类的构造函数依赖项。
- 无框架耦合:该类无需 Koin 即可编译和运行,这对共享代码和库来说尤为重要。
请尽量让 KoinComponent 保留在边缘边界处。由一个入口点检索顶层对象,其下的所有层级均使用构造函数注入:
class SyncCommand : KoinComponent {
private val syncService: SyncService by inject()
}
class SyncService(private val repository: UserRepository, private val api: ApiClient)
class UserRepository(private val database: Database)测试 KoinComponent
实现 KoinComponent 的类会从全局容器中读取内容,因此测试必须使用所需的定义启动 Koin,并在测试结束后将其停止:
class SyncCommandTest : KoinTest {
@get:Rule
val koinTestRule = KoinTestRule.create {
modules(module {
single<SyncService> { FakeSyncService() }
single<Logger> { TestLogger() }
})
}
@Test
fun `run calls sync`() {
SyncCommand().run()
// 对 FakeSyncService 进行断言
}
}KoinTestRule 会在每次测试之前启动 Koin,并在测试之后将其停止。规则、模拟(mocking)和模块验证相关内容请参阅 Testing。
相关内容
- Injection:
get()、inject()、可空检索和getAll()。 - Android Entry Points:了解哪些 Android 类需要
KoinComponent,哪些不需要。 - Context Isolation:将
KoinComponent指向隔离容器。 - Scopes:适用于拥有作用域的类的
KoinScopeComponent。 - Testing:测试使用 Koin 的类。
