语义版本控制和实验性 API 元素

Question

我根据语义版本控制的规则对我的 API（各种类型：REST、Java 等）进行版本控制（对于 REST API，在

Info 对象

的 version 字段中指定 OAS 中的版本；对于Java API，这是对应artifact的

version

属性——groupId、artifactId的部分，

version

）。

目前，我想介绍将一些API元素标记为实验性的做法（对于REST API，使用自定义扩展；对于Java API，使用自定义注释）。

现在，我不明白如果删除实验元素，我应该如何继续使用 API 版本？

---

案例：

1. 在API版本中添加实验性元素

   5.1.0

   。
2. 我正在从 API 中删除一个实验性元素。我应该提供哪个版本的 API：

   6.0.0

   、

   5.1.1

   还是其他？

Answer 1

可以说这是一个基于意见的问题，但我会尽力表达我对这个主题的看法。

如果可能的话，我强烈建议在某些标志/标头（如

enableExperimentalFeatures

）后面“隐藏”实验性功能，因此用户需要明确“同意”使用这些功能并验证是否理解所有风险（因此不提供兼容性保证）给定）。这将允许您仅操作次要/补丁版本，而不是用实际上没有任何重大更改的主要版本“乱扔”版本池。

或者，您可以发布两个版本，其中一个版本带有

experimental

后缀，遵循 SemVer 建议的 预发布版本控制处理（即，您将发布

X.Y.Z

和

X.Y.Z-experimental

版本，这两个版本仅在实验性的可用性方面有所不同）特点）