Java 注解(Annotation)

逆流者 2020年07月21日 42次浏览

注解(Annotation)

  • 从 JDK 5.0 开始, Java 增加了对元数据(MetaData) 的支持, 也就是Annotation(注解)

  • Annotation 其实就是代码里的特殊标记, 这些标记可以在编译, 类加载, 运行时被读取, 并执行相应的处理。通过使用 Annotation, 我们可以在不改变原有逻辑的情况下, 在源文件中嵌入一些补充信息。代
    码分析工具、开发工具和部署工具可以通过这些补充信息进行验证或者进行部署。

  • Annotation 可以像修饰符一样被使用, 可用于修饰,, 构造器, 方法, 成员变量, 参数, 局部变量的声明, 这些信息被保存在 Annotation 的 “name=value” 对中。

  • 在JavaSE中,注解的使用比较简单,例如标记过时的功能,忽略警告等。在JavaEE/Android中注解占据了更重要的角色,例如用来配置应用程序的任何切面,代替JavaEE旧版中所遗留的繁冗代码和XML配置等。

  • 未来的开发模式都是基于注解的,JPA是基于注解的,Spring2.5以上都是基于注解的,Hibernate3.x以后也是基于注解的,现在的Struts2有一部分也是基于注解的了,注解是一种趋势。一定程度上可以说:框架 = 注解 + 反射 + 设计模式

常见的Annotation

使用 Annotation 时要在其前面增加 @ 符号, 并把该 Annotation 当成一个修饰符使用。用于修饰它支持的程序元素。

生成文档相关的注解

注解说明
@author标明开发该类模块的作者,多个作者之间使用,分割
@version标明该类模块的版本
@see参考转向,也就是相关主题
@since从哪个版本开始增加的
@param对方法中某参数的说明,如果没有参数就不能写
@return对方法返回值的说明,如果方法的返回值类型是void就不能写
@exception对方法可能抛出的异常进行说明 ,如果方法没有用throws显式抛出的异常就不能写

注意:

  • @param @return@exception 这三个标记都是只用于方法的。
  • @param的格式要求:@param 形参名 形参类型 形参说明
  • @return 的格式要求:@return 返回值类型 返回值说明
  • @exception的格式要求:@exception 异常类型 异常说明
  • @param@exception可以并列多个

代码示例:

/**
 * @author wushanghui
 * @date 2020/7/16 17:51
 * @see Math
 * @version	 1.0
 *
 */
public class JavadocAnnotation {

    /**
     * 程序的主方法,程序的入口
     *
     * @param args String[] 命令行参数
     */
    public static void main(String[] args) {
        System.out.println(getArea(1.0d)); // 3.141592653589793
    }


    /**
     * 求圆面积的方法
     * @since 1.0
     * @param radius double 半径值
     * @return double 圆的面积
     */
    public static double getArea(double radius) {
        return Math.PI * radius * radius;
    }
}

JDK内置的基本注解(在编译时进行格式检查)

  • @Override: 限定重写父类方法, 该注解只能用于方法
  • @Deprecated: 用于表示所修饰的元素(类, 方法等)已过时。通常是因为所修饰的结构危险或存在更好的选择
  • @SuppressWarnings: 抑制编译器警告

跟踪代码依赖性,实现替代配置文件功能

如框架中使用的注解,后续解读框架中详细阐述

  • Servlet3.0提供了注解(annotation),使得不再需要在web.xml文件中进行Servlet的部署。
  • spring框架中关于“事务”的管理

自定义 Annotation

  • 定义新的 Annotation 类型使用 @interface 关键字
  • 自定义注解自动继承了java.lang.annotation.Annotation接口
  • Annotation 的成员变量在 Annotation 定义中以无参数方法的形式来声明。其方法名和返回值定义了该成员的名字和类型。我们称为配置参数。类型只能是八种基本数据类型String类型Class类型enum类型Annotation类型、以及所有类型的数组
  • 可以在定义 Annotation 的成员变量时为其指定初始值, 指定成员变量的初始值可使用 default 关键字
  • 如果只有一个参数成员,建议使用参数名为value
  • 如果定义的注解含有配置参数,那么使用时必须指定参数值,除非它有默认值。格式是“参数名 = 参数值”,如果只有一个参数成员,且名称为value,可以省略“value=”
  • 没有成员定义的 Annotation 称为标记; 包含成员变量的 Annotation 称为元数据 Annotation

自定义注解必须配上注解的信息处理流程才有意义,下面我们先简单体验下注解的用法:
定义三个注解:水果名称、水果颜色、以及水果供应者注解

/**
 * 水果名称注解
 */
@Target(FIELD)
@Retention(RUNTIME)
@Documented
public @interface FruitName {
    String value() default "";
}

/**
 * 水果颜色注解
 */
@Target(FIELD)
@Retention(RUNTIME)
@Documented
public @interface FruitColor {
    /**
     * 颜色枚举
     */
    public enum Color {
        BLUE,
        RED,
        GREEN
    }

    /**
     * 颜色属性
     */
    Color fruitColor() default Color.GREEN;

}

/**
 * 水果供应者注解
 */
@Target(FIELD)
@Retention(RUNTIME)
@Documented
public @interface FruitProvider {
    /**
     * 供应商编号
     */
    public int id() default -1;

    /**
     * 供应商名称
     */
    public String name() default "";

    /**
     * 供应商地址
     */
    public String address() default "";
}

定义一个Apple实体来标注注解

/**
 * 注解使用
 */
public class Apple {

    @FruitName("红富士苹果")
    private String appleName;

    @FruitColor(fruitColor = FruitColor.Color.RED)
    private String appleColor;

    @FruitProvider(id = 1, name = "陕西红富士集团", address = "陕西省西安市延安路89号红富士大厦")
    private String appleProvider;

    public void setAppleColor(String appleColor) {
        this.appleColor = appleColor;
    }

    public String getAppleColor() {
        return appleColor;
    }

    public void setAppleName(String appleName) {
        this.appleName = appleName;
    }

    public String getAppleName() {
        return appleName;
    }

    public void setAppleProvider(String appleProvider) {
        this.appleProvider = appleProvider;
    }

    public String getAppleProvider() {
        return appleProvider;
    }

    public void displayName() {
        System.out.println("水果的名字是:苹果");
    }
}

利用反射来读取注解的信息

/**
 * 注解处理器
 */
public class FruitInfoUtil {

    public static void getFruitInfo(Class<?> clazz) {

        String strFruitName = "水果名称:";
        String strFruitColor = "水果颜色:";
        String strFruitProvider = "供应商信息:";

        Field[] fields = clazz.getDeclaredFields();

        for (Field field : fields) {
            if (field.isAnnotationPresent(FruitName.class)) {
                FruitName fruitName = field.getAnnotation(FruitName.class);
                strFruitName = strFruitName + fruitName.value();
                System.out.println(strFruitName);
            } else if (field.isAnnotationPresent(FruitColor.class)) {
                FruitColor fruitColor = field.getAnnotation(FruitColor.class);
                strFruitColor = strFruitColor + fruitColor.fruitColor().toString();
                System.out.println(strFruitColor);
            } else if (field.isAnnotationPresent(FruitProvider.class)) {
                FruitProvider fruitProvider = field.getAnnotation(FruitProvider.class);
                strFruitProvider = strFruitProvider + " 供应商编号:" + fruitProvider.id() + " 供应商名称:" + fruitProvider.name() + " 供应商地址:" + fruitProvider.address();
                System.out.println(strFruitProvider);
            }
        }
    }
}

测试:

public class FruitTest {

    public static void main(String[] args) {
        FruitInfoUtil.getFruitInfo(Apple.class);
    }
}

结果:

水果名称:红富士苹果
水果颜色:RED
供应商信息: 供应商编号:1 供应商名称:陕西红富士集团 供应商地址:陕西省西安市延安路89号红富士大厦

从结果中可以看到,我们标注在实体Apple上的信息都可以利用反射读取到,关于上述注解中

@Target(FIELD)
@Retention(RUNTIME)
@Documented

是JDK中的元注解,下面详细阐述元注解的使用

JDK中的元注解

  • JDK 的元 Annotation 用于修饰其他 Annotation 定义
  • JDK5.0提供了4个标准的meta-annotation类型,分别是:

Retention
Target
Documented
Inherited

@Retention

@Retention: 只能用于修饰一个 Annotation 定义, 用于指定该 Annotation 的生命周期

@Documented
@Retention(RetentionPolicy.RUNTIME)
@Target(ElementType.ANNOTATION_TYPE)
public @interface Retention {
    RetentionPolicy value();
}

看jdk中源码定义,@Rentention 包含一个 RetentionPolicy 类型(枚举)的成员变量, 使用@Rentention 时必须为该 value 成员变量指定值。

public enum RetentionPolicy {
    SOURCE,
    CLASS,
    RUNTIME
}

有三个枚举类型,我们分别解释下
|类型 |说明 |
|:--|:--|
|RetentionPolicy.SOURCE | 在源文件中有效(即源文件保留)|
|RetentionPolicy.CLASS| 在class文件中有效(即class保留)|
|RetentionPolicy.RUNTIME|在运行时有效(即运行时保留) |
在这里插入图片描述
我们通过这张图可以清楚的看到这三个类型的作用范围,一般在工作中使用RetentionPolicy.RUNTIME比较多。

@Target

@Target: 用于修饰 Annotation 定义, 用于指定被修饰的 Annotation 能用于修饰哪些程序元素。

@Documented
@Retention(RetentionPolicy.RUNTIME)
@Target(ElementType.ANNOTATION_TYPE)
public @interface Target {
    ElementType[] value();
}

@Target 也包含一个名为 value 的成员变量,类型是ElementType(枚举)数组。

public enum ElementType {
    /** Class, interface (including annotation type), or enum declaration */
    TYPE,

    /** Field declaration (includes enum constants) */
    FIELD,

    /** Method declaration */
    METHOD,

    /** Formal parameter declaration */
    PARAMETER,

    /** Constructor declaration */
    CONSTRUCTOR,

    /** Local variable declaration */
    LOCAL_VARIABLE,

    /** Annotation type declaration */
    ANNOTATION_TYPE,

    /** Package declaration */
    PACKAGE,

    /**
     * Type parameter declaration
     *
     * @since 1.8
     */
    TYPE_PARAMETER,

    /**
     * Use of a type
     *
     * @since 1.8
     */
    TYPE_USE
}
类型说明
TYPE用于描述类、接口(包括注解类型)或注解声明
FIELD描述域
METHOD描述方法
PARAMETER描述参数
CONSTRUCTOR描述构造器
LOCAL_VARIABLE描述局部变量
ANNOTATION_TYPE描述注解
PACKAGE描述包
TYPE_PARAMETER
TYPE_USE

@Documented

  • @Documented: 用于指定被该元 Annotation 修饰的 Annotation 类将被javadoc 工具提取成文档。默认情况下,javadoc是不包括注解的。
  • 定义为Documented的注解必须设置Retention值为RUNTIME。

@Inherited

  • @Inherited: 被它修饰的 Annotation 将具有继承性。如果某个类使用了被 @Inherited 修饰的 Annotation, 则其子类将自动具有该注解。
    比如:如果把标有@Inherited注解的自定义的注解标注在类级别上,子类则可以继承父类类级别的注解。
public class InheritedTest {

    public static void main(String[] args) {
        Class clazz = Student.class;
        Annotation[] annotations = clazz.getAnnotations();
        for (Annotation annotation : annotations) {
            System.out.println(annotation);
        }
    }
}

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

@MyAnnotation
class Person {

}

class Student extends Person {
    
}

结果:
@base.annotation.inherited.MyAnnotation(value=Inherited)

利用反射获取注解信息(在反射部分涉及)

  • JDK 5.0 在 java.lang.reflect 包下新增了 AnnotatedElement 接口, 该接口代表程序中可以接受注解的程序元素
  • 当一个 Annotation 类型被定义为运行时 Annotation 后, 该注解才是运行时可见, 当 class 文件被载入时保存在 class 文件中的 Annotation 才会被虚拟机读取
  • 程序可以调用 AnnotatedElement对象的如下方法来访问 Annotation 信息。
    在这里插入图片描述

JDK 8中注解的新特性

Java 8对注解处理提供了两点改进:可重复的注解及可用于类型的注解。此外,反射也得到了加强,在Java8中能够得到方法参数的名称。这会简化标注在方法参数上的注解。

可重复注解

import java.lang.annotation.*;
import static java.lang.annotation.ElementType.*;

@Repeatable(MyAnnotation2.class)
@Retention(RetentionPolicy.RUNTIME)
@Target({TYPE, FIELD, METHOD, PARAMETER, CONSTRUCTOR, LOCAL_VARIABLE,TYPE_PARAMETER, TYPE_USE})
public @interface MyAnnotation {

    String value() default "hello";
}

在MyAnnotation 中标注 @Repeatable(MyAnnotation2.class)

import java.lang.annotation.Retention;
import java.lang.annotation.RetentionPolicy;
import java.lang.annotation.Target;

import static java.lang.annotation.ElementType.*;

@Retention(RetentionPolicy.RUNTIME)
@Target({TYPE, FIELD, METHOD, PARAMETER, CONSTRUCTOR, LOCAL_VARIABLE})
public @interface MyAnnotation2 {

    MyAnnotation[] value();
}

MyAnnotation2 中定义的变量是MyAnnotation数组

//jdk 8之前的写法:
//@MyAnnotation2({@MyAnnotation(value="hi"),@MyAnnotation(value="hi")})
@MyAnnotation(value="a")
@MyAnnotation(value="b")
class Person{
    private String name;
    private int age;

    public Person() {
    }
    @MyAnnotation
    public Person(String name, int age) {
        this.name = name;
        this.age = age;
    }
    @MyAnnotation
    public void walk(){
    }
    public void eat(){
    }
}

在jdk1.8之前,我们这么标注:

@MyAnnotation2({@MyAnnotation(value="hi"),@MyAnnotation(value="hi")})

jdk1.8 增加了可重复注解,在使用中可以重复标注:

@MyAnnotation(value="a")
@MyAnnotation(value="b")

类型注解

  • JDK1.8之后,关于元注解@Target的参数类型ElementType枚举值多了两个:TYPE_PARAMETER,TYPE_USE
  • 在Java 8之前,注解只能是在声明的地方所使用,Java8开始,注解可以应用在任何地方。
  • ElementType.TYPE_PARAMETER 表示该注解能写在类型变量的声明语句中(如:泛型声明)。
  • ElementType.TYPE_USE 表示该注解能写在使用类型的任何语句中。

TYPE_PARAMETER

@Retention(RetentionPolicy.RUNTIME)
@Target(ElementType.TYPE_PARAMETER)
public @interface MyAnnotation3 {
}
class TypeDefine<@MyAnnotation3 T>{

   private T t;

    public <@MyAnnotation3 U> U test(U u) {
        return u;
    }
}

TYPE_USE

@Retention(RetentionPolicy.RUNTIME)
@Target(ElementType.TYPE_USE)
public @interface MyAnnotation4 {
}
class Generic<@MyAnnotation4 T>{

    public void show() throws @MyAnnotation4 RuntimeException{

        ArrayList<@MyAnnotation4 String> list = new ArrayList<>();

        int num = (@MyAnnotation4 int) 10L;
    }

}