Java 基础——注解

冷不防 2023-10-06 19:03 18阅读 0赞

#### 目录 ####

*  1.注解概述
 *  2.Java 提供的 5 个基本注解
 *  3.注解入门使用
 *  4.✨自定义注解
 *  5.通过反射获取注解信息
 *  6.✨注解解析的底层实现

> 本文章部分笔记整理来自https://www.bilibili.com/video/BV12k4y1q73J?p=333

## 1.注解概述 ##

（1）注解 (Annotation)，也称为元数据，它是一种代码级别的说明，是 JDK 1.5 及以后版本引入的一个特性，与类、接口、枚举是在同一个层次。它可以声明在包、类、字段、方法、变量、参数等的前面，用来对它们进行说明。其作用大致可以分为以下三类：

<table> 
 <thead> 
  <tr> 
   <th>编写文档</th> 
   <th>通过代码里标识的注解生成文档【例如生成文档doc文档】</th> 
  </tr> 
 </thead> 
 <tbody> 
  <tr> 
   <td>代码分析</td> 
   <td>通过代码里标识的注解对代码进行分析（例如在框架中通常会采用注解的方式来代替配置文件，再通过反射获取注解中配置的信息）</td> 
  </tr> 
  <tr> 
   <td>编译检查</td> 
   <td>通过代码里标识的注解让编译器能够实现基本的编译检查【例如Override】</td> 
  </tr> 
 </tbody> 
</table>

（2）注解本质是一个继承了Annotation 的特殊接口：

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

（3）注解只有被解析之后才会生效，常见的解析方法有以下两种：

*  **编译期直接扫描**：编译器在编译 Java 代码的时候扫描对应的注解并处理，比如某个方法使用 @Override 注解，编译器在编译的时候就会检测当前的方法是否重写了父类对应的方法。
 *  **运行期通过反射处理**：像框架中自带的注解，比如 Spring 框架的 @Value 、@Component 都是通过反射来进行处理的。

（4）Java 注解主要解决了以下几个问题：

*  **代码可读性和维护性问题**：通过给代码添加注解，可以为代码**提供更加清晰明确的含义和解释**，从而提高代码可读性和代码维护性。同时，通过注解，还可以为代码提供更加详细的说明和附加信息。
 *  **配置和约束问题**：注解可以为代码**提供更加灵活和细致的配置和约束信息**，从而可以在编译期或运行期自动化地进行检查和约束，防止代码出现潜在的问题。比如，可以使用注解来标记某个方法或变量是过时的，或者限制某个方法的访问权限等。
 *  **元数据管理问题**：注解可以提供元数据信息，从而可以通过反射来获取代码的元数据，进而可以对元数据进行**自动化管理和处理**。比如，可以使用注解来自动生成文档或 API，或者从源代码中提取相关的元数据信息。

总的来说，Java 注解能够为程序员提供更加便捷和灵活的编程方式，同时也有助于提高代码的可读性和维护性。它主要解决了在代码开发、配置管理、约束检查、元数据处理等方面面临的一些问题。

## 2.Java 提供的 5 个基本注解 ##

<table> 
 <thead> 
  <tr> 
   <th>注解</th> 
   <th>作用</th> 
  </tr> 
 </thead> 
 <tbody> 
  <tr> 
   <td>@Override</td> 
   <td>当子类重写父类方法时，子类可以加上这个注解，那么可以确保子类确实重写了父类的方法，避免出现低级错误</td> 
  </tr> 
  <tr> 
   <td>@Deprecated</td> 
   <td>用于表示某个程序元素类，方法等已过时，当其他程序使用已过时的类，方法时编译器会给出警告（即删除线）</td> 
  </tr> 
  <tr> 
   <td>@SuppressWarnings</td> 
   <td>被该注解修饰的元素以及该元素的所有子元素取消显示编译器警告，例如修饰一个类，那它的字段，方法都是显示警告</td> 
  </tr> 
  <tr> 
   <td>@SafeVarargs</td> 
   <td>断定声明的构造函数和方法的主体不会对其可变参数执行潜在的不安全的操作</td> 
  </tr> 
  <tr> 
   <td>@Functionallnterface</td> 
   <td>保证修饰的接口只有一个抽象方法（注意该注解只能修饰接口）</td> 
  </tr> 
 </tbody> 
</table>

其中注解@SuppressWarnings(“参数”)后面的括号中不同的参数可以表示去除不同的警告类型：

<table> 
 <thead> 
  <tr> 
   <th>参数</th> 
   <th>去除的警告类型</th> 
  </tr> 
 </thead> 
 <tbody> 
  <tr> 
   <td>unused</td> 
   <td>变量未使用警告</td> 
  </tr> 
  <tr> 
   <td>deprecation</td> 
   <td>使用了不赞成使用的类或方法时的警告</td> 
  </tr> 
  <tr> 
   <td>unchecked</td> 
   <td>执行了未检查的转换时的警告，例如当使用集合时没有用泛型(Generics) 来指定集合保存的类型</td> 
  </tr> 
  <tr> 
   <td>fallthrough</td> 
   <td>当 Switch 程序块直接通往下一种情况而没有 Break 时的警告</td> 
  </tr> 
  <tr> 
   <td>path</td> 
   <td>在类路径、源文件路径等中有不存在的路径时的警告</td> 
  </tr> 
  <tr> 
   <td>serial</td> 
   <td>当在可序列化的类上缺少 serialVersionUID 定义时的警告</td> 
  </tr> 
  <tr> 
   <td>finally</td> 
   <td>任何 finally 子句不能正常完成时的警告</td> 
  </tr> 
  <tr> 
   <td>all</td> 
   <td>关于以上所有情况的警告</td> 
  </tr> 
 </tbody> 
</table>

## 3.注解入门使用 ##

package jf_Annotation;
    
    //案例: 注解入门
    
    //忽略所有警告信息
    @SuppressWarnings("all")       
    public class AnnotationDemo01 {
        
        
        //标记方法已过时，不推荐使用（但是还是可以使用）
        @Deprecated
        public static void show(){
        
            System.out.println("show!");
        }
        
        public static void main(String[] args) {
        
            //需求1: 调用show()方法
            //在调用时，IDEA提示的show()方法上会有删除线，表示该方法已经过时，不推荐使用
            show();
            
            //需求2: 去重警告
            int a = 10;
        }
    }

## 4.✨自定义注解 ##

（1）要自定义一个注解，可以使用 Java 的注解声明语法来定义。以下是自定义注解的基本步骤：

*  使用 `@interface` 关键字**创建一个新的注解类型**。
 *  在注解内部**定义需要的属性和方法**。注解属性使用成员变量的形式声明，可以指定默认值。方法用来获取注解属性的值。
 *  可以在注解中使用元注解，如 @Retention、@Target 等，来指定注解的保留策略和适用范围。
 *  使用自定义注解时，可以在合适的位置（类、方法、字段等）标记注解。

（2）自定义注解 `@Book1` 和 `@Book2`

/*
    	自定义注解里边可以写的内容包括：
        1.八种基本类型
        2.String 类型, Class类型, 枚举类型, 注解类型
        3.以上所有类型的数组形式
    */
    public @interface Book1 {
        
       public String value();                //书名
       public double price() default 100;    //价格，默认值为 100
       public String[] characters();         //人物
    }

//自定义的注解 Book2
    public @interface Book2 {
        
        public String value();
    }

> 注意：当注解中只有一个属性且名称是 value，在使用注解时给 value 属性赋值可以直接给属性值，无论 value 是单值元素还是数组类型

（3）使用自定义注解

//案例: 自定义类 BookShelf, 表示书架, 类上有注解
    /*
        注意事项:
        1.如果属性有默认值，则使用注解的时候，这个属性可以不用赋值。
        2.如果属性没有默认值，那么在使用注解时一定要给属性赋值。
     */
    @Book1(value = "西游记", characters = {
        "孙悟空", "猪八戒"})
    @Book2(value = "三国演义")  //或者 @Book2("三国演义")
    public class BookShelf {
        
        public void showBook() {
        
    
        }
    }

## 5.通过反射获取注解信息 ##

（1）自定义注解

/*
        元注解：元注解就是用来对自定义的注解进行一些限定的, 常用的元注解有:
        @Target     用来限定注解可以写在哪个地方, 如果不写默认是人可以地方都可以用此注解.
        @Retention  用来定义注解的生命周期(即: 注解的有效范围)
     */
    @Target({
        ElementType.METHOD, ElementType.TYPE})     //限定此注解只能写到方法上或者类上
    @Retention(RetentionPolicy.RUNTIME)     			//说明该注解在源码阶段、字节码阶段、程序运行阶段都有效
    public @interface Book {
        
       public String value();                  //书名
       public double price() default 50;       //价格，默认值为 50
       public String[] characters();           //人物
    }

（2）使用自定义注解

//案例: 自定义的类, 表示书架, 类上有注解
    @Book(value = "西游记",price = 60,characters = {
        "孙悟空", "猪八戒"})
    public class BookShelf {
        
        @Book(value = "三国演义", characters = {
        "刘备", "关羽", "张飞"})
        public void showBook() {
        
    
        }
    }

（3）获取注解信息  
通过 Java 技术获取注解数据的过程则称为**注解解析**，`Anontation` 是所有注解类型的公共接口，AnnotatedElement 接口定义了与注解解析相关的方法，常用的方法以下四个：

<table> 
 <thead> 
  <tr> 
   <th>方法</th> 
   <th>作用</th> 
  </tr> 
 </thead> 
 <tbody> 
  <tr> 
   <td><code>boolean isAnnotationPresent(Class annotationClass);</code></td> 
   <td>判断当前对象是否有指定的注解，有则返回 true，否则返回 false。</td> 
  </tr> 
  <tr> 
   <td><code>T getAnnotation(Class&lt;T&gt; annotationClass);</code></td> 
   <td>获得当前对象上指定的注解对象。</td> 
  </tr> 
  <tr> 
   <td><code>Annotation[] getAnnotations();</code></td> 
   <td>获得当前对象及其从父类上继承的所有的注解对象。</td> 
  </tr> 
  <tr> 
   <td><code>Annotation[] getDeclaredAnnotations();</code></td> 
   <td>获得当前对象上所有的注解对象，不包括父类的。</td> 
  </tr> 
 </tbody> 
</table>

//注解常用的场景: 用注解的方式来替代配置文件, 然后通过反射的方式获取注解中的配置信息
    public class BookTest {
        
        public static void main(String[] args) throws NoSuchMethodException {
        
            //需求1: 获取 BookShelf 类上的注解
            method01();
            System.out.println("-------------------------------");
    
            //需求2: 获取 showBook 方法上的注解
            method02();
        }
        
        public static void method01() {
        
            //获取 BookShelf 类的字节码文件对象
            Class<BookShelf> clazz = BookShelf.class;
            //判断 BookShelf 类是否有 Book 注解
            if (clazz.isAnnotationPresent(Book.class)) {
        
                //如果有, 就获取 BookShelf 类上的 Book 注解
                Book book = clazz.getAnnotation(Book.class);
                //输出注解的值，此时将注解当作对象使用即可
                System.out.println("书名: " + book.value());
                System.out.println("价格: " + book.price());
                System.out.println("人物: " + Arrays.toString(book.characters()));
            }
        }
        
        public static void method02() throws NoSuchMethodException {
        
            //获取 BookShelf 类的字节码文件对象
            Class<BookShelf> clazz = BookShelf.class;
            //根据字节码文件对象, 获取指定的方法对象
            Method method = clazz.getMethod("showBook");
            //判断 showBook 方法是否有Book注解
            if (method.isAnnotationPresent(Book.class)) {
        
                //如果有, 就获取 showBook 方法上的 Book 注解
                Book book = method.getAnnotation(Book.class);
                //输出注解的值
                System.out.println("书名: " + book.value());
                System.out.println("价格: " + book.price());
                System.out.println("人物: " + Arrays.toString(book.characters()));
            }
        }
    }

输出结果如下：

书名: 西游记
    价格: 60.0
    人物: [孙悟空, 猪八戒]
    -------------------------------
    书名: 三国演义
    价格: 50.0
    人物: [刘备, 关羽, 张飞]

## 6.✨注解解析的底层实现 ##

（1）注解解析的底层实现主要**依赖于 Java 的反射机制**。Java 反射机制允许在运行时动态地检查和操作类、方法、字段等的信息。通过反射，我们可以获取类的注解信息，并进一步解析注解的属性值。在注解解析的过程中，底层实现一般会采用以下步骤：

*  获取目标元素的 Class 对象，例如类、方法或字段的 Class 对象。
 *  通过 Class 对象的 `getAnnotations()` 方法，获取目标元素上使用的所有注解对象。
 *  遍历注解对象列表，对每个注解对象进行解析。通过注解对象的 Class 对象，我们可以获取注解的属性值。
 *  根据注解的属性值，进行相应的逻辑操作。

（2）具体的解析逻辑可以根据需求而定，有时可能需要递归解析注解，以获取更深层次的信息。需要注意的是，注解解析通常是在编译时或运行时进行的。在编译时，我们可以通过注解处理器 (Annotation Processor) 来解析注解并生成相应的代码。在运行时，我们可以通过反射来获取和解析注解信息。

（3）**注解解析的底层实现主要依赖于 Java 的反射机制，通过反射获取注解对象并解析注解的属性值，从而实现对注解的处理逻辑。**

> 相关知识点：  
> [Java 基础——反射][Java]

（4）为了正确使用和理解自定义注解，需要注意以下几个方面：

*  **确定注解的作用范围和目标**：通过元注解 `@Target` 来指定注解可以被应用于哪些元素，如类、方法、字段等。
 *  **确定注解的生命周期**：通过元注解 `@Retention` 来指定注解的保留策略，如 SOURCE、CLASS 或 RUNTIME。
 *  **设计注解属性**：根据自定义注解的目的，确定需要哪些属性，以及是否需要设置默认值。
 *  **考虑注解的元素类型**：注解属性的类型可以是基本类型、字符串、枚举、Class 类型、注解类型以及它们的数组。

[Java]: https://blog.csdn.net/weixin_43004044/article/details/119856638