适用于 SDK 与库的 Koin
Koin Embedded 允许 SDK 和库开发者在不同的软件包名称下打包重定位版本的 Koin。这样一来,您的库在内部使用的 Koin 就不会与应用程序中其他任何地方使用的 Koin 发生冲突。本页面面向库作者。对于常规应用程序,请使用标准 Koin。
获取重定位的 Koin 有两种方式:自助方式(使用预构建构件或重定位脚本),或者 Koin Embedded LTS(由 Kotzilla 作为企业支持的一部分,为您构建、签名、托管和维护专用版本)。
冲突问题
内部使用 Koin 的库会将 org.koin.* 作为其依赖图的一部分进行发布。这会带来两种冲突风险,而第二种往往会被忽略。
情况 1:与宿主应用程序冲突
接入您 SDK 的应用程序也在使用 Koin,并且拥有其自身的发布计划:
// 您的 SDK 使用 Koin 3.5.6
implementation("io.insert-koin:koin-core:3.5.6")
// 使用者应用使用 Koin 4.2.2
implementation("io.insert-koin:koin-core:4.2.2")
// 冲突:Gradle 为两者解析同一个版本这会导致的问题:
- 所有人共用一个版本:Gradle 会为整个应用程序选择单一的
org.koin版本,因此双方中总有一方运行在从未测试过的版本上。 - 运行时故障:版本之间的 API 变更会在运行时发生中断错误。
- 强制升级:您的 SDK 会强制其使用者升级 Koin,或者阻碍其升级。
情况 2:与其他 SDK 冲突
您的 SDK 很少是应用程序中唯一的 SDK。如果另一个供应商的 SDK 也嵌入了 Koin,双方就会发生冲突,而且谁都无法控制对方的发布周期:
// 应用集成了两个 SDK,两者内部均使用 Koin
implementation("com.vendor-a:analytics-sdk:2.1.0") // 嵌入了 Koin 3.5.6
implementation("com.vendor-b:payments-sdk:5.0.0") // 嵌入了 Koin 4.2.2
// 同样的冲突,且链条中的任何一方都无法修复它这就是为什么共享重定位命名空间还不够的原因。脱离 org.koin.* 并迁移到每个嵌入者共享的命名空间,只会转移冲突的发生地:重定位到相同目标的两个 SDK 依然会像以前一样发生冲突。您需要一个专属于您自己的命名空间。
软件包重定位
重定位会将 Koin 的软件包重写到不同的命名空间中,并将其重新构建为一个独立的构件:
// 重定位前
import org.koin.core.module.dsl.singleOf
import org.koin.core.context.startKoin
// 重定位后
import acme.koin.core.module.dsl.singleOf
import acme.koin.core.context.startKoin两个命名空间代表两组不同的类,因此它们可以并存而不会产生解析冲突:
// 您的 SDK 打包了自身重定位后的 Koin
implementation("io.insert-koin:acme-koin-core:3.5.6")
// 使用者应用使用标准 Koin
implementation("io.insert-koin:koin-core:4.2.2")
// 无冲突:两个独立的软件包WARNING
请勿在常规应用程序开发中使用嵌入式 Koin。它专为需要避免依赖冲突的库作者(支付、分析或身份验证 SDK、共享内部库、第三方集成)而设计。
预构建的嵌入式版本
Kotzilla 维护了重定位到共享命名空间 embedded.koin.* 的预构建构件:embedded-koin-core 和 embedded-koin-android。访问权限按需提供:请联系 Koin 团队。
WARNING
这些构件处于 Beta 阶段,并使用共享命名空间。它们仅供评估使用,不适用于已发布的 SDK。每个使用者都重定位到相同的 embedded.koin.* 命名空间,因此在一个应用程序中基于它们构建的两个 SDK 会像在 org.koin.* 上一样发生冲突(参见情况 2)。可以使用它们来尝试重定位,或用于您能端到端控制的内部构建。若要向第三方交付 SDK,请使用重定位脚本自行重定位,或使用 Koin Embedded LTS。
自定义重定位
若要获得完全专属于您自己的命名空间,请使用重定位脚本自行重新构建 Koin。
WARNING
这些脚本是一项处于 Beta 阶段的计划,按原样提供,不提供维护保证。脚本下游的所有事务均由您自行承担:构建、验证、发布,以及在未来的每个 Koin 版本(包含安全修复)发布时重新构建。
使用重定位脚本
koin-relocate 项目提供了使用自定义软件包名称重新构建 Koin 的脚本。重定位由前缀驱动,该前缀同时应用于软件包和模块名称:
RELOCATION_PREFIX=acme -> org.koin.* 变为 acme.koin.*
koin-core 变为 acme-koin-core步骤:
克隆重定位脚本仓库:
bashgit clone https://github.com/InsertKoinIO/koin-relocate.git cd koin-relocate编辑
relocate.properties以配置构建:propertiesRELOCATION_PREFIX=acme TARGET_KOIN_VERSION=3.5.6 KOIN_MODULES=core/koin-core;android/koin-android BUILD_DIR=./buildRELOCATION_PREFIX:应用于软件包和模块名称的前缀。TARGET_KOIN_VERSION:用于构建的 Koin 版本标签。KOIN_MODULES:需要重定位的 Koin 模块。BUILD_DIR:复制构建出的构件的目标目录。
运行重定位。它会从源代码克隆并重新构建 Koin,并且需要 JDK 17 环境:
bash./relocate.sh从
BUILD_DIR收集aar和jar构件。所有重定位后的模块也会安装到您的本地 Maven 仓库中,以便您在测试时立即可用。将它们发布到您自己的 Maven 仓库中,以供您的 SDK 构建使用。
有关详细说明,请参阅 koin-relocate 仓库。
自行托管涉及的工作
脚本可以帮助您完成第一次构建。但将重定位后的 Koin 作为交付 SDK 的依赖项来运行,是一项长期的投入。在投入之前,请了解其全貌:
- Koin 的构建结构:重定位会从源代码重新构建 Koin。您将继承其多模块 Gradle 设置、版本目录以及工具链要求,并且需要一个在 CI 中保持可复现的 JDK 17 环境。
- 远不止 package 语句:在 Kotlin 源代码中重写
org.koin是最简单的部分。资源以及诸如META-INF/services条目之类的声明式服务文件也包含完全限定名称。重写遗漏的任何内容都会在运行时失败,而不是在编译时。 - Android 与多平台构件:
koin-android会生成带有独立 Manifest 和使用者规则的aar构件。在 Kotlin Multiplatform 中,每个目标都会发布带有自身元数据的独立构件,并且重定位后的坐标必须在所有目标之间保持一致。 - 发布与签名:脚本会在
io.insert-koin组下生成带有前缀模块名称的构件,并安装到您的本地 Maven 仓库中。将其发布到您控制的仓库中即可满足内部使用。而公开发布则意味着需要承担使用者所期望的 POM 元数据、组所有权和签名,因为重定位后的 Koin 现在已成为您供应链的一部分。 - 验证等效性:重定位后的构建必须与原版表现完全一致。Koin 自身的测试套件是针对
org.koin运行的,因此对于您的 SDK 所使用的那部分 Koin,您需要自行确保解析、作用域界定和生命周期行为在重写后依然正常。 - 在每个 Koin 补丁上重复此过程:您想要的每个上游版本(包括每个安全修复)都意味着需要重新运行重定位、重新构建、验证、签名并发布。一次性的重定位只是一个快照,从您创建它的那一天起就会逐渐过时。
这些都不能作为不自行托管的理由。但它们是让您深思熟虑后再作决定的理由,而不是在收到第三次安全公告时才发现其代价。
Koin Annotations 与编译器插件
WARNING
重定位构建不支持 Koin Annotations 和 Koin 编译器插件。
两者生成的代码都会直接引用 org.koin。这些代码是在编译时在您的项目中生成的,而此时重定位已经发生,因此它针对的是您重定位构建中不再提供的标准 Koin 软件包。脚本不会重定位生成的代码。
在重定位构建中,请使用 Constructor 或 Classic DSL(module { }、single、factory、singleOf、factoryOf)来声明您的模块。
自助方式的局限性
除了 Beta 状态和共享命名空间的限制外,自助方式还存在以下局限:
- 不支持注解:无法使用 Koin Annotations 和编译器插件。
- 支持模块有限:并非所有 Koin 模块都能完全无误地重定位。
- 构建复杂性:重定位意味着需要维护构建、验证和发布流水线。
- 维护成本:Koin 的每一次更新(包括安全修复),都需要您自行重新重定位并发布。
最后一点永远无法避免,而这正是 Koin Embedded LTS 为您代劳之处。
Koin Embedded LTS
Koin Embedded LTS 为您提供专属于您自己的 Koin LTS 版本,无冲突,且获得至少 18 个月的维护支持。它是 Kotzilla 企业支持的一部分。Kotzilla 会为您构建、签名、托管和维护专属的重定位 Koin,无需您自行运行脚本。
专属版本
您将获得一个专供您使用、无其他人共享的专用命名空间。Kotzilla 从维护中的 Koin LTS 分支切出构建,将其重定位到您的命名空间,进行签名,并托管在面向您组织的私有仓库中。您只需添加一个 Maven 仓库,并依赖于您自己的重定位模块即可。
您无需运行重定位脚本、维护构建流水线或发布构件。
无冲突
由于命名空间为您独享,因此对于宿主应用程序以及与您的 SDK 一同发布的任何其他 SDK 而言,无论它们运行哪个 Koin 版本、无论它们是否嵌入了 Koin,您的嵌入式 Koin 都是完全不可见的。两种自助方式都无法做到这一点:预构建构件在其所有用户之间共享同一个命名空间,而自行重定位的命名空间也仅在您持续打补丁期间保持隔离。
18 个月的维护支持
您的构建基于维护中的 LTS 分支,即面向 Kotlin 1.x 的 Koin 3.5.6 或面向 Kotlin 2.x 的 Koin 4.2.x,自指定之日起享有至少 18 个月的维护支持。在您的订阅有效期内,针对您所发布的版本,支持将持续有效。
该分支上的每个补丁(包括安全向后移植)都会重新构建并发布到您的命名空间中。您只需接入自己构件的新版本,无需重新执行重定位。
范围
Koin Embedded LTS 涵盖 koin-core 和 koin-android。
入门指导包括将您迁移至 LTS 补丁级别。如果您目前使用的是该分支的较早版本,该迁移将作为初始设置的一部分进行,无需您先行完成。
NOTE
Embedded LTS 仅从 LTS 分支进行构建。重定位任意 Koin 版本是一次性的:此类构件处于任何受维护的分支之外,因此没有可供重新构建的上游修复流。这就变成了无人打补丁的构件,而将未打补丁的 DI 框架编译进广泛分发的 SDK 中,正是本方案旨在防止的问题。只要您的订阅处于有效状态,LTS 分支就始终会有下一个补丁可供重定位。
请参阅 kotzilla.io 上的 Koin Embedded LTS。
SDK 开发实践
当 Koin 在您的 SDK 内部运行时:
- 保持 Koin 仅在内部使用:它是您 SDK 的实现细节。
- 不要公开 Koin 类型:避免将
KoinComponent、Module以及其他 Koin 类型暴露在 SDK 的公共 API 中。 - 使用隔离实例:使用
koinApplication为您的 SDK 启动独立的 Koin 实例,绝不要使用全局的startKoin。请参阅上下文隔离。 - 固定版本:依赖精确的重定位版本,绝不要使用版本范围。
- 记录该依赖项:在您的 SDK 文档中说明其内部使用了 Koin。
Koin 作为内部细节:
class PaymentSDK private constructor(context: Context) {
companion object {
private var instance: PaymentSDK? = null
fun initialize(context: Context): PaymentSDK {
return instance ?: PaymentSDK(context).also { instance = it }
}
}
private val koinApp = koinApplication {
androidContext(context)
modules(paymentModule)
}
private val paymentService: PaymentService = koinApp.koin.get()
fun processPayment(amount: Double): PaymentResult {
return paymentService.process(amount)
}
}避免在公共 API 中公开 Koin:
// 不要这样做:KoinComponent 和 get() 会泄漏到公共 API 中
class PaymentSDK : KoinComponent {
fun getPaymentService(): PaymentService = get()
}在您的 SDK 文档中,声明该内部依赖项:
## Dependencies
This SDK uses Koin internally (embedded version) for dependency injection.
The embedded version is isolated and will not conflict with Koin usage
in your application.
Internal dependency: `io.insert-koin:acme-koin-core:3.5.6`
Package namespace: `acme.koin.*`将 SDK 迁移到重定位的 Koin
- 替换依赖项:将
io.insert-koin:koin-core替换为您的重定位坐标,例如io.insert-koin:acme-koin-core。 - 更新导入语句:将
import org.koin替换为import acme.koin。 - 使用 DSL 替换注解:如果您的 SDK 使用了 Koin Annotations 或编译器插件,请使用 Constructor 或 Classic DSL 重写这些声明。请参阅 Koin Annotations 与编译器插件。
- 在真实的部署环境中进行测试:在同样使用标准 Koin 的应用程序中进行测试,如果您的 SDK 会遇到其他嵌入 Koin 的 SDK,也要与其并存进行测试。
回滚过程正好相反:恢复标准的 koin-* 坐标和 org.koin 导入语句即可。
故障排除
无法解析重定位构件
Could not find io.insert-koin:acme-koin-core:3.5.6检查重定位构件是否已发布,以及发布该构件的仓库是否已在消费端构建中声明:
repositories {
maven("https://maven.acme.com/releases") // 无论您发布到何处
}运行时出现 ClassNotFoundException
检查您是否在所有地方都使用了重定位后的软件包名称:
// 错误
import org.koin.core.context.startKoin
// 正确
import acme.koin.core.context.startKoin如果缺失的类仅在资源或 META-INF/services 条目中被引用,说明重定位遗漏了非源代码引用。请检查这些文件是否也包含重定位后的名称。
依然存在版本冲突
请勿在同一个模块中混用标准 Koin 与重定位后的 Koin:
// 不要混用
implementation("io.insert-koin:koin-core:3.5.6") // 标准
implementation("io.insert-koin:acme-koin-core:3.5.6") // 重定位
// 仅使用您重定位后的构建
implementation("io.insert-koin:acme-koin-core:3.5.6")与另一个嵌入 Koin 的 SDK 发生冲突
双方都重定位到了相同的命名空间,极大概率是双方都使用了预构建的 embedded.koin.* 构件。其中一方需要拥有专属的命名空间:自行对其进行重定位,或使用 Koin Embedded LTS。
反馈
对于自助方式(预构建构件和重定位脚本):
相关内容
- 版本、路线图与支持:LTS 分支以及 Kotzilla 企业支持。
- 上下文隔离:在库内部运行私有 Koin 实例。
- 启动 Koin:
startKoin与koinApplication。 - koin-relocate:重定位脚本及其文档。
- Koin Embedded LTS:专属于您的、受维护且无冲突的 Koin。
