Java不推荐使用的API和SuppressWarnings“不推荐使用” -实用的方法 [英] Java Deprecated APIs and SuppressWarnings "deprecation" - practical approach
问题描述
我已经看到许多使用API上的不推荐使用的注释，以将其标记为需要尽快替换。
I have seen many examples of using the Deprecated annotation on APIs in order to mark them as 'need to be replaced soon'.
但是，在几乎所有这些情况下，代码开发人员不仅继续使用已弃用的API，而且还会继续使用禁止了弃用警告。
However, in almost all of these cases the code developers not only kept using the deprecated APIs, but also suppressed the deprecation warning.
这似乎是API开发人员的最佳意图最终会创建更多与已实现的业务逻辑无关的代码-如果已弃用API，但在抑制了相关警告的情况下继续使用该API，则似乎最好是代码的降级，而在替换已弃用的库时，这似乎是潜在的应用程序中断点最糟糕的恕我直言。
It seems like the best intentions of the API developers end up creating more code which is irrelevant to the implemented business logic - if an API is deprecated but is continually used with the associated warnings being suppressed it seems like a degradation of the code at best and a potential application breaking point when replacing deprecated libraries at worst IMHO.
是否有解决此问题的实用方法？至少，如果确实在CR中保留了较长时间，是否可以将这种情况标记为代码气味？
Is there a practical solution to this problem? At the very least, a way to tag this occurrence as a code smell, if it indeed stays for a relatively long time in the CR?
请提出您可能正在使用的实际解决方案（库，SCA，CR插件等.....）
Please suggest an actual solution you might be using (library, SCA, CR plugin, etc.....)
是否有计划中的JRE / JDK功能可以帮助解决这种情况？我的研究目前还没有发现任何东西。
Are there any planned JRE/JDK features that might help with this situation? My research has currently not found anything.
参考文献：
- what is the best way to comment a deprecated class in java
- is it wrong to use deprecated api
- Excluding warnings using @SuppressWarnings
- Use @Deprecated Java class without compilation warning
推荐答案
步骤1：宣布删除
一个人可能会认为弃用API意味着宣布将其删除，但这不是唯一的用例（例如， Java 7 和 Java 9 ）：
API很危险（例如
Thread.stop方法）。
有一个简单的重命名（例如，AWT Component.show/hide 替换为 setVisible ）。
There is a simple rename (for example, AWT Component.show/hide replaced by setVisible).
可以使用更新更好的API。
A newer, better API can be used instead.
不推荐使用的API将被删除。
The deprecated API is going to be removed.
进一步复杂的是，在Java 9之前，从未删除过JDK中已弃用的API（请参见 Java弃用20年），因此，如果开发人员不认真对待弃用，这是可以理解的-neithe
To further complicate things, before Java 9, no deprecated API in the JDK was ever removed (see 20 Years Of Java Deprecation), so it is understandable if developers do not take deprecation seriously - neither in the JDK nor elsewhere.
因此，您需要清楚地说明API 确实将被删除。这样做的方法取决于您的API所编译的Java版本。
Therefore, you need to communicate clearly that the API is really, really going to be removed. The way to do this depends on the version of Java your API is compiled with.
@deprecated ，不仅给出弃用的原因并列出替代方案，还明确宣布打算删除该API。
In these Java versions, there is no formal way to explicitly distinguish the various deprecation use cases. The best you can do is adding the Javadoc tag @deprecated and not only giving the reason of deprecation and listing alternatives, but also explicitly announcing your intention to remove the API.
从Java 9开始，带有增强弃用，现在您可以编写
Since Java 9, with Enhanced Deprecation, you can now write
@Deprecated(forRemoval=<boolean>)
明确记录您的意图。我认为，连同Javadoc @deprecated （应详细说明弃用的原因并列出替代方法），此标准化标志是一个合理的警告。
to explicitly document your intention. I think that together with Javadoc @deprecated (which should detail the reason for deprecation and list alternatives), this standardized flag is a fair warning.
将此标志设置为 true 时，编译器将针对每次弃用的元素的每次使用发出警告，如下所示：
With this flag set to true, the compiler will warn for each use of the deprecated element like this:
YourClass.java:<line>: warning: [removal] <method> in <class> has been
deprecated and marked for removal
此警告默认为启用（而不是可以通过 -Xlint：deprecation ）启用，并通过 @SuppressWarnings（ deprecation）不抑制c $ c>。取而代之的是，必须使用新的 @SuppressWarnings（ removal）来抑制它，这可能会使开发人员在没有充分理由的情况下三思而行。
This warning is enabled by default (instead of having to be enabled with -Xlint:deprecation) and is not suppressed with @SuppressWarnings("deprecation"). Instead, one would have to suppress it with the new @SuppressWarnings("removal"), which might make developers think twice about doing so without a really good reason.
此外，您可以明确声明引入了弃用的库版本
Additionally, you can explicitly state the library version which introduced the deprecation with
@Deprecated(since="<version>")
在Javadoc或源中看到它可以有所帮助开发人员评估更新代码的紧迫性。
Seeing this in Javadoc or the sources can help developers assess how urgent it is update their code.
在这种情况下可行，添加运行时提醒：使用已弃用的API时，让它在控制台或日志文件中记录一条警告（使用您使用的任何日志记录机制），以宣布该警告将不再与下一个主要版本一起使用。为了避免垃圾邮件，您只能记录一次（例如 private static boolean warningLogged ）。
If feasible for the situation, add a runtime reminder: when the deprecated API is used, have it log a warning to the console or log file (using whatever logging mechanism you use) announcing that this will no longer work with the next major release. To avoid spam, you could only log that once (e.g. private static boolean warningLogged).
静态代码分析器，例如 SonarQube （也可以设置为托管服务）来标记每个警告。 SonarQube规则不应该使用不赞成使用的代码 即使编译器不赞成使用，也应该可以使用
Static code analyzers like SonarQube (also available as a hosted service) can be set up to flag each of these warnings. The SonarQube rule "deprecated code should not be used" should even work if the compiler's deprecation usage warning is suppressed.
SonarQube还跟踪（基于版本控制）何时引入了某个问题（即违反规则），并且您可以基于以下内容交互地过滤其问题列表在那个日期。例如，您可以列出代码库中已有一年多的不赞成使用的代码的所有使用情况，以便您可以优先进行修复工作。
SonarQube also tracks when a certain issue (i.e. a rule violation) was introduced (based on version control) and you can interactively filter its issue lists based on that date. For example, you could list all usages of deprecated code that have been in your code base for over a year so that you can prioritize work on fixing them.
不删除API会给您的API用户以印象，即他们无需费心更改代码。
Not actually removing the API would give your API users the impression that they don't need to bother changing their code.
这篇关于Java不推荐使用的API和SuppressWarnings“不推荐使用” -实用的方法的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持IT屋！
