核心概念
本页通过逐步构建一个小示例,解释贯穿所有其他页面的核心理念:定义、模块、Koin 容器、受限标识符、作用域、限定符以及编译时检查。每个章节都很简短,并链接到包含详细内容的页面。本文假设你已了解什么是 SQL 注入(请参阅什么是 SQL 注入?)。
代码示例分为三个标签页:Compiler Plugin DSL、Annotations、Constructor / Classic DSL。选择适合你的风格,该选择将适用于所有页面。如果你不确定该使用哪种风格,请阅读选择你的风格。
示例
三个普通的 Kotlin 类。每个类都在其构造函数中接收所需的依赖项,并且对 Koin 一无所知:
class ApiService
class UserRepository(private val api: ApiService)
class UserViewModel(private val repository: UserRepository) : ViewModel()Koin 的工作就是创建 ApiService,将其传递给 UserRepository,再将其传递给 UserViewModel,无需你手动编写装配代码。
定义
定义会告诉 Koin 如何创建某个类型以及该实例的保留时间:
single<ApiService>()
single<UserRepository>()
viewModel<UserViewModel>()@Singleton
class ApiService
@Singleton
class UserRepository(private val api: ApiService)
@KoinViewModel
class UserViewModel(private val repository: UserRepository) : ViewModel()singleOf(::ApiService)
singleOf(::UserRepository)
viewModelOf(::UserViewModel)关键字用于设置生命周期。single 在整个容器中只保留一个实例。factory 在每次请求时都会创建一个新实例。viewModel 遵循 ViewModel 生命周期。Koin 读取 UserRepository 的构造函数,发现它需要一个 ApiService,并从容器中解析它。
详情:定义。
模块
模块用于对定义进行分组。通常每个功能或每个层对应一个模块:
import org.koin.dsl.module
import org.koin.plugin.module.dsl.*
val appModule = module {
single<ApiService>()
single<UserRepository>()
viewModel<UserViewModel>()
}@Module
@ComponentScan("com.example.app")
class AppModule@ComponentScan 会收集 com.example.app 软件包及其子包中所有带有注解的类。
import org.koin.dsl.module
import org.koin.core.module.dsl.*
val appModule = module {
singleOf(::ApiService)
singleOf(::UserRepository)
viewModelOf(::UserViewModel)
}模块只是一种描述。在 Koin 启动并且有人请求实例之前,不会创建任何内容。模块可以包含其他模块,因此大型应用是由小型模块构成的树。
详情:模块。
Koin 容器
startKoin 会创建容器(一个 KoinApplication)并将你的模块加载到其中。你在应用的入口点调用它一次:
fun main() {
startKoin {
modules(appModule)
}
}import org.koin.plugin.module.dsl.startKoin
@KoinApplication(modules = [AppModule::class])
class MyApp
fun main() {
startKoin<MyApp>()
}fun main() {
startKoin {
modules(appModule)
}
}在 Android 上,你在 Application.onCreate() 中调用它,并通过 androidContext(this) 传递 Android 上下文。容器持有已有的定义以及到目前为止创建的实例。stopKoin() 会关闭容器并释放所有的 single。
详情:启动 Koin 和 在 Android 上启动 Koin。
受限标识符
对象获取其依赖项的方式有两种。
构造函数受限标识符:依赖项是一个构造函数形参,Koin 在创建对象时会将其传入。本示例中的 UserRepository 和 UserViewModel 已经采用了这种方式。这是默认做法:类保持为普通的 Kotlin 类,并且你可以通过使用伪造对象调用构造函数来进行单元测试。
从容器中检索:某些类是由框架创建的,而不是由 Koin 创建的(例如 Android 的 Activity、Composable、Ktor 路由)。它们通过 get()(立即)或 inject()(延迟,首次访问时)向容器请求:
import org.koin.androidx.viewmodel.ext.android.viewModel
class UserActivity : AppCompatActivity() {
private val viewModel: UserViewModel by viewModel()
}import org.koin.compose.viewmodel.koinViewModel
@Composable
fun UserScreen(viewModel: UserViewModel = koinViewModel()) {
...
}检索在每种风格中都是相同的。将其保留在这些入口点:它们之下的所有内容均使用构造函数受限标识符。
详情:检索依赖项、Android 入口点、适用于 Compose 的 Koin。
图
综合起来,容器持有以下依赖图:
startKoin
└── appModule
├── single ApiService
├── single UserRepository ── needs ── ApiService
└── viewModel UserViewModel ── needs ── UserRepository
UserActivity ── by viewModel() ──> UserViewModel当 UserActivity 请求 UserViewModel 时,Koin 会先创建 ApiService(一次),然后创建 UserRepository(一次),最后创建与 Activity 的 ViewModel 生命周期绑定的 UserViewModel。
作用域
single 的存活时间与容器相同,factory 的存活时间取决于调用者保留它的时间。作用域涵盖了介于两者之间的场景:存活时间与某些其他事物相同的实例,例如用户会话、屏幕或请求。
假设 CartRepository 应该仅在用户登录期间存在:
class UserSession
class CartRepository(private val api: ApiService)
val sessionModule = module {
scope<UserSession> {
scoped<CartRepository>()
}
}class UserSession
@Scope(UserSession::class)
@Scoped
class CartRepository(private val api: ApiService)class UserSession
class CartRepository(private val api: ApiService)
val sessionModule = module {
scope<UserSession> {
scopedOf(::CartRepository)
}
}你在会话开始时打开该作用域,并在会话结束时将其关闭:
// inside a KoinComponent
val sessionScope = getKoin().createScope<UserSession>("session-42")
val cart: CartRepository = sessionScope.get()
sessionScope.close() // releases CartRepository作用域定义可以使用来自根容器的定义(此处为 ApiService)。在 Android 上,Koin 为 Activity、Fragment 和 ViewModel 提供了开箱即用的作用域,因此你很少需要手动创建作用域。
详情:作用域 和 Android 作用域。
限定符
Koin 通过类型查找定义。当两个定义提供相同的类型时,限定符会为每个定义指定一个名称:
interface NetworkClient
@Named("auth")
class AuthClient : NetworkClient
@Named("public")
class PublicClient : NetworkClient
class UserRepository(@Named("auth") private val client: NetworkClient)
val networkModule = module {
single<AuthClient>() bind NetworkClient::class
single<PublicClient>() bind NetworkClient::class
single<UserRepository>()
}@Singleton
@Named("auth")
class AuthClient : NetworkClient
@Singleton
@Named("public")
class PublicClient : NetworkClient
@Singleton
class UserRepository(@Named("auth") private val client: NetworkClient)val networkModule = module {
single<NetworkClient>(named("auth")) { AuthClient() }
single<NetworkClient>(named("public")) { PublicClient() }
single { UserRepository(get(named("auth"))) }
}详情:限定符。
编译时检查
若不使用编译器插件,缺失定义的情况只会在代码运行时暴露:get() 会抛出 NoDefinitionFoundException。而使用 Koin 编译器插件时,同样的错误会导致构建失败。如果从 appModule 中移除 single<ApiService>(),编译将中断并显示:
[Koin][KOIN-D001] Missing dependency: ApiService
required by: UserRepository (parameter 'api')
in module: ...该插件会在每个入口点(startKoin、@KoinApplication、Ktor 的 install(Koin))以及每次调用 get()、inject() 或 koinViewModel() 时检查完整图。如果不使用插件并采用 Constructor 或 Classic DSL,你可以在单元测试中通过 verify() 获得类似的检查。
详情:编译时安全性、验证你的 Koin 配置。
