Java注解

转载于：http://c.biancheng.net/java/40/

从 Java 5 开始，Java 增加了对元数据的支持，也就是注解。注解与注释是有一定区别的，可以把注解理解为代码里的特殊标记，这些标记可以在编译、类加载和运行时被读取，并执行相应的处理。开发人员可以通过注解在不改变原有代码和逻辑的情况下在源代码中嵌入补充信息。

本章学习要点

1. 了解注解的概念和作用
2. 掌握 Java 基本注解的作用及用法
3. 掌握 Java 元注解的的作用及用法
4. 熟练使用 Java 自定义注解
5. 了解如何获取 Java 注解信息

Java注解（Annotation）简介

从 Java 5 版本之后可以在源代码中嵌入一些补充信息，这种补充信息称为注解（Annotation），是 Java 平台中非常重要的一部分。注解都是 @ 符号开头的，例如我们在学习方法重写时使用过的 @Override 注解。同 Class 和 Interface 一样，注解也属于一种类型。

Annotation 可以翻译为“注解”或“注释”，一般翻译为“注解”，因为“注释”一词已经用于说明“//”、“/**…/”和“/…*/”等符号了，这里的“注释”是英文 Comment 翻译。

注解并不能改变程序的运行结果，也不会影响程序运行的性能。有些注解可以在编译时给用户提示或警告，有的注解可以在运行时读写字节码文件信息。

注解可以元数据这个词来描述，即一种描述数据的数据。所以可以说注解就是源代码的元数据。例如以下代码：

@Override
public String toString() {
    return "C语言中文网Java教程";
}

上面的代码重写了 Object 类的 toString() 方法并使用了 @Override 注解。如果不使用 @Override 注解标记代码，程序也能够正常执行。那么这么写有什么好处吗？事实上，使用 @Override 注解就相当于告诉编译器这个方法是一个重写方法，如果父类中不存在该方法，编译器便会报错，提示该方法没有重写父类中的方法。这样可以防止不小心拼写错误造成麻烦。

例如，在没有使用 @Override 注解的情况下，将 toString() 写成了 toStrring()，这时程序依然能编译运行，但运行结果会和所期望的结果大不相同。

注解常见的作用有以下几种：

1. 生成帮助文档。这是最常见的，也是 Java 最早提供的注解。常用的有 @see、@param 和 @return 等；
2. 跟踪代码依赖性，实现替代配置文件功能。比较常见的是 Spring 2.5 开始的基于注解配置。作用就是减少配置。现在的框架基本都使用了这种配置来减少配置文件的数量；
3. 在编译时进行格式检查。如把 @Override 注解放在方法前，如果这个方法并不是重写了父类方法，则编译时就能检查出。

无论是哪一种注解，本质上都一种数据类型，是一种接口类型。到 Java 8 为止 Java SE 提供了 11 个内置注解。其中有 5 个是基本注解，它们来自于 java.lang 包。有 6 个是元注解，它们来自于 java.lang.annotation 包，自定义注解会用到元注解。

提示：元注解就是负责注解其他的注解。

基本注解包括：@Override、@Deprecated、@SuppressWarnings、@SafeVarargs 和 @FunctionalInterface。后面我们会逐一介绍。

Java @Override注解

Java 中 @Override 注解是用来指定方法重写的，只能修饰方法并且只能用于方法重写，不能修饰其它的元素。它可以强制一个子类必须重写父类方法或者实现接口的方法。

使用 @Override 注解示例代码如下：

public class Person {
    private String name = "";
    private int age;
    ...
    @Override
    public String t0String() { //toString()
        return "Person [name=" + name + ", age=" + age + "]";
    }
}

上述代码第 6 行是重写 Object 类的 toString() 方法，该方法使用 @Override 注解。如果 toString() 不小心写成了 t0String()，那么程序会发生编译错误。会有如下的代码提示：

类型为 Person 的方法t0String()必须覆盖或实现超类型方法

所以 @Override 的作用是告诉编译器检查这个方法，保证父类要包含一个被该方法重写的方法，否则就会编译出错。这样可以帮助程序员避免一些低级错误。

当然如果代码中的方法前面不加 @Override 注解，即便是方法编辑错误了，编译器也不会有提示。这时 Object 父类的 toString() 方法并没有被重写，将会引起程序出现 Bug（缺陷）。

Java @Deprecated注解

Java 中 @Deprecated 可以用来注解类、接口、成员方法和成员变量等，用于表示某个元素（类、方法等）已过时。当其他程序使用已过时的元素时，编译器将会给出警告。

使用 @Deprecated 注解示例代码如下：

@Deprecated
public class Person {
    @Deprecated
    protected String name;
    private int age;
    public String getName() {
        return name;
    }
    public void setName(String name) {
        this.name = name;
    }
    public int getAge() {
        return age;
    }
    public void setAge(int age) {
        this.age = age;
    }
    @Deprecated
    public void setNameAndAge(String name, int age) {
        this.name = name;
        this.age = age;
    }
    @Override
    public String toString() {
        return "Person [name=" + name + ", age=" + age + "]";
    }
}

上述代码第 2 行类 Person、第 4 行的成员变量 name 和第 24 行的 setNameAndAge 方法都被 @Deprecated 注解。在 Eclipse 中这些被注解的 API 都会被画上删除线。调用这些 API 代码也会有删除线，示例代码如下。

public class HelloWorld {
    public static void main(String[] args) {
        Person p = new Person();
        p.setNameAndAge("C语言中文网", 20);
        p.name = "Java教程";
    }
}

在 Eclipse 中代码显示如下图所示。

从图中可以看到代码中不仅有删除线，而且还有编译警告。

Java 9 为 @Deprecated 注解增加了以下两个属性：

1. forRemoval：该 boolean 类型的属性指定该 API 在将来是否会被删除。
2. since：该 String 类型的属性指定该 API 从哪个版本被标记为过时。

示例代码如下所示：

class Test {
    // since属性指定从哪个版本开始被标记成过时，forRemoval指定该API将来会被删除
    @Deprecated(since = "9", forRemoval = true)
    public void print() {
        System.out.println("这里是C语言中文网Java教程！");
    }
}
public class DeprecatedTest {
    public static void main(String[] args) {
        // 下面使用info()方法时将会被编译器警告
        new Test().print();
    }
}

上面程序的第 12 行代码使用了 Test 的 print() 方法，而 Test 类中定义 info() 方法时使用了 @Deprecated 修饰，表明该方法已过时，所以将会引起编译器警告。

@Deprecated 的作用与文档注释中的 @deprecated 标记的作用基本相同，但它们的用法不同，前者是 Java 5 才支持的注解，无须放在文档注释语法（/** … */部分）中，而是直接用于修饰程序中的程序单元，如方法、类和接口等。

Java @SuppressWarnings：抑制编译器警告

Java 中的 @SuppressWarnings 注解指示被该注解修饰的程序元素（以及该程序元素中的所有子元素）取消显示指定的编译器警告，且会一直作用于该程序元素的所有子元素。例如，使用 @SuppressWarnings 修饰某个类取消显示某个编译器警告，同时又修饰该类里的某个方法取消显示另一个编译器警告，那么该方法将会同时取消显示这两个编译器警告。

@SuppressWarnings 注解主要用在取消一些编译器产生的警告对代码左侧行列的遮挡，有时候这样会挡住我们断点调试时打的断点。如下图所示。

如果你确认程序中的警告没有问题，可以不用理会。通常情况下，如果程序中使用没有泛型限制的集合将会引起编译器警告，为了避免这种编译器警告，可以使用 @SuppressWarnings 注解消除这些警告。

注解的使用有以下三种：

1. 抑制单类型的警告：@SuppressWarnings(“unchecked”)
2. 抑制多类型的警告：@SuppressWarnings(“unchecked”,“rawtypes”)
3. 抑制所有类型的警告：@SuppressWarnings(“unchecked”)

抑制警告的关键字如下表所示。

关键字	用途
all	抑制所有警告
boxing	抑制装箱、拆箱操作时候的警告
cast	抑制映射相关的警告
dep-ann	抑制启用注释的警告
deprecation	抑制过期方法警告
fallthrough	抑制在 switch 中缺失 breaks 的警告
finally	抑制 finally 模块没有返回的警告
hiding	抑制相对于隐藏变量的局部变量的警告
incomplete-switch	忽略不完整的 switch 语句
nls	忽略非 nls 格式的字符
null	忽略对 null 的操作
rawtypes	使用 generics 时忽略没有指定相应的类型
restriction	抑制禁止使用劝阻或禁止引用的警告
serial	忽略在 serializable 类中没有声明 serialVersionUID 变量
static-access	抑制不正确的静态访问方式警告
synthetic-access	抑制子类没有按最优方法访问内部类的警告
unchecked	抑制没有进行类型检查操作的警告
unqualified-field-access	抑制没有权限访问的域的警告
unused	抑制没被使用过的代码的警告

使用 @SuppressWarnings 注解示例代码如下：

public class HelloWorld {
    @SuppressWarnings({ "deprecation" })
    public static void main(String[] args) {
        Person p = new Person();
        p.setNameAndAge("C语言中文网", 20);
        p.name = "Java教程";
    }
}

在 Eclipse 显示如下图所示。

上述代码第 2 行使用 @SuppressWarnings({ “deprecation” }) 注解了 main 方法。在《Java @Deprecated注解》一节中的 Person 代码中，这些 API 已经过时了，所以代码第 4 行~第 6 行是编译警告，但是在使用了 @SuppressWarnings 注解之后会发现程序代码的警告没有了。

Java @SafeVarargs注解

在介绍 @SafeVarargs 注解用法之前，先来看看如下代码：

public class HelloWorld {
    public static void main(String[] args) {
        // 传递可变参数，参数是泛型集合
        display(10, 20, 30);
        // 传递可变参数，参数是非泛型集合
        display("10", 20, 30); // 会有编译警告
    }
    public static <T> void display(T... array) {
        for (T arg : array) {
            System.out.println(arg.getClass().getName() + ":" + arg);
        }
    }
}

代码第 10 行声明了一种可变参数方法 display，display 方法参数个数可以变化，它可以接受不确定数量的相同类型的参数。可以通过在参数类型名后面加入...的方式来表示这是可变参数。可变参数方法中的参数类型相同，为此声明参数是需要指定泛型。

但是调用可变参数方法时，应该提供相同类型的参数，代码第 4 行调用时没有警告，而代码第 6 行调用时则会发生警告，这个警告是 unchecked（未检查不安全代码），就是因为将非泛型变量赋值给泛型变量所发生的。

可用 @SafeVarargs 注解抑制编译器警告，修改代码如下：

public class HelloWorld {
    public static void main(String[] args) {
        // 传递可变参数，参数是泛型集合
        display(10, 20, 30);
        // 传递可变参数，参数是非泛型集合
        display("10", 20, 30); // 没有@SafeVarargs会有编译警告
    }
    @SafeVarargs
    public static <T> void display(T... array) {
        for (T arg : array) {
            System.out.println(arg.getClass().getName() + "：" + arg);
        }
    }
}

上述代码在可变参数 display 前添加了 @SafeVarargs 注解，当然也可以使用 @SuppressWarnings(“unchecked”) 注解，但是两者相比较来说 @SafeVarargs 注解更适合。

注意：@SafeVarargs注解不适用于非 static 或非 final 声明的方法，对于未声明为 static 或 final 的方法，如果要抑制 unchecked 警告，可以使用 @SuppressWarnings 注解。

Java @FunctionalInterface注解

在学习 Lambda 表达式时，我们提到如果接口中只有一个抽象方法（可以包含多个默认方法或多个 static 方法），那么该接口就是函数式接口。@FunctionalInterface 就是用来指定某个接口必须是函数式接口，所以 @FunInterface 只能修饰接口，不能修饰其它程序元素。

函数式接口就是为 Java 8 的 Lambda 表达式准备的，Java 8 允许使用 Lambda 表达式创建函数式接口的实例，因此 Java 8 专门增加了 @FunctionalInterface。

例如，如下程序使用 @FunctionalInterface 修饰了函数式接口。

@FunctionalInterface
public interface FunInterface {
    static void print() {
        System.out.println("C语言中文网");
    }
    default void show() {
        System.out.println("我正在学习C语言中文网Java教程");
    }
    void test(); // 只定义一个抽象方法
}

编译上面程序，可能丝毫看不出程序中的 @FunctionalInterface 有何作用，因为 @FunctionalInterface 注解的作用只是告诉编译器检查这个接口，保证该接口只能包含一个抽象方法，否则就会编译出错。

@FunctionalInterface 注解主要是帮助程序员避免一些低级错误，例如，在上面的 FunInterface 接口中再增加一个抽象方法 abc()，编译程序时将出现如下错误提示：

“@FunctionInterface”批注无效；FunInterface不是functional接口