Java不推荐使用的API和SuppressWarnings“不推荐使用”-实用方法

Question

我已经看到了许多在API上使用Deprecated注释以将其标记为“需要尽快替换”的示例。

但是，在几乎所有这些情况下，代码开发人员不仅继续使用已弃用的API，而且还抑制了弃用警告。

API开发人员的最佳意图似乎最终是创建更多与已实现的业务逻辑无关的代码-如果不赞成使用API​​，但在抑制相关警告的情况下继续使用它，则似乎充其量只是代码的降级，并且在IMHO最差的情况下替换不推荐使用的库时，可能会导致应用程序中断。

有解决这个问题的切实可行的方法吗？至少，如果确实在CR中保留了较长时间，是否可以将这种情况标记为代码气味？

请提出您可能正在使用的实际解决方案（库，SCA，CR插件等.....）

是否有计划中的JRE / JDK功能可以帮助解决这种情况？我的研究目前还没有发现任何东西。

参考文献：

• 在Java中注释不推荐使用的类的最佳方法是什么
• 使用已弃用的api是错误的
• 使用@SuppressWarnings排除警告
• 使用@Deprecated Java类而不进行编译警告

Answer 1

第1步：宣布删除

可能有人认为弃用API意味着宣布将其删除，但这并不是唯一的用例（如Java 7和Java 9的相关文章中所述）：

• API很危险（例如，Thread.stop方法）。

• 有一个简单的重命名（例如，AWT Component.show/hide被替换为setVisible）。

• 可以使用更新更好的API。

• 不推荐使用的API将被删除。

更复杂的是，在Java 9之前，从未删除过JDK中不推荐使用的API（请参阅Java禁止使用20年），因此，如果开发人员不认真对待弃用，无论是在JDK中还是在其他地方，都是可以理解的。

因此，您需要清楚地传达出该API 确实将被删除的事实。执行此操作的方法取决于编译API所使用的Java版本。

Java 8或更低版本

在这些Java版本中，没有正式的方法来明确区分各种弃用用例。最好的办法是添加Javadoc标记@deprecated，不仅给出弃用的原因并列出替代方案，而且明确声明要删除该API。

Java 9或以上

由于Java 9具有增强的弃用功能，因此您现在可以编写

@Deprecated(forRemoval=<boolean>)

明确记录您的意图。我认为与Javadoc @deprecated（应详细说明弃用的原因并列出替代方案）一起使用时，此标准化标志是一个合理的警告。

将此标志设置true为时，编译器将针对不赞成使用的元素的每次使用发出警告，如下所示：

@Deprecated(forRemoval=<boolean>)

默认情况下会启用此警告（而不是必须启用-Xlint:deprecation），并且不会将其取消显示@SuppressWarnings("deprecation")。相反，必须使用new来抑制它@SuppressWarnings("removal")，这可能会使开发人员在没有充分理由的情况下三思而行。

此外，您可以明确声明使用弃用的库版本

@Deprecated(since="<version>")

从Javadoc或源中看到这一点可以帮助开发人员评估其更新代码的紧急程度。

步骤2a：运行时警告

如果适合这种情况，请添加运行时提醒：使用已弃用的API时，让它在控制台或日志文件中记录警告（使用您使用的任何日志记录机制），以宣布该警告将不再与下一个主要版本一起使用。为了避免垃圾邮件，您只能记录一次（例如private static boolean warningLogged）。

步骤2b：静态代码分析

可以设置诸如SonarQube之类的静态代码分析器（也可以作为托管服务使用），以标记每个警告。如果禁止了编译器的弃用用法警告，则SonarQube规则“不应使用弃用的代码”甚至应该起作用。

SonarQube还可以跟踪（基于版本控制）何时引入了某个问题（即违反规则），并且您可以基于该日期以交互方式过滤其问题列表。例如，您可以列出代码库中已使用一年多的不赞成使用的代码的所有使用情况，以便您可以优先确定修复它们的工作。

步骤3：删除API

实际上，如果不删除API，则会给您的API用户以印象，即他们无需费心更改代码。