模块
模块用于按功能或按层次对相关的定义进行分组。本页面介绍如何声明模块、组合模块、扫描包以查找带注解的类、跨 Gradle 模块发现模块,以及模块的加载顺序。有关模块内部的定义,请参阅定义。
声明模块
import org.koin.dsl.module
import org.koin.plugin.module.dsl.*
val networkModule = module {
single<ApiClient>()
single<TokenManager>()
}
val dataModule = module {
single<Database>()
single<UserRepository>()
}@Module
@ComponentScan("com.myapp.network")
class NetworkModule
@Module
@ComponentScan("com.myapp.data")
class DataModule@Module 类会收集由 @ComponentScan 发现的带注解类,以及在其内部声明的提供者函数(请参阅非自有的类)。
import org.koin.dsl.module
import org.koin.core.module.dsl.*
val networkModule = module {
singleOf(::ApiClient)
singleOf(::TokenManager)
}
val dataModule = module {
singleOf(::Database)
singleOf(::UserRepository)
}一个定义可以依赖于来自另一个模块的定义。Koin 会跨所有已加载的模块进行解析,因此 dataModule 中的 UserRepository 可以使用 networkModule 中的 ApiClient,而无需在模块之间进行任何导入。但两个模块都必须已被加载,请参阅启动 Koin。
使用 includes() 组合模块
模块可以包含其他模块。加载父模块即可加载整棵树:
val networkModule = module {
single<ApiClient>()
}
val storageModule = module {
single<Database>()
}
val dataModule = module {
includes(networkModule, storageModule)
single<UserRepository>()
}
startKoin {
modules(dataModule)
}@Module
class NetworkModule
@Module
class StorageModule
@Module(includes = [NetworkModule::class, StorageModule::class])
@ComponentScan("com.myapp.data")
class DataModule
@KoinApplication(modules = [DataModule::class])
class MyAppval networkModule = module {
singleOf(::ApiClient)
}
val storageModule = module {
singleOf(::Database)
}
val dataModule = module {
includes(networkModule, storageModule)
singleOf(::UserRepository)
}
startKoin {
modules(dataModule)
}相比在 startKoin 中传入冗长的扁平列表,更推荐使用带有单个根模块的 includes() 树形结构。这样模块的结构就可以契合代码的结构,且启动调用也保持简洁。
即使多个父模块包含了同一个模块,Koin 也会将树展开并仅加载每个模块一次:
val commonModule = module {
single<Logger>()
}
val featureAModule = module {
includes(commonModule)
single<FeatureA>()
}
val featureBModule = module {
includes(commonModule)
single<FeatureB>()
}
val appModule = module {
includes(featureAModule, featureBModule) // commonModule 仅加载一次
}多模块项目中的可见性
在 Gradle 多模块项目中,建议为每个功能公开一个公共模块,其余模块保持 private 或 internal:
// Gradle 模块 "feature-user"
private val userDataModule = module {
single<UserDao>()
single<UserCache>()
}
val userFeatureModule = module {
includes(userDataModule)
viewModel<UserViewModel>()
}应用模块只需加载 userFeatureModule,并且永远不会感知到其内部模块。有关拆分为 Gradle 模块的 Android 应用完整布局,请参阅多模块应用。
使用 @ComponentScan 扫描包
@ComponentScan 仅适用于注解方式。它会收集某个包及其子包中的所有带注解类和顶层函数:
@Module
@ComponentScan
class AppModule // 扫描 AppModule 所在的包
@Module
@ComponentScan("com.myapp.features")
class FeatureModule
@Module
@ComponentScan("com.myapp.data", "com.myapp.network")
class InfraModule如果不提供任何值,它将扫描被注解类所在的包。该扫描可以跨越 Gradle 模块:来自同一包中其他 Gradle 模块的类也会被发现。
对于 DSL 风格,你需要自行在模块中列出每个定义。如果想混合使用两者,只需在启动代码块中将 DSL 模块与带注解的模块一起包含即可(请参阅使用 @KoinApplication 进行类型化启动)。
使用 @Configuration 实现自动发现
@Configuration 用于标记 @Module,以便 @KoinApplication 无需显式列出即可发现它。该模块可以位于类路径上的任何 Gradle 模块中:
// Gradle 模块 "feature-user"
@Module
@Configuration
@ComponentScan("com.myapp.feature.user")
class UserFeatureModule
// Gradle 模块 "app"
@KoinApplication
class MyApp
fun main() {
startKoin<MyApp>() // 加载 UserFeatureModule
}这样添加功能就只需添加 Gradle 依赖项即可:无需更改应用的模块列表。代价是加载的模块列表不再集中记录在一处。如果你希望显式指定,可以在 @KoinApplication(modules = [...]) 中列出这些模块。
@Configuration 支持标签,因此你可以针对不同环境或渠道(flavor)加载不同的模块。相关规则见配置标签。
@Configuration 仅适用于注解,并且需要配合使用类型化启动(startKoin<MyApp>())的 @KoinApplication。
加载顺序与覆盖
当两个已加载的模块声明了相同的类型时,后加载的模块优先。在 DSL 启动代码块中,这取决于 modules(...) 的顺序:
startKoin {
modules(productionModule, debugModule) // debugModule 的 ApiService 胜出
}使用 @KoinApplication 时,编译器插件按以下顺序构建模块列表:
- 它发现的
@Configuration模块(来自你的代码和依赖项)。 - 在
@KoinApplication(modules = [...])中列出的模块,按声明顺序加载。
因此,你的应用模块会覆盖库的默认配置:
// 在库中
@Module
@Configuration
class CoreModule {
@Singleton
fun feature(): Feature = DefaultFeature()
}
// 在应用中
@Module
class AppModule {
@Singleton
fun feature(): Feature = AppFeature()
}
@KoinApplication(modules = [AppModule::class])
class MyApp // get<Feature>() 返回 AppFeature在显式列表中,modules = [A::class, B::class, C::class] 会依次加载 A、B、C,且每个模块的 includes 保持与其归组在一起。既被显式列出又被 @Configuration 发现的模块只会被加载一次,位置取决于它在显式列表中的位置。如需控制多个 @Configuration 模块之间的顺序,请显式列出它们。
若要在启动时对意外的覆盖直接报错,请使用 allowOverride(false)。有关覆盖单个定义的规则,请参阅覆盖定义。
预加载模块
可以标记整个模块,使其在 Koin 启动时创建其所有的 single 定义:
val coreModule = module(createdAtStart = true) {
single<ConfigManager>()
single<CrashReporter>()
}@Module(createdAtStart = true)
@ComponentScan("com.myapp.core")
class CoreModuleval coreModule = module(createdAtStart = true) {
singleOf(::ConfigManager)
singleOf(::CrashReporter)
}每个预加载定义都会增加启动时间。有关单个定义的标志及其开销,请参阅预加载创建。
参数化模块
DSL 模块是一个值,因此可以通过函数传入实参来构建它:
fun loggingModule(debug: Boolean) = module {
if (debug) {
single<DebugLogger>() bind Logger::class
} else {
single<ReleaseLogger>() bind Logger::class
}
}
startKoin {
modules(loggingModule(debug = BuildConfig.DEBUG))
}@Module 类不接受实参。对于这种情况,请使用 DSL 模块,或者为每个变体定义一个 @Module 并通过配置标签进行选择。
fun loggingModule(debug: Boolean) = module {
single<Logger> {
if (debug) DebugLogger() else ReleaseLogger()
}
}
startKoin {
modules(loggingModule(debug = BuildConfig.DEBUG))
}同样的思路也可用于替换实现:保持 repositoryModule 不变,并根据需要在其旁边加载 localDatasourceModule 或 remoteDatasourceModule,两者各自声明一个 Datasource。条件模块列表是在运行时解析的,因此编译器插件无法在构建时验证所有组合。
