Java注解的原理和使用详解

保留所有版权，请引用而不是转载本文（原文地址 https://yeecode.top/blog/50/ ）。

Java注解是一种标注。Java中的类、方法、变量、参数、包等均可以被注解标注从而被添加额外的信息。相比于直接修改代码的硬编码方式，基于注解的这种松耦合的信息添加方式受到了广泛的欢迎。

本文，我们将对注解的声明方式、注解的原理进行详细的介绍。

1. 元注解

随便打开一个注解类，我们会发现它们中也包含注解。例如下面代码所示的@Param注解（来自MyBatis源码）中就存在@Documented、@Retention、@Target等注解。这些用来注解其他注解的注解，称为元注解。

@Documented // 表明该注解会保留在API文档中
@Retention(RetentionPolicy.RUNTIME) // 表明注解会保留到运行阶段
@Target(ElementType.PARAMETER) // 表明注解可以应用在参数上
public @interface Param {
  String value(); // 整个注解只有一个属性，名为value
}

元注解一共有五个，分别是：@Target、@Retention、@Documented、@Inherited、@Repeatable，我们分别进行介绍。

@Target注解用来声明注解可以用在什么地方，它的值需要从枚举类ElementType中选取。ElementType的枚举值及其含义如下：

• TYPE：类、接口、注解、枚举
• FIELD：字段
• METHOD：方法
• PARAMETER：参数
• CONSTRUCTOR：构造方法
• LOCAL_VARIABLE：本地变量
• ANNOTATION_TYPE：注解
• PACKAGE：包
• TYPE_PARAMETER：类型参数
• TYPE_USE：类型使用

例如我们要声明一个注解只能声明在参数上，则可以如下所示进行设置。

@Target(ElementType.PARAMETER)

元注解也有Target值，而且该值都是ElementType.ANNOTATION_TYPE，表明它们只能声明在注解上。

当然，以上枚举值也可以选择多个，例如下面代码声明注解可以用在字段和方法上。

@Target(value={ElementType.FIELD, ElementType.METHOD})

@Retention注解用来声明注解的生命周期，即表明注解会被保留到哪一阶段。它的值需要从枚举类RetentionPolicy选取。RetentionPolicy的枚举值如下：

• SOURCE：保留到源代码阶段。这一类注解一般是留给编译器使用，在编译时会被擦除。
• CLASS：保留到类文件阶段。这是默认的生命周期，注解会保留到类文件阶段，但是JVM运行时不包含这些信息.
• RUNTIME：保留到JVM运行阶段。如果我们想在程序运行时获得注解，则需要保留在这一阶段。

@Documented不需要设置具体的值。如果一个注解被@Documented标注，则该注解会被生成到javadoc中。

@Inherited不需要设置具体的值。如果一个注解被@Inherited标注，表明允许子类继承父类的该注解（可以从父类继承该注解，但是不能从接口继承该注解）。

@Repeatable是JDK 8中新加入的。如果一个注解被@Repeatable标注，则该注解可以在同一个地方被重复使用多次。用@Repeatable来修饰注解时需要指明一个接受重复注解的容器。

（以上均参考自书籍《通用源码阅读指导书——MyBatis源码详解》）

2. 自定义注解

自定义一个注解非常简单，需要使用元注解进行一些声明，然后就可以定义注解中的属性。下面代码给出了一个自定义注解的示例。

@Target(value=ElementType.METHOD) // 表明该注解可以标注到方法上
@Retention(RetentionPolicy.RUNTIME) // 表明该注解会保留到运行时
@Documented // 表明该注解会被生成到javadoc中
public @interface Yeecode { // 自定义注解的名称为Yeecode
    String name(); // 一个属性
    String value() default "123"; // 一个指定了默认值的属性
    int age() default 12;
    SizeUnits height() default SizeUnits.CM;
    Class<?> clazz();
    int[] index() default {0,1};
}

在定义注解的属性时，是使用方法的形式来定义的，即属性名就是方法名。每个属性都可以定义默认值。如果不为属性指定默认值，则在使用时必须赋值。

属性的类型很灵活，可以是字符串、基本类型、枚举类型、注解、Class类型，以及以上类型的一维数组。

如果一个注解只有一个名为value的属性，则在使用过程中为该属性赋值时可以省略属性名。

3. 总结

可见，Java中注解的创建并不复杂，只要学会使用元注解即可。而注解，最主要的是解析，即如何解析已经定义好并使用在某些地方的注解。

关于注解的使用，最常见的例子就是MyBatis中的Param注解。通过它，我们可以定义向MyBatis传入的参数。

《通用源码阅读指导书——MyBatis源码详解》一书对注解的定义以及解析进行了详细的介绍，大家可以参考这本书。

《通用源码阅读指导书》

《通用源码阅读指导书——MyBatis源码详解》是一本以MyBatis的源码为实例讲述源码阅读方法的书籍，并且附带有示例项目源码，MyBatis的全中文注解。书籍还总结了大量的编程知识和架构经验，对提升编程和架构能力十分有用，非常推荐。

在下面的文章中，我们会介绍MyBatis中Param注解的解析过程。

可以访问个人知乎阅读更多文章：易哥（https://www.zhihu.com/people/yeecode），欢迎关注。

作者书籍推荐