API 稳定性与发布类型

API 稳定性

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

实验性 API - @KoinExperimentalAPI

为了促进创新并收集宝贵的社区反馈，我们通过 @KoinExperimentalAPI 注解引入新功能和 API。此标识表明：

• 正在积极开发中：该 API 仍处于设计阶段，可能会发生变化。
• 鼓励提供反馈：我们邀请开发者测试这些功能并分享他们的经验，帮助我们改进和完善设计。
• 潜在的重大更改：由于这些 API 具有实验性，它们可能会根据社区反馈在后续版本中进行修改或移除。

废弃策略 - @Deprecated

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

明确的警告：废弃的 API 会附带一条消息，指示推荐的替代方案或废弃的原因。

废弃级别：

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

这种方法有助于开发者识别和更新依赖于过时 API 的代码，减少技术债务，并为更简洁、更健壮的代码库铺平道路。ReplaceWith 可以与 API 一起提供，具体取决于更新的复杂性。

内部 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 保证。鼓励开发者在非生产环境中尝试这些版本，以帮助识别潜在问题并指导未来的改进。