记录可能被更改的API

Question

我正在开发一个Java项目，它大量使用JavaDoc并生成一个开放的API。我们想要一些记录API何时可能发生变化的方法。那里有先例吗？

Answer 1

首先，我想引用约书亚布洛赫的讲话How to Design a Good API & Why it Matters：

  

如有疑问，请将其删除！

您以后可以随时向API添加新内容，但是您永远无法更改删除已存在的方法，因为人们将使用这种确切的方法，并且不会成为当它突然不在那里时很高兴。

现在，实际上，API 做会发生变化。您可以通过简单地将API从一个版本更改为下一个版本来减少此API用户的麻烦，但至少建立一个优雅的弃用模型。当一个方法即将被更改或删除时，它应该在一个版本中标记为@Deprecated，同时提示它应该如何模拟＆＃34;模拟＆＃34;使用新API，并在后续版本中删除，以便用户有时间适应。

最后，关于你的实际问题：

JavaDocs应该是第一个写这样的通知的地方。当然，那里有足够的开发人员没有阅读文档，但JavaDoc中明确的警告至少是您在发布投诉后可以参考的内容变化; - ）

另一种选择是使用注释。 Guava人添加了the @Beta annotation：

  

表示公用API（公共类，方法或字段）在将来的版本中会发生不兼容的更改，甚至删除。带有此注释的API不受其包含库所做的任何兼容性保证的限制。请注意，此注释的存在并不意味着所讨论的API的质量或性能，只是它没有＆＃34; API冻结。＆＃34;

     

应用程序依赖于beta API通常是安全的，但代价是升级期间的一些额外工作。但是，通常不建议将库（包含在用户和CLASSPATHs中，在库开发人员和控件之外）这样做。

如果适合你的意图，可能会派上用场。

Answer 2

您可以使用现有代码以兼容或不兼容的方式更改API。

理想情况下，公共API仅以与现有代码兼容的方式进行更改。有时需要例外。

如果您可以提前预测API会发生不兼容的更改，请考虑将其设置为私有API，而不是简单地在JavaDoc中进行标记。

可以以不兼容的方式更改私有API。标记私有API的先例包括：

• 使用访问控制使API非公开。
• 将代码放在包含一个术语的包中，该术语表明它不是供公众使用的，例如internal或impl。例如，Eclipse平台有许多包含术语internal。
的包

您还可以标记不可能会更改的API。在Java 8之前，第三方可访问的接口通常不会发生变化。（在Java 8之后，可以通过默认方法将方法添加到接口而不破坏现有代码。）

Answer 3

是的，只需在javadoc中注明。例如，JFrame（以及许多其他Swing组件）的javadoc：

  

警告：此类的序列化对象与之不兼容   未来的Swing发布。目前的序列化支持是   适用于运行的应用程序之间的短期存储或RMI   相同版本的Swing。截至1.4，支持长期存储   所有JavaBeansTM都已添加到java.beans包中。请参阅   XMLEncoder。

这样的信息是类合同的一部分，因此javadoc是记录它的地方。