使用@Deprecated标记删除版本的正确方法是什么？

Question

我被要求弃用一些要在未来版本中弃用和删除的类。鉴于 Javadocs 有 2 个属性，即已弃用的版本以及是否将被删除。所以我最终得到了这样的标签

@Deprecated(forRemoval = true)

然后我被要求添加两件事，首先是它将被删除的版本。现在我当然可以使用评论或类似的东西，但似乎没有任何正式的东西，所以评论只是一种方法还是我遗漏了什么？在此示例中，删除版本为 4.5.0。

还有一个

since

属性，但是，由于我们并行有多个版本，这看起来并不直观。例如，我们可能会发布版本 4.3、4.2 和 4.1 的补丁，因此从技术上来说，在 4.3 分支上，它会从 4.3.2 开始被标记为已弃用，在 4.2 上，它会从 4.2.5 开始，4.1 会从 4.1.9 开始标记为已弃用。 。这意味着如果您使用的是 4.3.1、4.2.4 或 4.1.8，它不会被标记为已弃用。

我是否需要通过注释来完成这项工作，或者是否有某种方法可以使用注释来完成所有这些工作，以便开发人员的 IDE 能够识别它？

Answer 1

说实话，这个问题是众所周知的，我可以在这里分享一些经验。

首先，java中没有内置的方法来指定软件的版本，其中给定的API将被删除。参数

since

只是 API 被标记为弃用的版本，引用自文档：

此元素的值指示首次弃用带注释的程序元素的版本。

我是 spring-data 开源项目的社区贡献者，API 弃用是很常见的事情。 如果我们弃用某些 API，如果我们将其标记为

forRemoval = true

，则它会在 SemVer 之后的下一个主要版本中被删除。我只是让你知道行业霸权是怎么做到的。 至于这个说法：

还有一个since属性，但是，由于我们并行有多个版本，这看起来并不直观。例如，我们可能会发布版本 4.3、4.2 和 4.1 的补丁，因此从技术上来说，在 4.3 分支上，它会从 4.3.2 开始被标记为已弃用，在 4.2 上，它会从 4.2.5 开始，4.1 会从 4.1.9 开始标记为已弃用。 。这意味着如果您使用的是 4.3.1、4.2.4 或 4.1.8，它不会被标记为已弃用。

这完全没问题。这是仍然支持以前的主要版本的众多原因之一 - 因为主要版本 2 中删除的一些 API 存在于主要版本 1 中，并且某些客户端尚未准备好迁移。 这就是为什么我们将补丁向后移植到以前的主要版本的次要版本中，正如您所描述的，这很好。这种做法被 JDK、Kotlin、Spring 项目等采用。

我是否需要通过注释来完成这项工作，或者是否有某种方法可以使用注释来完成所有这些工作，以便开发人员的 IDE 能够识别它？

没有兼容的方法可以做到这一点。您无法知道该人正在使用什么 IDE 以及启用了哪些插件或检查。

我们可以而且应该做的是：

1. 添加 Java 标签

   @deprecated

   并提供有意义的解释为什么该 API 已被弃用以及何时将被删除。
2. 添加 Java 标签

   @see

   引导用户找到 API 的潜在替代品
3. 当然，不要忘记将源代码与包含字节码的 .jar 一起打包，以便上述两个建议能够在开发人员的 IDE 上运行，至少 IntelliJ 可以下载并解析源 jar。

关心用户是一件伟大的事情，你做的是正确的事情。但你无法解决所有问题，所以，尽你所能。

P.S：Oracle 官方关于弃用 API 的指南，从他们的角度来看。