java弃用标签_Java 9 揭秘（15. 增强的弃用注解）

Tips

做一个终身学习的人。

主要介绍以下内容：

如何弃用API

@deprecate Javadoc标签和@Deprecation注解在弃用的API中的角色

用于生成弃用警告的详细规则

在JDK 9中更新@Deprecation注解

JDK 9中的新的弃用警告

如何使用@SuppressWarnings注解来抑制JDK 9中的不同类型的弃用警告

如何使用jdeprscan静态分析工具来扫描编译的代码库，以查找已弃用的JDK API的用法

一. 什么是弃用

Java中的弃用是提供有关API生命周期的信息的一种方式。 可以弃用模块，包，类型，构造函数，方法，字段，参数和局部变量。 当弃用API时，要告诉其用户：

不要使用API，因为它存在风险。

API已经迁移，因为存在API的更好的替代方案。

API已经迁移，因为API将在以后的版本中被删除。

二. 如何弃用API

JDK有两个用于弃用API的结构：

@deprecated Javadoc标签

@Deprecated注解

@deprecated Javadoc标签已添加到JDK 1.1中，它允许使用丰富的HTML文本格式功能指定关于弃用的详细信息。JDK 5.0中添加了java.lang.Deprecated注解类型，并且可以在已被弃用的API元素上使用。 在JDK 9之前，注解不包含任何元素。 它在运行时保留。

@deprecated标签和@Deprecated注解应该一起使用。 两者都应该存在或两者都不存在。 @Deprecation注解不允许指定弃用的描述，因此必须使用@deprecated标签来提供描述。

Tips

在API元素上使用@deprecated标签(而不是@Deprecated注解)会生成编译器警告。 在JDK 9之前，需要使用-Xlint：dep-ann编译器标志来查看这些警告。

下面包含FileCopier类的声明。 假设这个类作为类库迁移的一部分。 该类使用@Deprecation注解表示弃用。 它的Javadoc使用@deprecated标签来提供不推荐使用的详细信息，例如不推荐使用的时间，它的替换和删除通知。 在JDK 9之前，@Deprecated注解类型不包含任何元素，因此必须使用Javadoc中已弃用的API的@deprecated标签提供有关弃用的所有详细信息。 请注意，Javadoc中使用的@since标签表示FileCopier类自该库的版本1.2以来已经存在，而@deprecated标签表示该类自版本1.4以来已被弃用。

// FileCopier.java

package com.jdojo.deprecation;

import java.io.File;

/**

* The class consists of static methods that can be used to

* copy files and directories.

*

* @deprecated Deprecated since 1.4. Not safe to use. Use the

* java.nio.file.Files class instead. This class

* will be removed in a future release of this library.

*

* @since 1.2

*/

@Deprecated

public class FileCopier {

// No direct instantiation supported.

private FileCopier() {

}

/**

* Copies the contents of src to dst.

* @param src The source file

* @param dst The destination file

* @return true if the copy is successfully,

* false otherwise.

*/

public static boolean copy(File src, File dst) {

// More code goes here

return true;

}

// More methods go here

}

Javadoc工具将@deprecated标签的内容移动到生成的Javadoc中的顶部，以引起读者的注意。 当不被弃用的代码使用不推荐使用的API时，编译器会生成警告。 请注意，使用@Deprecated注解标注API不会生成警告；但是，使用已经使用@Deprecated注解标注的API。 如果在类本身之外使用FileCopier类，则会收到关于使用不推荐使用的类的编译器警告。

三. JDK 9中@Deprecated注解的更新

假设编译了代码并将其部署到生产环境中。如果升级了JDK版本或包含旧应用程序使用的新的已弃用的API的库/框架，则不会收到任何警告，并且将错过从不推荐使用的API迁移的机会。必须重新编译代码以接收警告。没有任何扫描和分析编译代码(例如JAR文件)的工具，并报告使用已弃用的API。更坏的情况是，从旧版本中删除不推荐使用的API，而旧的编译代码会收到意外的运行时错误。当他们查看不赞成使用的元素Javadoc时，开发人员也感到困惑 —— 当API被废弃时，无法表达何种方式，以及在将来的版本中是否会删除已弃用的API。所有可以做的是在文本中将这些信息指定为@deprecated标签的一部分。 JDK 9尝试通过增强@Deprecated注解来解决这些问题。注解在JDK 9中已增加两个新元素：since和forRemoval。

在JDK 9之前，注解的声明如下：

@Documented

@Retention(RetentionPolicy.RUNTIME)

@Target(value={CONSTRUCTOR, FIELD, LOCAL_VARIABLE, METHOD, PACKAGE, PARAMETER, TYPE})

public @interface Deprecated {

}

在JDK 9中，弃用注解的声明更改为以下内容：

@Documented

@Retention(RetentionPolicy.RUNTIME)

@Target(value={CONSTRUCTOR, FIELD, LOCAL_VARIABLE, METHOD, PACKAGE, MODULE, PARAMETER, TYPE})

public @interface Deprecated {