跳到主要内容

API 稳定性 & 发布类型

API 稳定性​

Koin 项目致力于在不同版本之间保持高度兼容性。Kotzilla 团队和所有活跃的维护者都在努力确保在新版本中引入的任何更改、增强或优化都不会破坏现有的应用程序。 我们深知，稳定且可预测的升级路径对我们的用户至关重要，因此我们力求在改进 API 时最大限度地减少中断。

实验性 API - @KoinExperimentalAPI​

为了在收集宝贵的社区反馈的同时促进创新，我们引入了带有 @KoinExperimentalAPI 注解的新特性和 API。此标识表明：

  • 积极开发中：该 API 仍处于设计阶段，可能会发生变化。
  • 鼓励反馈：我们邀请开发者测试这些特性并分享他们的经验，帮助我们改进和完善设计。
  • 潜在的破坏性更改：由于这些 API 是实验性的，因此可能会根据社区的意见进行迭代，并在后续版本中进行修改或删除。

弃用策略 - @Deprecated​

为了确保在 API 的某些部分逐步淘汰时能够平稳过渡，Koin 使用 @Deprecated 注解来清晰地标记这些区域。我们的弃用策略包括：

清晰的警告：已弃用的 API 附带一条消息，指示建议的替代方案或弃用原因。

弃用级别：

  • Warning（警告）：表示虽然该 API 仍然可用，但不鼓励使用，应尽早替换。
  • Error（错误）：表示该 API 不再供使用，并且将无法编译，从而确保及时处理重要的更改。

这种方法可以帮助开发人员识别和更新依赖于过时 API 的代码，从而减少技术债务，并为更简洁、更健壮的代码库铺平道路。 根据更新的复杂性，可以为 API 提供 ReplaceWith。

内部 API - @KoinInternalAPI​

对于 Koin 框架内严格用于内部的功能，我们引入了 @KoinInternalAPI 注解。这些 API 不是公共合约的一部分，并且：

  • 仅供内部使用：专门为 Koin 的内部机制而设计。
  • 可能会发生变化：可能会在未来的版本中进行修改或删除，恕不另行通知。
  • 避免外部使用：不鼓励开发人员在其应用程序代码中使用这些 API，以保持长期的兼容性。

使用 Kotlin 的 @OptIn 注解选择加入​

Koin 中实验性和已弃用 API 的使用都需要选择加入，以确保开发人员完全了解 API 的状态和潜在风险。 通过使用 Kotlin 的 @OptIn 注解，您可以明确承认您的代码依赖于实验性或标记为已弃用的 API。

发布类型​

Koin 遵循语义版本控制（SemVer），并带有额外的“前缀标识符”，用于指示每个版本的成熟度和预期用途。我们使用的前缀包括：

  • Release Candidate (RC)：这些版本是功能完整的稳定版本候选版本。它们经过最后的测试和完善。虽然 RC 版本旨在高度兼容，但根据官方发布之前的最终反馈，可能仍然会发生细微的变化。
  • Alpha / Beta：Alpha 和 Beta 版本主要用于测试和反馈。它们通常包含实验性特性，并且可能不完全符合稳定的 API 保证。鼓励开发人员在非生产环境尝试这些版本，以帮助识别潜在问题并指导未来的改进。