Annotation 是一种元数据，它为程序提供不属于自身的信息，对被注解代码的操作不起直接作用。
注解有很多用处，包括：
- 提供给编译器的信息 —— 编译器可以根据注解检测错误或抑制警告
- 编译期和部署期处理 —— 工具可以根据注解生成代码、XML 等文件
- 运行时处理 —— 有些注解可以在运行时被检测到
下文介绍注解可以被用到什么地方，如何使用，JavaSE 提供了哪些预定义注解，怎样在可插拔类型系统中使用类型注解实现强大的类型检查，怎样实现重复注解。
Annotation Basics
The Format of an Annotation
下面是最简单的注解形式：
@Entity@ 符号告诉编译器，紧跟着的是注解。下面这个注解的名称是 Override：
@Override
void mySuperMethod(){}注解可以包含 elements，它们可以是 named 或 unnamed，具有 value：
@Author(
name = "Benjamin Franklin",
date = "3/27/2003"
)
class MyClass {
}或者
@SupressWarnings(value = "unchecked")
void myMethod(){}如果仅有一个名为 value 的 element，则可以像下面这样省略 name：
@SupressWarnings("unchecked")
void myMethod(){}如果一个 element 都没有，还可以像前面 @Override 那样省略圆括号。
也可在相同声明处使用多个注解：
@Author(name = "Jane Doe")
@EBook
class MyClass {
}如果多个注解类型相同，这种声明称为 repeating annotation：
@Author(name = "Jane Doe")
@Author(name = "John Smith")
class MyClass {
}Java SE 8开始支持重复注解。更多信息见 Repeating Annotations。
注解类型可以是 java.lang 或 java.lang.annotation 中定义的一种，上面的 Override 和 SuppressWarnings 就是预定义注解。你还可以定义自己的注解类型，就如上面的 Author 和 Ebook。
Where Annotation Can Be Used
注解可被用在声明上：包括类、属性、方法和其他程序元素的声明。当被使用时，按照惯例，每个注解单独占一行。
从 Java SE 8 开始，注解可以被用在类型的 使用 上，下面是一些例子：
类实例创建表达式
new @Interned MyObject();类型转换
myString = (@NotNull String) str;implements子句class UnmodifiableList<T> implements @Readonly List<@Readonly T> {}抛出异常声明
void moniterTemperature() throws @Critical TemperatureException {}
这种形式的注解称 type annotation。更多信息见 Type Annotations and Pluggable Type Systems。
Declaring an Annotation Type
许多注解用来代替注释。假设一个软件开发组习惯在每个类开头通过注释提供重要信息：
public class Generation3List extends Generation2List {
// Author: John Doe
// Date: 3/17/2002
// Current revision: 6
// Last modified: 4/12/2004
// By: Jane Doe
// Reviewers: Alice, Bill, Cindy
// class code goes here
}为了使用注解代替它们，先要声明注解类型。下面是声明格式：
@interface ClassPreamble {
String author();
String date();
int currentRevision() default 1;
String lastModified() default "N/A";
String lastModifiedBy() default "N/A";
// Note use of array
String[] reviewers();
}注解定义看上去就像接口定义，只是 interface 关键字前多了个 @ (@ = AT) ，它确实是一种接口。
上面的注解定义中包含 annotation type element 声明，看上去就像方法。注意它们可以定义可选的默认值。
完成注解类型定义，就可以使用它了，可以像下面这样为元素赋值：
@ClassPreamble(
author = "John Doe",
date = "3/17/2002",
currentRevision = 6,
lastModified = "4/12/2004",
lastModifiedBy = "Jane Doe",
// Note array notation
reviewers = {"Alice", "Bob", "Cindy"}
)
public class Generation3List extends Generation2List {
// class code goes here
}备注
如果想让@ClassPreamble 包含的信息出现在 Javadoc 生成的文档中，你必须在 @ClassPreamble 的定义上使用 @Documented 注解：
// import this to use @Documented
import java.lang.annotation.*;
@Documented
@interface ClassPreamble {
// Annotation element definitions
}Predefined Annotation Types
Java SE API 提供了一组预定义注解，它们有些被编译器使用，有些用于其他注解。
Annotation Types Used by the Java Language
预定义在 java.lang 包下的注解有 @Deprecated, @Override, 和 @SuppressWarnings。
@Deprecated 注解表明被标记元素已经过时，不应该继续使用。当代码中出现被 @Deprecated 注解的类，方法或属性时，编译器会生成一个警告。如果一个元素已经过时，它同时应该像下面这样，被 Javadoc 的 @deprecated 标签标注。Javadoc 标签和 Annotataion 注解都使用了 @ 符号，这并不是偶然的：它们在概念上相关。同时，注意 Javadoc 标签以小写 d 开头，而注解是大写 D。
class CertainClass {
// Javadoc comment follows
/**
* @deprecated
* explanation of why it was deprecated
*/
@Deprecated
static void deprecatedMethod() {
}
}@Override 通知编译器，下面的元素将要覆盖父类中的元素。重写方法将会在 Interfaces and Inheritance 讨论。
// mark method as a superclass method
// that has been overridden
@Override
int overriddenMethod(){}虽然重写方法时，该注解并非必须，但它可以防止错误。如果一个被标记了 @Override 的方法没有正确覆盖某个父类中的方法，编译器将生成错误。
@SuppressWarnings 告诉编译器抑制某个它本要产生的警告。下例中使用了一个过时方法，编译器本应发出警告，但因为有了上述注解，警告将被抑制。
// use a deprecated method and tell
// complier not to generate a warning
@SuppressWarnings("deprecation")
void useDeprecatedMethod() {
// deprecation warning
// - supressed
objectOne.deprecatedMethod();
}每个编译器警告属于一个类别。Java 语言规范中列举了两类：deprecated 和 unchecked。当与引入 泛型 之前的遗留代码交互时，unchecked 警告就会产生。使用下面的语法抑制多种类型警告：
@SuppressWarnings({"unchecked", "deprecation"})@SafeVarargs 用于方法或构造器时，断言该方法不会对自身的 varargs 产生潜在的不安全操作。此时，与 varargs 使用 相关的 unchecked warnings 将被抑制。
@FunctionalInterface 注解在 Java SE 8 引入，表明要将类型声明为 Java 语言规范定义的函数接口。
Annotation That Apply to Other Annotations
应用于其他注解的注解称为 meta-annotations。java.lang.annation 中定义了几种元注解类型。
@Retention 指定被标记注解如何储存。
- RetentionPolicy.SOURCE —— 标记注解仅保留在源码级别，会被编译器忽略。
- RetentionPolicy.CLASS —— 标记注解在编译时被编译器保留，但会被 JVM 忽略。
- RetentionPolicy.RUNTIME —— 标记注解被 JVM 保留，所以可以在运行时环境中使用它。
@Documented 表明无论何时使用被它标记的注解，该注解的元素都会通过 Javadoc tool 生成文档。（默认情况下，注解不被包含在 Javadoc 中。）更多信息见 Javadoc tools page。
@Target 用于约束被它标记的注解能够应用到哪些 Java 元素上。该注解需要指定以下元素中的一个作为它的值：
- ElementType.ANNOTATION_TYPE 可以被用在注解上
- ElementType.CONSTRUCTOR 可以被用在构造器上
- ElementType.FIELD 可以被用在域或属性上
- ElementType.LOCAL_VARIABLE 可以被用在局部变量上
- ElementType.METHOD 可以被用在方法级注解上
- ElementType.PACKAGE 可以被用在包声明上
- ElementType.PARAMETER 可以被用在方法的参数上
- ElementType.TYPE 可以被用到类的任何元素上
@Inherited 表明该注解类型可以从父类继承（默认情况下不可以）。当用户查询一个类的注解类型而该类没有注解时，该类的父类将被查找。这种注解仅用于类型声明。
@Repeatable 在 Java SE 8 被引入，被它标记的注解，在相同声明或类型引用处可以使用多次。更多信息见 Repeating Annotations。
Type Annotations and Pluggable Type Systems
Java SE 8 发布前，注解仅能被用到声明上。随着 Java SE 8 的发布，注解也可以用到任何 类型引用 上了。这意味着你可以在任何使用类型的地方使用注解。几个类型使用的例子是 类实例创建表达式、casts、implements 子句，和 throws 子句。这种形式的注解称为 type annotation，见 Annotations Basics。
类型注解被创建出来支持改进的，确保强类型检查方式的分析。虽然 Java SE 8 没有提供类型检查框架，但它允许你编写（或下载）一个实现了一到多个可插拔模块的框架，这些模块可以和 Java 编译器协同使用。
举例来说，你想保证程序中的某个变量永远不会赋值成 null，从而触发 NullPointerException。你可以通过编写自定义插件来检查它。随后，修改代码，在那个变量上添加注解，表明它永远不被赋值为 null。那个变量的声明可能像下面这样：
@NonNull String str;当你编译代码时，在命令行中包含 NonNull 模块，如果编译器检测到潜在问题，警告将被打印，提醒你修改代码避免错误。在你改正代码移除所有警告后，程序运行时，该错误将永远不会发生。
你可以使用多个类型检查模块，每个模块检查一种错误。这样，你就可以在 Java 类型系统的基础上进行构建，在需要的时间和地点，增加特定的检查。
审慎地使用类型注解搭配可插拔的类型检查器，你就可以写出健壮的，不容易出错的代码。
许多情况下，你不需要自己编写类型检查模块。第三方已经为你做了。例如，你可能想使用华盛顿大学创建的类型检查框架。它包含一个 NonNull 模块，一个正则表达式框架，和一个互斥锁模块。更多信息见 Checker Framework。
Repeating Annotations
有时，你想在声明或类型引用处使用多个类型相同的注解。随着 Java SE 8 的发布，repeating annotations 支持你这样做。
例如，你正在编写一段使用定时器服务的代码，它确保你根据特定时间或计划运行某个方法，类似于 UNIX 的 cron 服务。现在你想为 doPeriodicCleanup 设定一个计时器，让它在每月最后一天，和每周五下午 11 点运行代码。为了启动定时器，创建一个 @Schedule 注解，随后在 doPeriodicCleanup 上运用两次。第一次指定每月最后一天，第二次指定每周五下文 11 点，就像下面的示例代码那样：
@Schedule(dayOfMonth = "last")
@Schedule(dayOfWeek = "Fri", hour = "23")
public void doPeriodicCleanup(){ /* ... */ }之前的代码将注解应用到了方法上。你可以在任何可以使用注解的地方重复单个注解。例如，你有一个处理未认证访问异常的类。你在它之上分别为经理和其他管理员添加了 @Alert 注解：
@Alert(role = "Manager")
@Alert(role = "Administrator")
public class UnauthorizedAccessException extends SecurityException {
// ...
}出于兼容性考虑，重复注解被储存在编译器自动生成的 container annotation 中。为了让编译器支持该操作，你的代码中需要加上两个声明。
Step 1: Declare a Repeatable Annotation Type
注解类型必须被 @Repeateable 元注解标记。下面的例子定义了一个自定义的可重复注解 @Schedule：
import java.lang.annotation.Repeatable;
@Repeatable(Schedules.class)
public @interface Schedule {
String dayOfMonth() default "first";
String dayOfWeek() default "Mon";
int hour() default 12;
}元注解 @Repeateable 位于圆括号中的值，是容器注解类型，它由 Java 编译器产生，用来存储重复注解。此例中，容器注解类型是 Schedules，所以重复的 @Schedule 注解被存储到 @Schedules 中。
在声明上重复使用相同注解，如果该注解没有被定义为 repeatable，将产生编译时错误。
Step 2: Declare the Containing Annotation Type
容器注解类型必须包含名为 value 的数组元素。数组的成员类型必须是可重复注解类型。Schedules 容器注解类型的声明就像这样：
public @interface Schedules {
Schedule[] value();
}Retrieving Annotations
在 Reflection API 里有几种获取注解的方法。对于返回单个注解的方法，如 AnnotatedElement.getAnnotation(Class\<T>)，如果仅存在一个所请求的注解，它的行为不发生改变。如果存在多个所请求的注解，你得到的将是它们的容器注解。在这种情况下，遗留代码仍能工作。Java SE 8 引入了其他方法，如 AnnotatedElement.getAnnotationsByType(Class\<T>).，通过扫描容器注解，一次返回多个注解。阅读 AnnotatedElement 类型规范了解所有可用方法。
Design Considerations
设计注解类型时，你必须考虑这种注解的 cardinality。注解可以被使用零次，一次，或者，如果被标记为 @Repeatable，它可以被使用多次。你可以通过 @Target 元注解限制注解的作用域。例如，创建一个仅可用于方法和属性的可重复注解。细致地设置注解以确保它在使用者手中足够灵活与强大。
Questions and Exercises: Annotations
Questions
1. Question: 下面的接口定义有何错误？
public interface House {
@Deprecated
void open();
void openFrontDoor();
void openBackDoor();
}Answer: 应该同时在文档中反映 open 为何过时，替代的方法是哪个。如：
public interface House {
/**
* @deprecated use of `open`
* is discouraged, use
* `openFrontDoor` or
* `openBackDoor` instead.
*/
@Deprecated
void open();
void openFrontDoor();
void openBackDoor();
}2. Question: 考虑 House 接口的实现类.
public class MyHouse implements House {
public void open() {
}
public void openFrontDoor() {
}
public void openBackDoor() {
}
}编译这段代码，编译器将产生一个警告，因为 open 已经过时了。怎样做才能消除那个警告。
Answer: 为 open 的实现添加 @Deprecated：
public class MyHouse implements House {
// The documentation is
// inherited from the interface.
@Deprecated
public void open() {
}
public void openFrontDoor() {
}
public void openBackDoor() {
}
}或者，抑制那个警告：
public class MyHouse implements House {
@SuppressWarnings("deprecation")
public void open() {
}
public void openFrontDoor() {
}
public void openBackDoor() {
}
}3. Question: 下面的代码能编译通过吗？为什么？
public @interface Meal {
// ...
}
@Meal("breakfast", mainDish = "cereal")
@Meal("lunch", mainDish = "pizza")
@Meal("dinner", mainDish = "selad")
public void evaluateDiet() { /* ... */ }Answer: 不能通过编译。JDK 8 之前没有重复注解。JDK 8 之后，如果要重复使用注解，要将 Meal 声明为 @Repeatable，随后定义其容器注解：
@java.lang.annotation.Repreatable(MealContainer.class)
public @interface Meal {
// ...
}
public @interface MealContainer {
Meal[] value();
}Exercises
1. Exercise: 为增强请求定义一个注解，元素是 id，synopsis，engineer 和 date。为 engineer 指定默认值 unassigned，date 指定默认值 unknown。
Answer:
/**
* Describe the Request-for-Enhancement (RFE) annotation type.
*/
public @interface RequestForEnhancement {
int id();
String synopsis();
String engineer() default "[unassigned]";
String date() default "[unknown]";
}本文译自 Annotations，译者 LOGI。
如有问题请在下方留言，文章转载请注明出处，详细交流请加下方群组！请大佬不要屏蔽文中广告，因为它将帮我分担服务器开支，如果能帮忙点击我将万分感谢。