小编典典
第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=)
明确记录您的意图。我认为与Javadoc @deprecated(应详细说明弃用的原因并列出替代方案)一起使用时,此标准化标志是一个合理的警告。
将此标志设置true为时,编译器将针对不赞成使用的元素的每次使用发出警告,如下所示:
YourClass.java:: warning: [removal] in has been
deprecated and marked for removal
默认情况下启用此警告(而不是必须启用-Xlint:deprecation),并且 不会将其
取消显示@SuppressWarnings("deprecation")。相反,必须使用new来抑制它@SuppressWarnings("removal"),这可能会使开发人员在没有充分理由的情况下三思而行。
此外,您可以明确说明使用以下方式引入了弃用功能的库版本
@Deprecated(since="")
从Javadoc或源中看到这一点可以帮助开发人员评估其更新代码的紧急程度。
步骤2a:运行时警告
如果适合这种情况,请添加运行时提醒:使用已弃用的API时,让它在控制台或日志文件中记录警告(使用您使用的任何日志记录机制),以宣布该警告将不再与下一个主要版本一起使用。为了避免垃圾邮件,您只能记录一次(例如private
static boolean warningLogged)。
步骤2b:静态代码分析
可以设置诸如SonarQube(也可以作为托管服务)之类的静态代码分析器来标记这些警告中的每一个。如果禁止了编译器的弃用用法警告,则SonarQube规则“不应使用弃用的代码”甚至应该起作用。
SonarQube还可以跟踪(基于版本控制)何时引入了某个问题(即违反规则),并且您可以基于该日期以交互方式过滤其问题列表。例如,您可以列出代码库中已使用一年多的不赞成使用的代码的所有使用情况,以便您可以优先确定修复它们的工作。
步骤3:删除API
实际上,如果不删除API,则会给您的API用户以印象,即他们无需费心更改代码。
2020-11-16