本系列文章主要目的在于重新梳理 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<User> 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<User> 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 的内置注解的使用范围及其作用可总结为下表：
需要注意的是最下面的五个注解，它们都是用在注解类型上的，是元注解。
#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 所有可用参数及其含义：
@Retention 元注解只有三种选择，分别对应于上文的三个保留时期：
- RetentionPolicy.SOURCE：源码处理时可见，不会包含在 .class 文件中
- RetentionPolicy.CLASS：默认选择，会包含在 .class 文件中，但不会被虚拟机加载
- RetentionPolicy.RUNTIME：运行时可见，可以通过反射 API 获取
以上就是本文的全部内容，我们将会在进阶篇中讲解更多关于注解的使用技巧，如果你对本文有任何建议，欢迎留言反馈。
