自定义Java注解

什么是注解

我们都知道注释，在写程序中经常使用，那么是什么注释呢？
简单来说，就是用文字描述程序，主要的作用呢是给程序员看的。让别人能够读懂我们所写的程序。
注解同样，也是用来说明程序的，不同的是，注解是给计算机看的

我们先说说注解的定义

注解（Annotation)，也叫元数据。一种代码级别的说明。它是 JDK1.5 及以后版本引入的一个特性，与类、接口、枚举实在听一个层次的。它可以声明在包、类、字段、方法、局部变量、方法参数等的前面，用来对这些元素进行说明，注释。

注解的作用

主要分为 编译检查 、编写文档、以及 代码分析

编译检查：通过代码里标识的注解让编译器能够实现基本的编译检查（Override）
编写文档：通过代码里标识的注解生成文档（生成 doc 文档）
代码分析：通过代码里标识的注解对代码进行分析（使用反射）
先说说编译检查：
在类中覆写 toString 方法时，上面标注的 @Override 注解，就是编译检查的情况，该注解会在编译时检查该方法是否是覆写的父类中的方法，如果不是就会编译失败。

    @Override
    public String toString() {
        return "User{" +
                "id=" + id +
                ", uName='" + uName + '\'' +
                ", uPassword='" + uPassword + '\'' +
                '}';
    }

下一个编写文档

/**
 * 注解文档演示
 *
 * @author 作者 V
 * @since JDK1.5之后
 * @version 1.0
 */
public class UserDemo {
    /**
     * 计算两数的和
     * @param a 整数
     * @param b 整数
     * @return 两数的和
     */
    public int add(int a, int b){
        return a + b;
    }
}

比如在类上面使用文档注释，添加 @auther 注解标明作者，@since 表示从以下版本开始，@version 标识版本。
在方法上面使用文档注释，会自动生成一些注解，@param 用于说明参数，@return 说明返回值
可以打开文件位置，在命令行中运行 javadoc 文件名 会抽取信息生成文档，可以点开 index.html 查看。
编译检查 和 编写文档 的使用方式是预先定义好的，我们无法修改。
而 代码分析 ，就是用于自定义注解，我们将会使用反射技术来抽取注解。

JDK中预定义的一些注解

接下来我们了解 JDK 中预定义的几个注解，@Override、@Deprecated、@SuppressWarnings

@Override：检测该注解标注的方法是否是继承自父类接口的
@Deprecated：该注解标注的内容，表示已过时
@SuppressWarnings：压制警告
@Override 注解之前提过，就是在类中覆写 toString 方法时使用的注解
而 @Deprecated 注解，我们看个例子：
如下代码，我们一段代码，我们在他前面写上 @Deprecated 注解后，在其他地方使用的时候，方法名上会出现一条横线，表示这个方法已经过时，但是开始可以继续使用。

@Deprecated
public void show(){
}

@SuppressWarnings 可以对代码中出现的警告进行压制，不再提示警告。

自定义注解

接下来我们看看如何定义注解，首先是注解的格式，下面时 @Override 注解和 @Deprecated 注解的定义。

-----------------------------------------------------
@Target(ElementType.METHOD)
@Retention(RetentionPolicy.SOURCE)
public @interface Override {
}
----------------------------------------------------
@Documented
@Retention(RetentionPolicy.RUNTIME)
@Target(value={CONSTRUCTOR, FIELD, LOCAL_VARIABLE, METHOD, PACKAGE, PARAMETER, TYPE})
public @interface Deprecated {
}
----------------------------------------------------

他们有一个共同的地方，都是 public @interface '注解名称'，以及上面的一些注解。
所以注解的格式可以分为两部分的内容，一个内容上面的 元注解，第二个就是 public @interface '注解名称'。
我们先不看元注解,定义一个自己的注解：

public @interface MyAnno {
}

这是一个最简单的注解，会发现这里出现了一个之前没有见过的类型 @Interface，那这是什么意思呢，我们可以通过反编译，了解他的本质，我们先对这个类进行编译，会生成一个 .class 文件，在使用 javap命令对 .class文件进行反编译，我们打开这个反编译的文件，会发现内容如下：

public interface MyAnno extends java.lang.annotation.Annotation{}

也就是说，注解就是一个接口，而这个接口默认继承了 Annocation类，Annocation类本身并不定义注解类型。
接下来我们说说注解的属性，那么什么是注解的属性，其实就是注解中定义的成员方法，我们在注解中称为属性，比如下面注解中的 str 方法就是注解的属性。

public @interface MyAnno {
    public String str();
}

注解的属性有一些要求，并不是随便什么都可以的：

首先就是属性的返回值类型
1. 基本类型 byte,short,long,char,int,float,double,boolean
2. String类型
3. 枚举
4. 注解
  只有符合以上类型的属性才是符合要求的。

那么注解中的这些成员函数为什么要叫做属性呢，我们看一下，下面的这个例子

@MyAnno()
public class Test {
}

我们创建一个 Test 类，在类的前面使用我们定义的注解
这个时候程序会报一个错误 'str' missing though required ，提示我们需要一个 str 的参数，我们在回头看一眼自定义的注解：

public @interface MyAnno {
    public String str();
}

我们的注解中定义了一个 str 的成员函数，我们怎么解决这个问题呢？我们可以在注解括号中添加上这个函数名称，使用 = 为其赋值，就像是下面这样：

@MyAnno(str="")
public class Test {
}

从这里可以看出，注解中的成员方法为什么叫做属性。
我们可以在属性的后面添加 default关键字设置默认值，它看起来像是这样的：

public @interface MyAnno {
    public String str() default "";
}

需要注意的是，当我们将属性的名称设置为 value，在使用注解的时候，如果只有一个值，我们可以省略名称，直接写值：

----------------------------------------------------------

public @interface MyAnno {
    public String value() default "";
}
----------------------------------------------------------
@MyAnno("str")
public class Test {
}

给数组属性赋值有些不一样，我们使用大括号进行赋值，他看起来向下面这样：

----------------------------------------------------------
public @interface MyAnno {
    public String[] array();
}
----------------------------------------------------------
@MyAnno(array = {"aa", "bb", "cc"})
public class Test {
}

了解了注解的基本定义规则，我们下面开始说 元注解；

简单的说， 元注解 就是描述注解的注解
这听上去很绕。但是这并不难理解，我慢回看一下之前的预定义的注解有哪些元注解。

@Target(ElementType.METHOD)
@Retention(RetentionPolicy.SOURCE)
public @interface Override {
}

这上面有一个 @Target 注解和 @Retention 注解，这两个是最常见的元注解，我们需要了解的元注解有4个，还有两个元注解分别是 @Documented 和 @Inherited。

@Target：描述注解能够作用的位置
@Retention：描述注解被保留的阶段
@Documented：描述注解能否被抽取到 API 文档中
@Inherited：描述注解能否被子类继承

我们先看看 @Target 注解，下面是 @Target 注解的定义

public @interface Target {
    /**
     * Returns an array of the kinds of elements an annotation type
     * can be applied to.
     * @return an array of the kinds of elements an annotation type
     * can be applied to
     */
    ElementType[] value();
}

可以发现他有一个 ElementType 的数组属性，下面是 Element 的部分定义，可以发现他是一个枚举类型，我列出了三个我们需要了解的，

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

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

    /** Method declaration */
    METHOD,
}

TYPE 表示该注解能作用于类上
FIELD 表示该注解能作用于类的成员属性上
METHOD 表示该注解能作用于函数上

下面看一下如何使用，我们在 MyAnno 上添加这个注解，使其只能作用于类上,结果看起来像下面这样：

@Target(value={ElementType.TYPE})
public @interface MyAnno {
}

我们还可以添加其他的作用位置，再添加一个作用于方法上的枚举值，就会像下面这样

@Target(value={ElementType.TYPE, ElementType.METHOD})
public @interface MyAnno {
}

在使用 @MyAnno 注解的时候，我们的注解就只能写在类名和方法名的前面，否这编译就会报错。

接着看看 @Retention 注解，下面是 @Retention 注解的定义

public @interface Retention {
    /**
     * Returns the retention policy.
     * @return the retention policy
     */
    RetentionPolicy value();
}

他需要一个 RetentionPolicy 属性值，下面是 RetentionPolicy 的定义。

public enum RetentionPolicy {
   
    SOURCE,

    CLASS,

    RUNTIME
}

SOURCE：注解保留到编码阶段
CLASS：注解保留到字节码文件阶段
RUNTIME：注解保留到运行时

当我们使用 CLASS 他看起来像下面这样：

@Retention(RetentionPolicy.CLASS)
public @interface MyAnno {
}

剩下的两个就不做详细的介绍，我们这里简单解释一下，
@Documented 有这个元注解的注解，我们在对代码执行 javadoc 命令的时候，注解会被抽取到 API 文档中。
@Inherited 如果注解上有这个元注解，编写代码的时候，如果类上使用了 MyAnno 注解，那么这个类的子类就会有这个注解，无需再次标注。

如何使用

我们已经知道了如果定义注解，接下来我们看一下如何使用（解析）注解，前面我们可以给注解添加属性并给注解赋值，我们既然赋值了，就希望将这些值用起来，我们看一下如何获取注解中定义的值。看一个例子，我们定义一个注解，用来描述需要执行的类名和方法名，我们期望该注解被使用在类上并保留到RUNTIME阶段，他看起来像如下的结果：

@Target({ElementType.TYPE})
@Retention(RetentionPolicy.RUNTIME)
public @interface MyAnno {
    String className();
    String methodName();
}

接着我们创建一个类用来表示我们需要执行的类，里面添加一个show()方法，它看起来是这样的：

public class DemoClass {
    public void show(){
        System.out.println("DemoClass show()");
    }
}

我慢再创建一个Demo类获取注解的信息，它看起来是这样的：

@MyAnno(className = "com.neuedu.demo.DemoClass", methodName = "show")
public class Demo {
}

下面我们开始解析注解。
先获取 Demo类的字节码文件对象
获取注解对象
调用注解的抽象方法，获取返回值
注意这里没有说调用属性，而是调用抽象方法获取返回值，为什么要怎么说呢，是因为底层会给我们生成一段如下的实现类

public class MyAnnoImmpl implements MyAnno{
    public String className(){
        return "com.neuedu.demo.DemoClass";
    }
    public String methodName(){
        return "show";
    }
}

最后创建类，调用方法，运行会发现控制台输出了 DemoClass show()
具体的 Demo 类内容如下

@MyAnno(className = "com.neuedu.demo.DemoClass", methodName = "show")
public class Demo {
    public static void main(String[] args) throws Exception {
        // 获取 Demo 字节码对象
        Class<Demo> demoClass = Demo.class;
        // 获取注解对象
        MyAnno myAnno = demoClass.getAnnotation(MyAnno.class);
        // 调用注解抽象方法获取返回值
        String className = myAnno.className();
        String methodName = myAnno.methodName();
        // 加载需要执行的类
        Class<?> aClass = Class.forName(className);
        // 创建类对象
        Object instance = aClass.newInstance();
        // 获取方法对象
        Method method = aClass.getMethod(methodName);
        // 执行方法
        method.invoke(instance);
    }
}