什么是注解
# 什么是注解
本节我们将介绍 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;
}
}
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...
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)
# 预定义的一些注解
除了用于生成 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(){
}
}
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
# 注解的作用
注解在 Java 中是非常重要的内容，我们后面使用框架，大部分都是基于注解来使用的。使用注解可以大大简化代码。
