32、学习 Java 中的注解（参照官方教程）

注解文章目录

一、注解概述（Annotation）

(1) 大概是什么

📖 Annotations, a form of metadata（元数据）, provide data about a program that is not part of the program itself. Annotations have no direct effect on the operation of the code they annotate.
📝 注解是元数据的一种形式，用于提供与程序相关的数据，但这些数据并不是程序的一部分。注解对它们所注释的代码的操作没有直接影响。

(2) 注解的用处

📖① Annotations can be used by the compiler to detect errors or suppress warnings.
📝 注解可以为编译器使用，用于检测错误或抑制警告

📖② 【Compile-time and deployment-time processing】Software tools can process annotation information to generate code, XML files, and so forth.
📝【运行时和部署的时候】软件工具可以通过处理注解信息生成 Java 代码、生成 XML 文件等等 …

📖③【Runtime processing】Some annotations are available to be examined at runtime.
📝 有些注解可在运行时被检测到

二、注解基础

(1) 注解的基本格式

📖 In its simplest form, an annotation looks like the following:
📝 一个注解最简单的格式如下所示：

@Entity

📖 The at sign character (@) indicates to the compiler that what follows is an annotation. In the following example, the annotation’s name is Override:
📝 @ 符号用于告诉编译器 @ 符号后面的内容是一个注解。在下面的例子中，注解的名字是：Override

classDogextendsAnimal{@Overridepublicvoidtest(){super.test();}}

📖 The annotation can include elements, which can be named or unnamed, and there are values for those elements:
📝 注解可以包含元素。元素可以有名字，也可以没有名字。元素如下所示：

@Author(
        name ="庆医",
        date ="2022/5/20")classCommonClass{}

🌼 上面代码中的 name 和 date 是注解的元素
🌼【庆医】和【2022/5/20】是元素的值

@SuppressWarnings(value ="unused")classWhatever{privateString s;}

🌼 上面代码中的 @ 告诉编译器 @ 符号后面的是注解
🌼 SuppressWarnings 是注解名
🌼 value 是 SuppressWarnings 注解的元素
🌼【unused】是 value 元素的值

📖 If there is just one element named value, then the name can be omitted.
📝 如果注解中只写了一个元素，并且元素的名字是 value，那么元素名可以省略掉（如下所示）

//@SuppressWarnings(value = "unused")@SuppressWarnings("unused")classWhatever{privateString s;}

📖 If the annotation has no elements, then the parentheses（圆括号） can be omitted.
📝 如果注解中没有元素，那么注解的圆括号可以省略掉（如下所示）

classDogextendsAnimal{@Override// Override 注解没有元素, 圆括号可以省略publicvoidtest(){super.test();}}

📖 It is also possible to use multiple annotations on the same declaration.
📝 也可以在同一个声明上使用多个注解

classDogextendsAnimal{@Override@SuppressWarnings("unused")publicvoidtest(){int a =66;super.test();}}

📖 The annotation type can be one of the types that are defined in the

java.lang

or

java.lang.annotation

packages of the Java SE API. It is also possible to define your own annotation type.
📝 注解类型可能存在于 Java 标准版的

java.lang

包或

java.lang.annotation

包中。您也可以定义自己的注解类型。

(2) 注解可以使用在哪儿

📖 Annotations can be applied to declarations: declarations of classes, fields, methods, and other program elements. When used on a declaration, each annotation often appears, by convention, on its own line.
📝 注解可以运用于声明：类声明、字段声明、方法声明和其他程序元素的声明。当多个注解使用在同一个声明的时候，每一个注解独占一行。

三、创建注解类型

📖 Many annotations replace comments in code.
📝 很多注解取代了代码中的注释

📖 The annotation type definition looks similar to an

interface

definition where the keyword interface is preceded by the at sign (@).
📝 定义注解类型就像定义一个接口一样。只是接口的关键字（interface）前面增加了 @ 符号【**@** 符号是注解类型的标志】

📖 Annotation types are a form of interface.【注解类型是接口的一种形式】

📖 The body of the annotation definition contains annotation type element declarations, which look a lot like methods. Note that they can define optional default values.
📝 注解定义的主体中包含注解类型元素的定义，注解类型元素的定义看起有点像方法（定义注解类型元素的时候可以提供可选的默认值）

创建注解类型示例：

/**
 * @author 庆医
 * @describe 创建一个注解类型,
 * 花括号中可定义注解的元素（且元素可以有可选的默认值）
 */@Documented// 使 DescribeInfo 注解能够在 javadoc 文档中出现public@interfaceDescribeInfo{/*
        元素的类型是：String
        元素名是：author
     */Stringauthor();// 作者Stringdate();// 创建时间/*
        元素的类型是：int
        元素名是：currentRevision
        该元素的默认值是：1
     */intcurrentRevision()default1;// 当前版本StringlastModifiedDate()default"";// 最后一次修改的时间StringlastModifiedBy()default"";// 最后一次是被誰修改的String[]reviewers();// 审核者（可以写数组）}

🌼 元素的定义和方法有点像，一种语法而已，记住就好。

使用自定义注解：

@DescribeInfo(
        author ="庆医",
        date ="2022/2/2",
        currentRevision =3,
        lastModifiedDate ="2022/3/3",
        lastModifiedBy ="庆医儿子",
        reviewers ={"Tom","Eric"})publicclassMainTest{}

📖 To make the information in

@DescribeInfo

appear in Javadoc-generated documentation, you must annotate the

@DescribeInfo

definition with the

@Documented annotation

.

📝 为了能够在 javadoc 文档中显示

@DescribeInfo

自定义注解的信息，您必须在定义该注解的时候标注

@Documented

注解。

四、注解介绍

📄 注解（Annotation）也被称为元数据（Metadata），用于解释包、类、方法、属性、构造器、局部变量等数据的信息

📄 和注释一样，注解不影响程序的逻辑。当注解可以被编译或运行（相当于嵌入在代码中的补充信息）

📄 在 JavaSE 中，注解的作用非常简单（例如：标记过时的功能、忽略警告等）

📄 在 JavaEE 中，注解非常非常得重要。在 JavaEE 中，注解占据重要地位（可用于配置应用程序的任何切面，代替 Java EE 旧版中所遗留的繁冗代码和 XML 配置等）

📄 软件工具可以通过处理注解信息生成 Java 代码、生成 XML 文件

五、jdk 中的常见注解

jdk 中的预定义注解（jdk 中自带的注解）详细介绍

📄 使用注解必须要加上 @ 符号，它是注解的标志

📗

@Override

：只能应用于方法，表示该方法是重写父类的方法
📗

@Deprecated

：用于表示某个程序元素（类或方法）已过时
📗

@SuppressWarnings

：抑制编译器的警告
📗

@FunctionalInterface

：标志该接口是函数式接口（若接口使用了 @FunctionalInterface 注解，并且该接口中存在多个抽象方法：会报错）

@FunctionalInterfacepublicinterfaceIRocket{voidtest();}

🌼 函数式接口（Functional Interface）：只有一个抽象方法的接口

Lambda 表达式、函数式接口

六、四种元注解

📄 元注解：用于修饰注解的注解

📄① Retention：指定注解的作用范围（SOURCE、CLASS、RUNTIME）

📄② Target：指定注解可以在哪些地方使用

📄③ Documented：指定被该注解修饰的自定义注解是否会白 javadoc 文档中显示

📄④ Inherited：指定子类是否可以继承父类的注解

(1) Retention

@Documented@Retention(RetentionPolicy.RUNTIME)@Target(ElementType.TYPE)public@interfaceFunctionalInterface{}

📗 SOURCE：编译器使用该注解后，直接丢弃被该注解修饰的注解

📗 CLASS：编译器会把被该注解修饰的注解记录到字节码文件中（在 JVM 中运行字节码的时候，该注解不会被保留）

📗 RUNTIME：编译器会把被该注解修饰的注解记录到字节码文件中（在 JVM 中运行字节码的时候，该注解会被保留，程序可通过反射获取该注解）

(2) Target

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

指定注解可以在哪些地方使用（方法、类型...）

📗 该注解有一个 value 元素（它是数组类型）

📗 value 元素的取值有十种：

🌼 TYPE：可运用在类型上
🌼 FIELD：可运用在属性上
🌼 METHOD：可运用在方法上
🌼 PARAMETER：可运用在参数上
🌼 CONSTRUCTOR：可运用在构造器上
🌼 LOCAL_VARIABLE：可运用在局部变量上
🌼 ANNOTATION_TYPE：可运用在注解类型上
🌼 PACKAGE：可运用在包上
🌼 TYPE_PARAMETER
🌼 TYPE_USE

结束，如有错误，请不吝赐教！