[Java Again]之注解（Annotation）-基础篇

本系列文章主要目的在于重新梳理 Java 基础知识，可能不会按照由浅入深的顺序去写。文章内容主要参考《Core Java for the Impatient》一书。

注解相关的内容打算分两篇来写：基础篇和进阶篇，本文是基础篇，主要涵盖以下内容：

• 什么是注解
• 注解的基本使用及分类
• 标准注解与自定义注解

#0. 什么是注解

注解（Annotation）是 Java 在 1.5 版本中引入的新特性。它可以用来标注源码，并在编译期或运行时被注解处理器处理。如果你是一个优雅的 Android Developer，那么你肯定对 ButterKnife、retrofit 等优秀的三方库非常熟悉。你没看错，它们都在使用注解让代码变的更优雅，易于理解。下面就让我们揭开注解神秘的面纱吧。

Are You Ready?

#1. 注解的基本使用及分类

在正式了解注解之前，我们先看一个例子：学过 Java 的同学应该都知道，在自定义对象中，我们需要重写 toString 方法以格式化打印该对象时的输出。

public class Person {
    String name;
    int age;

    ...

    @Override
    public String toString() {
        return "Person{" +
                "name='" + name + '\'' +
                ", age=" + age +
                '}';
    }
}

相信你已经注意到了 toString 方法上面的 @Override，它就是一个标记在方法上的注解，用于表示该方法是对父类方法的重写。

#1.1. 注解的基本使用

让我们借着上面的例子来讲一下注解的基本使用。如你所见，注解都是以 @ 开头，后面紧跟一个标准或自定义注解类型（这里的 Override 是一个标准注解）。

注解可以声明在源码中的以下位置：

• 类，枚举，接口
• 方法
• 构造器
• 实例（全局）变量（包括枚举常量）
• 局部变量（包括 for 或 try 代码块中的变量）
• 形式参数和 catch 中的参数
• 类型参数
• 包

// 类注解
@Entity public class User{...}
// 变量注解
@SuppressWarnings("unchecked") List users = ...;
public User getUser(@Param("id") String userId){...}
// 类型参数注解
public class Cache<@Immutable V> {...}
// 包注解
@GPL(version=“3”) 
package com.horstmann.corejava; 
import org.gnu.GPL; // 注意：导入语句在包定义下方

注解可以拥有一些被称为元素的键值对，以 JUnit 4 测试框架中的 @Test 注解为例：

@Test(timeout=2000)
public void testSample() {
    ...
}

此处的 timeout=2000表示该测试最长可执行 2000 毫秒，超过 2000 毫秒没有执行完就会抛出异常：

java.lang.Exception: test timed out after 2000 milliseconds

如果注解中只有一个元素，且元素的键名为 value，则该元素的键可以省略，如上面的变量注解：

@SuppressWarnings("unchecked") List users = ...;

元素的值可以是以下类型：

• 原始类型
• 字符串
• Class 对象
• 枚举实例
• 注解
• 或以上类型的数组（不包括数组）

在同一个条目上可以有多个（相同的或不同的）注解。

@Test 
@BugReport(showStopper=true, reportedBy=“Joe”) 
public void checkRandomInsertions() { ... }

@BugReport(showStopper=true, reportedBy=“Joe”) 
@BugReport(reportedBy={“Harry”, “Carl”}) 
public void checkRandomInsertions() { ... }

#1.2. 注解的分类

根据注解保留的时期，可以将其分为三类：

• 源码期注解：只能保留在源码文件中，不会被编译到 .class 文件
• 编译期注解：只能被编译器保留到 .class 文件中，不能被虚拟机保留到运行时
• 运行时注解：能被虚拟机保留到运行时

作用于注解类型上的注解被称为元注解。

#2. 标准注解与自定义注解

Java 默认实现了一些方便的注解类型供我们在开发中使用，它还允许我们在需要时创建自定义注解。

#2.1. Java 内置标准注解

Java 的内置注解的使用范围及其作用可总结为下表：

摘自《Core Java for the Impatient》

需要注意的是最下面的五个注解，它们都是用在注解类型上的，是元注解。

#2.2. 自定义 Java 注解

与使用 class 声明类相似，Java 使用 @interface 声明一个注解类型：

public @interface BugReport { ... }

我们可以像给接口添加方法一样为自定义注解添加元素：

public @interface BugReport {

    String desc();
    String[] reportBy() default {}; //添加默认值，如果不指定，则使用该值
}

我们还可以给自定义注解指定保留时期和使用范围：

@Target(ElementType.TYPE)
@Retention(RetentionPolicy.CLASS)
public @interface BugReport {

    String desc();
    String[] reportBy() default {};
}

这样，我们的 BugReport 将只能作用于类型级别上（不能在方法，字段上使用），而且指定其为编译期注解。

下图为 @Target 所有可用参数及其含义：

@Target 可用参数

@Retention 元注解只有三种选择，分别对应于上文的三个保留时期：

• RetentionPolicy.SOURCE：源码处理时可见，不会包含在 .class 文件中
• RetentionPolicy.CLASS：默认选择，会包含在 .class 文件中，但不会被虚拟机加载
• RetentionPolicy.RUNTIME：运行时可见，可以通过反射 API 获取

---

以上就是本文的全部内容，我们将会在进阶篇中讲解更多关于注解的使用技巧，如果你对本文有任何建议，欢迎留言反馈。

#3. 延伸阅读

• 《Core Java for the Impatient》
• Java注解(Annotation)
• 公共技术点之 Java 注解 Annotation