Java注解Target、Retention、Inherited、Documented的作用简述，以@Transactional注解为例（处女座总结）

﹏ヽ暗。殇╰゛Y 2022-12-23 13:26 142阅读 0赞

**原创博文，欢迎转载，转载时请务必附上博文链接，感谢您的尊重。**

# 前言 #

通过本篇，你将学会@Target、@Retention、@Inherited、@Documented注解的含义，以及他们的使用场景，方便大家更好的学习源码。

写作本篇的原因，是在我在研究Spring事务 @Transactional 注解源码时候，需要优先解决注解的含义。借助这个机会，我打算全面的研究一下，并总结下来以备不时之需。

![20201125111456252.png][]

上述四种注解按分类属于元注解（meta-annotation），是指负责注解其他注解的注解，是JDK 1.5及以后版本定义的4个标准的元注解类型。

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

# 一、@Target注解 #

![20201125143020767.png][]

用于设定注解使用范围（即：被描述的注解可以用在什么地方），注解的值是 **enum **类型的 **ElementType**，包括以下几种情况：

<table> 
 <thead> 
  <tr> 
   <th>取值</th> 
   <th>注解使用范围</th> 
  </tr> 
 </thead> 
 <tbody> 
  <tr> 
   <td>METHOD</td> 
   <td>可用于方法上，用于描述方法</td> 
  </tr> 
  <tr> 
   <td>TYPE</td> 
   <td>可用于类或者接口上，用于描述类、接口(包括注解类型) 或enum声明</td> 
  </tr> 
  <tr> 
   <td>ANNOTATION_TYPE</td> 
   <td>可用于注解类型上（被@interface修饰的类型）</td> 
  </tr> 
  <tr> 
   <td>CONSTRUCTOR</td> 
   <td>可用于构造方法上，用于描述构造器</td> 
  </tr> 
  <tr> 
   <td>FIELD</td> 
   <td>可用于域上，用于描述域</td> 
  </tr> 
  <tr> 
   <td>LOCAL_VARIABLE</td> 
   <td>可用于局部变量上，用于描述局部变量</td> 
  </tr> 
  <tr> 
   <td>PACKAGE</td> 
   <td>用于记录java文件的package信息，用于描述包</td> 
  </tr> 
  <tr> 
   <td>PARAMETER</td> 
   <td>可用于参数上，用于描述参数</td> 
  </tr> 
 </tbody> 
</table>

**重点说明下：**如果某个注解用@Target标明了适用范围（该范围可以使多个，参照 @Transactional 注解），那么它就只能在 ElementType 设定的范围内使用，否则将会编译报错。

**举例说明：**如果范围只包含ElementType.METHOD ，则表明该注解只能使用在类的方法上，超出使用范围将编译异常。

# 二、@Retention注解 #

![20201125143043266.png][]

用于设定注解的生命周期（位置），注解的值是 **enum **类型的 **RetentionPolicy**，包括以下几种情况：

<table> 
 <thead> 
  <tr> 
   <th>取值</th> 
   <th>注解生命周期</th> 
  </tr> 
 </thead> 
 <tbody> 
  <tr> 
   <td>SOURCE</td> 
   <td>该类型的Annotations只保留在源文件，当Java文件编译成class文件的时候，注解被遗弃</td> 
  </tr> 
  <tr> 
   <td>CLASS</td> 
   <td>该类型的Annotations在编译时被保留到.class文件，但JVM加载.class文件时候被遗弃，这是默认的生命周期</td> 
  </tr> 
  <tr> 
   <td>RUNTIME</td> 
   <td>该类型的Annotations将被JVM保留，不仅被保存到.class文件中，JVM加载.class文件之后也仍然存在，所以他们能在运行时被JVM或其他使用反射机制的代码所读取和使用</td> 
  </tr> 
 </tbody> 
</table>

生命周期分别对应于：Java源文件(.java文件) → .class文件→ 内存中的字节码，生命周期的长度分别对应于： SOURCE < CLASS < RUNTIME，前者能作用的地方后者一定也能作用。

那怎么来选择合适的注解生命周期呢？

1.  如果需要在运行时去动态获取注解信息，那只能用 RUNTIME 注解，这也是我们自定义注解常使用的参数；
2.  如果要在编译时进行一些预处理操作，比如生成一些辅助代码（如 [ButterKnife][]），就用 CLASS注解；
3.  如果只是做一些检查性的操作，比如** @Override** 和 **@SuppressWarnings**，则可选用 SOURCE 注解。

# 三、@Inherited注解 #

![20201125143103575.png][]

这是一个稍微复杂的注解类型，它指明注解类的属性会被子类自动继承。（说它复杂，其实主要就是前面这句作用的描述有点抽象，晦涩难懂）

**举例说明：**我们创建了一个自定义注解 @Verification，并使用了 @Inherited 元注解标记了它，@Target 注明作用范围是TYPE（类），然后用 @Verification 和 @Documented 注解来标注另一个父类（Grade），再定义一个子类（Class）,那么父类（Grade）的所有属性将被继承到它的子类（Class）中，包括 @Documented 注解的文档特性（没错，注解也可以被继承）。

这就是 @Inherited 的魅力所在，@Transactional 注解的事务的延展特性可以很完美的解释上面的举例。

# 四、@Documented注解 #

![20201125143114133.png][]

用于描述其它类型的注解应该被作为被标注的程序成员的公共API，因此可以被例如 javadoc 此类的工具文档化。

这个注解我并没有深入研究，因为它并不影响源码的运行和逻辑，大家了解含义，明白使用就好。

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

# 五、总结 #

通过上面对@Target、@Retention、@Inherited、@Documented 注解含义的理解，可以非常直观且高效的帮助我们理解 @Transactional 注解特性：

1.  @Target(\{ElementType.TYPE, ElementType.METHOD\})：设定注解使用范围是类和方法上；
2.  @Retention(RetentionPolicy.RUNTIME)：设定生命周期为全周期，支持使用反射机制的代码读取和使用；
3.  @Inherited：指明如果该注解修饰的父类被子类继承，那么子类也具备事务特性；
4.  @Documented：表明这个注解应该被 javadoc工具记录。

#  #

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

**我是一名小白程序员，您的点赞、评论和关注，是我不懈创作的动力！！  
学无止境，气有浩然，让我们一起加油，乘风破浪，江湖有缘再见。**

[20201125111456252.png]: /images/20221120/a21fac82e7d84c3e81dc53aea12f1fb5.png
[20201125143020767.png]: /images/20221120/7c5fd643e47b4b77886b980857e1eafd.png
[20201125143043266.png]: /images/20221120/eb0e8036a8f94002a03b5b0ca7ed5457.png
[ButterKnife]: https://github.com/JakeWharton/butterknife
[20201125143103575.png]: /images/20221120/b54f1d8f079e491f8e91cd2276753b05.png
[20201125143114133.png]: https://img-blog.csdnimg.cn/20201125143114133.png