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 都需要选择启用 (opt-in)，以确保开发者充分了解 API 的状态和潜在风险。 通过使用 Kotlin 的 @OptIn 注解，你显式承认了你的代码依赖于实验性或被标记为弃用的 API。

发布类型

Koin 遵循语义化版本规范 (SemVer)，并带有额外的后缀标识符来表示每个版本的成熟度和预期用途。我们使用的后缀包括：

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