在 Android 上启动 Koin
本页介绍如何在 Android 应用中启动 Koin:Application 类、Android Context、Logcat 日志记录器、来自 assets 的属性、启动后加载模块以及 AndroidX App Startup。本文假设你的构建配置中已包含 io.insert-koin:koin-android 依赖项(请参阅 Gradle 设置)。关于 startKoin 在各平台上的作用,请参阅启动 Koin。
在 Application 类中启动 Koin
在 Application.onCreate() 中启动一次 Koin:
import org.koin.android.ext.koin.androidContext
import org.koin.android.ext.koin.androidLogger
import org.koin.core.context.startKoin
class MainApplication : Application() {
override fun onCreate() {
super.onCreate()
startKoin {
androidLogger()
androidContext(this@MainApplication)
modules(appModule)
}
}
}appModule 是使用编译器插件 DSL(single<UserRepository>()、viewModel<UserViewModel>())声明的 module { }。
import org.koin.android.ext.koin.androidContext
import org.koin.android.ext.koin.androidLogger
import org.koin.core.annotation.KoinApplication
import org.koin.plugin.module.dsl.startKoin
@KoinApplication
class MainApplication : Application() {
override fun onCreate() {
super.onCreate()
startKoin<MainApplication> {
androidLogger()
androidContext(this@MainApplication)
}
}
}startKoin<MainApplication>() 会加载每个带有 @Configuration 标记的 @Module 类。你无需自行列出模块。若要显式选取模块,请使用 @KoinApplication(modules = [AppModule::class])。模块发现机制在模块中进行了说明。
import org.koin.android.ext.koin.androidContext
import org.koin.android.ext.koin.androidLogger
import org.koin.core.context.startKoin
class MainApplication : Application() {
override fun onCreate() {
super.onCreate()
startKoin {
androidLogger()
androidContext(this@MainApplication)
modules(appModule)
}
}
}在 AndroidManifest.xml 中的 <application> 标记上使用 android:name=".MainApplication" 注册该类,否则 Android 绝不会运行它。
androidContext() 将 Application 实例添加到 Koin 中,同时绑定到 Application 和 Context。请在任何需要 Context 的选项(如 androidFileProperties() 或 workManagerFactory())之前调用它。
定义中的 Android Context
需要 Context 的类在其构造函数中声明它即可。不需要限定符:Koin 会将 Context 解析为传递给 androidContext() 的实例。
class PreferencesStore(private val context: Context)
class NotificationHelper(private val application: Application)
val androidModule = module {
single<PreferencesStore>()
single<NotificationHelper>()
}@Singleton
class PreferencesStore(private val context: Context)
@Singleton
class NotificationHelper(private val application: Application)val androidModule = module {
singleOf(::PreferencesStore)
singleOf(::NotificationHelper)
}在 lambda 表达式定义中,使用 androidContext() 和 androidApplication() 读取它们:single { PreferencesStore(androidContext()) }。
| 函数 | 返回值 | 失败情况 |
|---|---|---|
androidContext() | 最近的 Context:Application,或 Activity 作用域中的 Activity | 启动时未提供 androidContext()(MissingAndroidContextException) |
androidApplication() | 始终为 Application 实例 | 未向 androidContext() 提供 Application |
两个函数都是来自 org.koin.android.ext.koin 的 get<Context>() 和 get<Application>() 的快捷方式。
你会获取到哪个 Context
在 single 或从根作用域解析的任何定义中,Context 为 Application。对于生命周期与应用相同长的对象,这是安全的。
在从 Activity 作用域解析的定义中,Context 会优先解析为 Activity,因为该 Activity 是该作用域的来源。具有作用域的 presenter 就是通过这种方式获取 Activity 的。请参阅 Android 作用域。
Activity 上下文
不要将 Activity 声明为 single 的依赖项:单例会在 Activity 销毁后仍保持其存活,从而导致 Activity 泄漏。当类需要 Activity(屏幕度量、对话框)时,请在 Activity 中创建它、将 Activity 作为注入形参传递,或在 Activity 作用域中声明它:
class ScreenMetrics(private val activity: Activity) {
fun screenWidth(): Int = activity.resources.displayMetrics.widthPixels
}
class MainActivity : AppCompatActivity() {
override fun onCreate(savedInstanceState: Bundle?) {
super.onCreate(savedInstanceState)
val metrics = ScreenMetrics(this)
}
}同一 Android 类型的多个实例
当两个定义共享相同类型时(例如两个 SharedPreferences 文件),使用限定符来区分它们:
val preferencesModule = module {
single(named("settings")) {
androidContext().getSharedPreferences("settings", Context.MODE_PRIVATE)
}
single(named("session")) {
androidContext().getSharedPreferences("session", Context.MODE_PRIVATE)
}
}@Module
class PreferencesModule {
@Singleton
@Named("settings")
fun settings(context: Context): SharedPreferences =
context.getSharedPreferences("settings", Context.MODE_PRIVATE)
@Singleton
@Named("session")
fun session(context: Context): SharedPreferences =
context.getSharedPreferences("session", Context.MODE_PRIVATE)
}val preferencesModule = module {
single(named("settings")) {
androidContext().getSharedPreferences("settings", Context.MODE_PRIVATE)
}
single(named("session")) {
androidContext().getSharedPreferences("session", Context.MODE_PRIVATE)
}
}日志记录
androidLogger() 将 Koin 日志发送到 Logcat。默认级别为 Level.INFO:
startKoin {
androidLogger(Level.DEBUG)
androidContext(this@MainApplication)
modules(appModule)
}Level.DEBUG 会记录每次解析及其持续时间,这有助于调试缺失的定义。它也会降低解析速度,因此请仅在调试构建中保留它:androidLogger(if (BuildConfig.DEBUG) Level.DEBUG else Level.ERROR)。其他日志记录器列在启动 Koin中。
来自 assets 的属性
androidFileProperties() 从 src/main/assets 中的文件加载 Koin 属性。默认文件名为 koin.properties:
startKoin {
androidContext(this@MainApplication)
androidFileProperties() // assets/koin.properties
// androidFileProperties("app.properties")
modules(appModule)
}它通过 Context 读取文件,因此请在 androidContext() 之后调用它。如果文件缺失,Koin 会记录该日志并继续运行。要在定义中读取属性,请参阅启动 Koin。
启动后加载模块
loadKoinModules() 和 unloadKoinModules() 在应用运行时添加或移除模块。在 Android 上,这适用于仅在少数几个屏幕中使用的功能:
private val premiumModules = lazy { loadKoinModules(premiumModule) }
class PremiumActivity : AppCompatActivity() {
override fun onCreate(savedInstanceState: Bundle?) {
premiumModules.value
super.onCreate(savedInstanceState)
}
}- 在
super.onCreate()之前加载:这样系统恢复的 Fragment 就可以找到它们的依赖项。 - 每个进程加载一次:再次加载同一模块将重新注册其定义,记录一条覆盖警告,并且如果 Koin 在
allowOverride(false)下运行则会失败。 - 谨慎卸载:
unloadKoinModules(premiumModule)会丢弃模块定义及其实例。仅在不再需要该功能时卸载,切勿在配置变更时卸载;如果稍后再次加载它,请自行跟踪已加载状态。
延迟模块
在大型应用中,在 Application.onCreate() 中加载每个模块会增加主线程的启动时间。lazyModules() 会在后台线程上加载使用 lazyModule { } 标记的模块,而首屏所需的模块则使用 modules() 加载。配置、等待完成以及限制条件请参阅延迟模块。
使用 AndroidX App Startup 启动
AndroidX App Startup 在 Application.onCreate() 之前通过单个 ContentProvider 运行初始化程序。io.insert-koin:koin-androidx-startup 构件将 Koin 作为这些初始化程序之一来启动。在你的 Application 中实现 KoinStartup 并从 onKoinStartup() 返回配置:
import org.koin.androix.startup.KoinStartup
import org.koin.dsl.koinConfiguration
@OptIn(KoinExperimentalAPI::class)
class MainApplication : Application(), KoinStartup {
override fun onKoinStartup() = koinConfiguration {
androidContext(this@MainApplication)
modules(appModule)
}
}import org.koin.androix.startup.KoinStartup
import org.koin.plugin.module.dsl.koinConfiguration
@KoinApplication
@OptIn(KoinExperimentalAPI::class)
class MainApplication : Application(), KoinStartup {
override fun onKoinStartup() = koinConfiguration<MainApplication> {
androidContext(this@MainApplication)
}
}import org.koin.androix.startup.KoinStartup
import org.koin.dsl.koinConfiguration
@OptIn(KoinExperimentalAPI::class)
class MainApplication : Application(), KoinStartup {
override fun onKoinStartup() = koinConfiguration {
androidContext(this@MainApplication)
modules(appModule)
}
}KoinStartup 取代了 onCreate() 中的 startKoin 调用:不要同时调用两者。包名为 org.koin.androix.startup(采用此拼写),且该 API 标记为 @KoinExperimentalAPI。
如果另一个初始化程序需要 Koin,请让它依赖 KoinInitializer。App Startup 本身会创建初始化程序,因此初始化程序是一个入口点:它实现 KoinComponent 来检索其依赖项。
class CrashTrackerInitializer : Initializer<Unit>, KoinComponent {
private val crashTracker: CrashTracker by inject()
override fun create(context: Context) {
crashTracker.configure(context)
}
override fun dependencies(): List<Class<out Initializer<*>>> =
listOf(KoinInitializer::class.java)
}WARNING
KoinStartup 仍然在应用启动期间运行在主线程上。它不会让 Koin 启动得更快。仅使用它来编排 Koin 与其他 App Startup 初始化程序的顺序。要将模块加载移出主线程,请使用延迟模块。
在 Application 类之外启动 Koin
只要每个进程运行一次且在首次注入之前运行,你就可以从另一个类调用 startKoin。请传递 application context,而不是 Activity:
startKoin {
androidContext(context.applicationContext)
modules(appModule)
}startKoin 会注册一个全局实例。自带 Koin 设置的库或 SDK 不应使用它,因为这会与宿主应用发生冲突:请改用隔离的上下文(请参阅上下文隔离)。
相关内容
- 启动 Koin:各平台上的
startKoin选项、日志记录器和属性。 - Android 入口点:在 Activity、Fragment、Service 和其他组件中注入。
- Android 作用域:将实例绑定到 Activity 或 Fragment 生命周期。
- 模块:组织定义并使用
@Configuration发现机制。 - 延迟模块:在后台加载模块。
- 多模块应用:跨 Gradle 模块组织 Koin 模块。
