什么是注解

# 什么是注解

本节我们将介绍 Java 程序的一种特殊“注释”——注解（Annotation）。

# 注解的概念

注解的概念不太好理解，我们来说说和和注解的概念很像的东西，注释。注释是用文字描述程序的作用的，是给程序员看的

注解的定义：注解（Annotation），也叫元数据。一种代码级别的说明，是给计算机说明程序的作用的。是自 JDK1.5 及以后版本引入的一个特性，与类、接口、枚举是在同一个层次。它可以声明在包、类、字段、方法、局部变量、方法参数等的前面，用来对这些元素进行说明，使用方式为 @注解名称。

作用分类：

① 文档生成：通过代码里标识的注解生成文档【即 API 文档】

② 代码分析：通过代码里标识的注解对代码进行分析【使用反射】

③ 编译检查：通过代码里标识的注解让编译器能够实现基本的编译检查【例如 @Override】。如果父类没有该方法，重写会失败。

我们先来看看注解的入门案例。

# 用于生成文档

/**
 * @author peterjxl
 * @version 1.0
 * @since 1.0
 */
public class AnnoDemo1 {
  /**
   * 计算两数的和
   * @param a 整数
   * @param b 整数
   * @return 两数的和
   */
  public int add(int a, int b){
    return a+b;
  }
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

注解一般以 @ 开头，例如这里我们用 @author 这个注解告诉 Java 作者是谁；用 @version 这个注解告诉 Java 版本是多少，这两个注解是标注在类上的，也就是说告诉 Java，这个类的作者是 peterjxl，这个类的版本是 1.0.

@param 注解和 @return 注解则是标注在方法上，告诉 Java 这个方法的参数是什么，返回值是什么。

接下来我们可以用命令 javadoc 类名.java (文件名) 来生成 JavaDoc 文档：

javadoc AnnoDemo1.java -encoding utf8 
正在加载源文件AnnoDemo1.java...
正在构造 Javadoc 信息...
标准 Doclet 版本 1.8.0_281
正在构建所有程序包和类的树...
正在生成.\AnnoDemo1.html...
正在生成.\package-frame.html...
正在生成.\package-summary.html...
正在生成.\package-tree.html...
正在生成.\constant-values.html...
正在构建所有程序包和类的索引...
正在生成.\overview-tree.html...
正在生成.\index-all.html...
正在生成.\deprecated-list.html...
正在构建所有类的索引...
正在生成.\allclasses-frame.html...
正在生成.\allclasses-noframe.html...
正在生成.\index.html...
正在生成.\help-doc.html...

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19

打开 index.html，效果如下：

是不是和官方的 API 文档 (opens new window)很像？官方就是通过这个来生成文档的

注意编码问题。如果遇到乱码，则需指定编码，注意我在命令行参数了加了 -encoding utf8

更多请参考官网文档：How to Write Doc Comments for the Javadoc Tool (opens new window)

也可以参考：Javadoc 使用详解_风流少年的博客-CSDN 博客 (opens new window)

# 预定义的一些注解

除了用于生成 API 文档的注解，Java 还提供了如下注解：

@Override：检测被该注解标注的方法是否是继承自父类（接口）的，如果不是会报错
@Deprecated：该注解标注的内容，表示已过时。例如一个方法被发现有缺陷，但为了兼容以前的代码，不能将其删除。例如 Date 类里有很多过时的方法，会有删除线表示。
@SuppressWarnings：忽略警告。例如有个方法从未被使用，IDE 会报警告。一般用在类上，可以压制已过时的注解。一般传递参数 all

/**
 * JDK中预定义的一些注解
 * @Override: 检测被该注解标注的方法是否是继承自父类(接口)的
 * @Deprecated: 该注解标注的内容，表示已过时
 * @SuppressWarnings: 忽略警告
 */

@SuppressWarnings("all")
public class AnnoDemo2 {
  
  @Override
  public String toString(){
    return super.toString();
  }

  @Deprecated
  public void show1(){

  }
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20

# 注解的作用

注解在 Java 中是非常重要的内容，我们后面使用框架，大部分都是基于注解来使用的。使用注解可以大大简化代码。

上次更新: 2024/10/1 18:45:09

← 反射小结注解的本质→