记录 API 可能会更改
Documenting API which may be changed
我正在开发一个 Java 项目，该项目大量使用 JavaDoc 并生成一个开放的 API。我们想要某种方式来记录 API 何时可能发生变化。这有先例吗？
您可以使用与现有代码兼容或不兼容的方式更改API。
Public APIs 理想情况下仅以与现有代码兼容的方式进行更改。有时需要例外。
如果您可以提前预测 API 会发生不兼容的更改，请考虑将其设为私有 API，而不是简单地在 [=37= 中标记它]博士
私人 API 可以以不兼容的方式更改。标记私有 API 的先例包括：
- 使用访问控制使 API 非 public。
- 将代码放在包含一个术语的包中，该术语表明它不适合 public 使用，例如
internal 或 impl。例如，Eclipse 平台有许多包含术语 internal. 的包
您还可以将 API 标记为 不会 可能更改的。在 Java 8 之前，第三方可访问的接口通常根本不会改变。（在 Java 8 之后，可以通过默认方法将方法添加到接口而不会破坏现有代码。）
是的，只需在 javadoc 中指出即可。例如，JFrame（以及许多其他 Swing 组件）的 javadoc：
Warning: Serialized objects of this class will not be compatible with
future Swing releases. The current serialization support is
appropriate for short term storage or RMI between applications running
the same version of Swing. As of 1.4, support for long term storage of
all JavaBeansTM has been added to the java.beans package. Please see
XMLEncoder.
此类信息是 class 合同的一部分，因此 javadoc 是对其进行记录的地方。
首先我想引用 Joshua Bloch 的演讲 How to Design a Good API & Why it Matters:
When in doubt, leave it out!
您以后可以随时向 API 添加新内容，但您永远不能更改删除已经存在的方法，因为人们将 使用 这个方法，当它突然不存在时不会高兴。
现在，实际上，APIs 做改变。您可以减少此 API 用户的麻烦，而不是简单地将 API 从一个版本更改为另一个版本，而是至少建立一个优雅的 弃用模型 。当一种方法即将被更改或删除时，它应该在一个版本中被标记为 @Deprecated，并提示如何用新的 API 来“模拟”它，然后删除在后续版本中，让用户有时间适应。
最后，关于你的实际问题：
JavaDocs 应该是第一个写这样的通知的地方。当然，有足够多的开发人员不阅读文档，但 JavaDoc 中明确的 WARNING 至少是您在收到投诉后可以参考的内容发布更改 ;-)
另一种选择是使用注释。 Guava 人添加了 the @Beta annotation:
Signifies that a public API (public class, method or field) is subject to incompatible changes, or even removal, in a future release. An API bearing this annotation is exempt from any compatibility guarantees made by its containing library. Note that the presence of this annotation implies nothing about the quality or performance of the API in question, only the fact that it is not "API-frozen."
It is generally safe for applications to depend on beta APIs, at the cost of some extra work during upgrades. However it is generally inadvisable for libraries (which get included on users' CLASSPATHs, outside the library developers' control) to do so.
如果符合您的意图，它可能会在这里派上用场。
我正在开发一个 Java 项目，该项目大量使用 JavaDoc 并生成一个开放的 API。我们想要某种方式来记录 API 何时可能发生变化。这有先例吗？
您可以使用与现有代码兼容或不兼容的方式更改API。
Public APIs 理想情况下仅以与现有代码兼容的方式进行更改。有时需要例外。
如果您可以提前预测 API 会发生不兼容的更改，请考虑将其设为私有 API，而不是简单地在 [=37= 中标记它]博士
私人 API 可以以不兼容的方式更改。标记私有 API 的先例包括：
- 使用访问控制使 API 非 public。
- 将代码放在包含一个术语的包中，该术语表明它不适合 public 使用，例如
internal或impl。例如，Eclipse 平台有许多包含术语internal. 的包
您还可以将 API 标记为 不会 可能更改的。在 Java 8 之前，第三方可访问的接口通常根本不会改变。（在 Java 8 之后，可以通过默认方法将方法添加到接口而不会破坏现有代码。）
是的，只需在 javadoc 中指出即可。例如，JFrame（以及许多其他 Swing 组件）的 javadoc：
Warning: Serialized objects of this class will not be compatible with future Swing releases. The current serialization support is appropriate for short term storage or RMI between applications running the same version of Swing. As of 1.4, support for long term storage of all JavaBeansTM has been added to the java.beans package. Please see XMLEncoder.
此类信息是 class 合同的一部分，因此 javadoc 是对其进行记录的地方。
首先我想引用 Joshua Bloch 的演讲 How to Design a Good API & Why it Matters:
When in doubt, leave it out!
您以后可以随时向 API 添加新内容，但您永远不能更改删除已经存在的方法，因为人们将 使用 这个方法，当它突然不存在时不会高兴。
现在，实际上，APIs 做改变。您可以减少此 API 用户的麻烦，而不是简单地将 API 从一个版本更改为另一个版本，而是至少建立一个优雅的 弃用模型 。当一种方法即将被更改或删除时，它应该在一个版本中被标记为 @Deprecated，并提示如何用新的 API 来“模拟”它，然后删除在后续版本中，让用户有时间适应。
最后，关于你的实际问题：
JavaDocs 应该是第一个写这样的通知的地方。当然，有足够多的开发人员不阅读文档，但 JavaDoc 中明确的 WARNING 至少是您在收到投诉后可以参考的内容发布更改 ;-)
另一种选择是使用注释。 Guava 人添加了 the @Beta annotation:
Signifies that a public API (public class, method or field) is subject to incompatible changes, or even removal, in a future release. An API bearing this annotation is exempt from any compatibility guarantees made by its containing library. Note that the presence of this annotation implies nothing about the quality or performance of the API in question, only the fact that it is not "API-frozen."
It is generally safe for applications to depend on beta APIs, at the cost of some extra work during upgrades. However it is generally inadvisable for libraries (which get included on users' CLASSPATHs, outside the library developers' control) to do so.
如果符合您的意图，它可能会在这里派上用场。