R8 / ProGuard
本文介绍了 Koin 在代码缩减与混淆(R8 / ProGuard)下的行为表现、Koin 为你保留的内容,以及你需要在自己的应用中保留的内容。
TL;DR
- Koin 的核心解析对 R8 是安全的。
get<T>()、inject<T>()以及*Of构建器(singleOf、factoryOf、viewModelOf……)均在编译时解析依赖项——它们使用具体化类型(reified types),并且在 Android/JVM 上使用Class.getName()作为注册表的键。不会在运行时对你的构造函数进行反射,因此你不需要为了 Koin 而保留你的定义、ViewModel 或它们的构造函数。 - Koin 在其 Android AAR(
koin-android、koin-core-viewmodel、koin-compose-viewmodel、koin-androidx-workmanager、koin-androidx-startup)中附带了consumer-rules.pro,因此下列规则会自动应用——通常无需你手动添加任何规则。 - 你仍然需要保留其他组件通过反射加载的类(见下文)。
Koin 为你保留的内容(附带的 consumer rules)
AAR 会屏蔽有关 Koin 内部代码的 R8 警告:
-dontwarn org.koin.**koin-androidx-startup 还会额外保留其在清单(manifest)中引用的初始化程序。这些规则都不会保留你的应用程序类——Koin 并不需要保留它们。
你必须保留的内容
这些规则源自平台/依赖库本身,而非来自 Koin 的解析机制:
- 由
KoinFragmentFactory创建的 Fragment 是通过类名进行实例化的。请保留你的 Fragment 子类(通常它们已经通过@Keep、布局引用或 AndroidX 规则保留了)。 - WorkManager
ListenableWorker子类由androidx.work自身的 consumer rules 保留。 - 针对进程终止的已保存状态(Saved state)。
SavedStateHandle是由 androidx 的CreationExtras提供的,而不是由 Koin 提供的。你放入其中的值必须像其他已保存状态一样在经过 R8 处理后仍然保留——请保留你自己的@Parcelize/Serializable状态类:
# 示例 — 保留你自己的已保存状态有效负载 (payload)
-keep class com.example.** implements android.os.Parcelable { *; }ViewModel 与 SavedStateHandle (#2044)
一种常见的误解是,间歇性出现的 No definition found for SavedStateHandle 崩溃是由 R8 剥离了 Koin 的 ViewModel 反射所致。事实并非如此——viewModelOf(::MyViewModel) 是在编译时确定的,因此在你的 ViewModel 上添加 -keep 并不会改变 Koin 的解析方式。
SavedStateHandle 仅在创建 ViewModel 的过程中可用(它是根据传递给工厂的 CreationExtras 构建的)。请直接在 ViewModel 构造函数中解析它——不要延迟解析或在构造完成后解析:
// ✅ 在创建期间解析
class MyViewModel(val handle: SavedStateHandle) : ViewModel()
// ❌ 稍后解析 — 届时 CreationExtras 已不复存在
class MyViewModel(koin: Koin) : ViewModel() {
val handle by lazy { koin.get<SavedStateHandle>() } // 失败
}如果你在 viewModelScope { } 内声明 ViewModel,请启用相应的选项以允许创建作用域:
startKoin {
options(viewModelScopeFactory())
modules(appModule)
}非 Android 目标平台 (JS / WASM / Native)
在 Android/JVM 上,Koin 使用 Class.getName() 作为注册表的键,这在 R8 下是稳定的。在 Kotlin/JS、WASM 和 Native 上,Koin 使用来自 Kotlin 反射的 qualifiedName / simpleName。在这些目标平台上进行激进的代码压缩混淆可能会影响类型标识——在压缩非 Android 目标平台时,建议优先使用命名限定符(named("...")),而非依赖类名。
