JAVA 注解详解（java中注解是什么）

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

解析注解

一个基本的注解类似：

@Retention(RetentionPolicy.RUNTIME)
@Target(ElementType.TYPE)
@Inherited
@Documented
public @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 { ... }

@Retention

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

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 42
public class MySubType extends MyType { ... }

@Documented

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 { ... }

注解value

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

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

• Marker -- 没有值，仅仅存在就是实际的元数据。比如 @Documented, @Inherited, @Override
• Configuration -- 有值，默认值就能直接用。比如@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: Package
boolean isTypeAnnotationPresent =
    clazz.getPackage().isAnnotationPresent(MyAnnotation.class);

// Target: Type
boolean isTypeAnnotationPresent =
    clazz.isAnnotationPresent(MyAnnotation.class);

// Target: Method
Method method = clazz.getMethod("myMethod");
boolean isMethodAnnotationPresent =
    method.isAnnotationPresent(MyAnnotation.class);

// Target: Field
Field 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)