自从JSR-175，Java 5获得了元数据功能，从而使我们能够使用装饰性语法元数据来注解我们的代码。 可以为类型，字段，方法，参数，构造函数，局部变量，类型参数，类型的使用甚至其他注解类型提供此元数据。 各种各样的工具可以将其用于代码生命周期的不同步骤。

解析注解

一个基本的注解类似：

@Retention(RetentionPolicy.RUNTIME)@Target(ElementType.TYPE)@Inherited@Documentedpublic @interface MyAnnotation {    String name() default "";    int value();}

现在一行行来看，具体解析

@Retention -- 注解生效的生命周期@Target -- 注解用在哪里@Inherited -- 如果存在，会传递给任何子的注解@Document -- 如果存在，文档类似javadoc格式[@interface] -- 注解的类型标记基本使用

最简单的注解用法是在兼容的目标站点上使用@MyAnnotation。 但是，如果未提供默认值，则注解可以具有多个可能需要设置的值。 值名称value()是一个特殊的名称。 如果没有其他值，则可以不带名称使用。

// Both values are specified, naming them is required@MyAnnotation(name = "an awesome name", value = 42)public class MyType { ... }// Only "value()" is present, "name()" will be its default value@MyAnnotation(value = 42)public class MyType2 { ... }// Only "value()" needed, we can actually omit the name@MyAnnotation(42)public class MyType3 { ... }

代码的正常生命周期类似:

source ---(Compiler)----> Class -----(JVM)----> Runtime

注解的Retention策略反映了这些生命周期阶段，并为我们提供了一种方法来指定元数据的确切可用性。

RetentionPolicy.SOURCE 注解仅在源码中可用。 编译器将丢弃元数据，因此编译器和运行时都无法访问它。 此retention策略对于预编译工具(例如注解处理器)很有用。RetentionPolicy.CLASS 默认的策略。注解对于编译器是可见的，并且将在类文件中可用，但在运行时不可用。 任何后编译字节码工具都可以使用元数据。RetentionPolicy.RUNTIME 所有元数据运行时可用。

我们针对自定义注解用哪个Retention策略取决于我们的要求。 提供的元数据可能包含有关带注释代码内部工作的敏感信息。 我们应该始终选择尽可能低的保留时间，以使我们的代码仍能正常工作。

@Target

并非每个注解都对每个可用目标有意义。 因此，我们可以明确设置可接受的目标。八个可用的目标在java.lang.annotation.ElementType中定义：

ElementType.PACKAGE: 包声明ElementType.TYPE: 类、接口、枚举ElementType.TYPE_PARAMETER: 泛型类型参数, java8+ElementType.TYPE_USER: 类型，比如声明，泛型，cast java8+ElementType.ANNOTATION_TYPE: 注解ElementType.CONSTRUCTOR:构造函数声明ElementType.FIELD: 类成员和枚举常量ElementType.METHOD: 方法声明ElementType.LOCAL_VARIABLE: 本地变量

@Target 接收一组赋值

// Multi-Target@Target({ ElementType.FIELD, ElementType.Type })​// Single-Target@Target(ElementType.ANNOTATION_TYPE)

如果没有声明，默认支持所有的ElementType，除了TYPE_PARAMETER

@Inherited

默认情况下，不继承注解。 通过将@Inherited添加到注解类型，我们允许它被继承。 这仅适用于带注解的类型声明，该声明将传递给它们的子类型。

@MyAnnotation(value = 42)public class MyType { ... }// Any annotation check at runtime// will also provide "MyAnnotation" and its value 42public class MySubType extends MyType { ... }

Java文档的默认行为是被注解忽略。 使用@Documented，我们可以更改它，从而使元数据及其值可通过文档访问。

@Repeatable

在Java 8之前，我们只能在目标上应用一次特定的注解类型。 在@Repeatable的帮助下，我们现在可以通过提供中间注解来声明可重复的注解：

public @interface MyRepeatableAnnotationContainer {    MyRepeatableAnnotation[] value();}@Repeatable(MyRepeatableAnnotationContainer.class)public @interface MyRepeatableAnnotation {  String value() default "";}

可以再用一次

@MyRepeatableAnnotation@MyRepeatableAnnotation("Foo")@MyRepeatableAnnotation("Bar")public class MyType { ... }

能够注解我们的代码并检查注解是否存在于不同的生命周期事件中，这一点很棒。 但是提供除注解类型本身之外的其他值甚至更好。 甚至支持默认值。

Values是可选的，分割注解为两组:

Marker -- 没有值，仅仅存在就是实际的元数据。比如 @Documented, @Inherited, @OverrideConfiguration -- 有值，默认值就能直接用。比如@Target, @Retention

Java语言规范（JLS）将配置分为普通注解和单元素注解。 但是我认为，这两个行为的重叠程度足以被视为（几乎）相等。

配置注解支持多个值。 允许的类型在JLS 9.6.1中定义：

基本类型String类型 Class 或者 Class<T>枚举注解数组

数组是特殊处理。 如果使用时仅提供一个值，则可以省略花括号。

@Retention(RetentionPolicy.RUNTIME)@Target(ElementType.TYPE)public @interface Values {    String name() default "";    int value();    Class allowedTypes() default String.class,    ElementType[] types();}

尽管不能接受null，但默认值必须是常量表达式。 数组可以使用{}作为默认值来返回一个空数组。

JDK存在的一些注解

除了之前提到的，JDK还包含多个注解：

@Override 指示方法覆盖/替换继承的方法。 此信息不是严格必需的，但有助于减少错误。 如果我们想覆盖一个方法，但是签名中的类型很简单，或者参数类型错误，那么该错误可能不会引起注意。 但是，如果提供@Override批注，则编译器将确保我们实际上重写了一个方法，而不仅仅是偶然地添加或重载了该方法。@Deprecated 另一个仅编译的注释。 我们可以将代码标记为已弃用，并且编译器/ IDE可以访问此信息以告诉我们不再使用该代码。 从Java 9开始，此先前的标记注解变为配置注解。 添加了 String since() default "" 和 boolean forRemoval() default false，以为编译器和IDE提供更多信息。@FunctionInteface 从Java 8开始，我们可以将接口标记为单一抽象方法接口（SAM），因此可以将它们用作lambda。 该标记注释使编译器可以确保接口仅具有一个单一的抽象方法。 如果我们添加另一个抽象方法，我们的代码将不再编译。 此注释可进行编译器检查，但并非绝对必要。 任何SAM都会自动成为功能接口。@SafeVarargs 另一个“相信我，我最牛逼的标记注释。 告诉编译器使用varargs时，我们不会执行任何不安全的操作。@SuppressWarnings 配置批注，接受警告名称的数组，这些警告名称应在编译期间禁用

怎么运行时访问

仅添加元数据还不够。 我们还需要以某种方式访问它。 多亏了反射，我们可以通过class-object访问它：

检查注解

Class<MyAnnotatedType> clazz = anInstance.getClass();// or: Class<MyAnnotatedType> clazz = MyAnnotatedType.class;// Target: Packageboolean isTypeAnnotationPresent =    clazz.getPackage().isAnnotationPresent(MyAnnotation.class);// Target: Typeboolean isTypeAnnotationPresent =    clazz.isAnnotationPresent(MyAnnotation.class);// Target: MethodMethod method = clazz.getMethod("myMethod");boolean isMethodAnnotationPresent =    method.isAnnotationPresent(MyAnnotation.class);// Target: FieldField field = clazz.getField("myField");boolean isFieldAnnotationPresent =    field.isAnnotationPresent(MyAnnotation.class);

类似 boolean isAnnotationPresent(Class<? extends Annotation> annotationClass), 我们还具有访问实际注解实例的方法，从而为我们提供了对其值的访问。

以下是适用于不同目标的一些方法：

Classes<A extends Annotation> A getAnnotation(Class<A> annotationClass): 返回具体的注解，不存在 nullAnnotation[] getAnnotations(): 返回所有的注解<A extends Annotation> A[] getAnnotationsByType(Class<A> annotationClass): 返回传入注解类型的所有注解Methods<T extends Annotation> T getAnnotation(Class<T> annotationClass) : 返回具体类型的注解，不存在nullAnnotation[] getDeclaredAnnotations() : 返回方法的所有注解Annotation[] getParameterAnnotations(): 返回一个二维数组， 包含所有参数的注解，已声明的顺序用例

一个很好的用例是序列化。 通过注释，可以提供有关如何处理我们的数据结构的许多其他元数据。

Jackson是JSON序列化框架，使用@JsonProperty批注提供修改默认序列化过程所需的所有信息：

class Pojo implements Serializable {    private String name;    @JsonProperty(value = "name",                  required = true,                  access = ACCESS.READ_ONLY)    public String getName() {        return this.name;    }    public void setName(String name) {        this.name = name;    }}

另一个出色的用例是RESTEasy如何使用注释来描述REST API，因此在其他地方不需要其他配置：

@Path("/v1")@Produces("application/json")public class LoginController {    @POST    @Path("/login")    Response login(@FormParam("username") String username,                   @FormParam("password") String passowrd,                   @HeaderParam("User-Agent") String userAgent) {...}    @HEAD    @Path("/")    Response health() {}}

结论

注解是为自己或第三方工具和库提供附加数据的好方法。 但是请注意解析，编译和查找批注的额外成本，尤其是在运行时。

参考The Java Tutorials — Annotations (Oracle)java.lang.annotation package summary (JavaSE 8)Creating a Custom Annotation (Baeldung)