Java常用注解(Annotation)详解汇总

先来说说什么是注解：

注解其实就是代码里的特殊标记，它用于替代配置文件，有了注解技术后，开发人员可以通过注解告诉类如何运行。通过元注解来定义（修饰）自定义注解并定义所需要实现的功能。
注解可以标记在包、类、属性、方法，方法参数以及局部变量上，且同一个地方可以同时标记多个注解，这样一来就可以为我们省掉大量的重复复杂的代码。
在Java技术里注解的典型应用是：可以通过反射技术去得到类里面的注解，以决定怎么去运行类。

一，元注解（用来修饰注解的注解）

从JDK 1.5开始, Java增加了对元数据(MetaData)的支持，提供了4个标准的用来对注解类型进行注解的注解类，我们称之为 meta-annotation（元注解）
@Target(ElementType.) 描述注解的使用范围（即：被修饰的注解可以用在什么地方）

取值（ElementType）有：
　　　　1.CONSTRUCTOR:用于描述构造器
　　　　2.FIELD:用于描述域
　　　　3.LOCAL_VARIABLE:用于描述局部变量
　　　　4.METHOD:用于描述方法
　　　　5.PACKAGE:用于描述包
　　　　6.PARAMETER:用于描述参数
　　　　7.TYPE:用于描述类、接口（包括注解类型）或enum声明

@Retention(RetentionPolicy.) 描述注解的生命周期（即：被修饰的注解被保留到何时）

取值（RetentionPoicy）有：
　　　　1.SOURCE:在源文件中有效（即源文件保留）
　　　　2.CLASS:在class文件中有效（即class保留）
　　　　3.RUNTIME:在运行时有效（即运行时保留）

@Documented 会被javadoc工具动态提取成文档。
@Inherited 允许子类继承父类中的注解。

---

二，Spring中的注解

SpringMVC注解

SpringMVC运行流程原理图

这些注解描述的类 Spring会创建原生对象或代理对象并交给 IOC容器 管理，这些对象称之为bean。用时直接 @Autowired 注入即可。

@Mapper 描述数据层 (Mapper)
@Service 描述业务层 (Service)
@Repository 标识持久层 / 数据访问层组件(Dao)
@Component 可以描述各种组件(当组件不好归类时)

@RestController 描述控制层(Controller)并返回JSON数据类型，但不会再执行配置的视图解析器，也不会返回给jsp页面，返回值就是return里的内容。
该注解等同于：@Controller + @ResponseBody
@Controller 描述控制层 接收用户请求 执行 视图解析器 。
返回一个ModelAndView对象，传给指定的jsp（将传过来的ModelAndView对象解析后展示在页面上），封装后，最后返回给客户端一个Html页面。
@ResponseBody 将Java对象转为JSON。如果用ajax接收请求，必须使用该注解。如果没有加此注解，返回的是一个页面，return里面的内容会被认做是需要跳转页面的地址。

IOC容器注解

IOC(Inversion of Control) 是控制反转，也叫依赖注入(DI)。
把复杂系统分解成相互合作的对象，这些对象类通过封装以后，内部实现对外部是透明的，从而降低了解决问题的复杂度，而且可以灵活地被重用和扩展。

简单来说： IOC容器意味着将你设计好的对象(类)交给容器控制(管理)，需要的时候通过注解来注入(获取)，而不是传统的在你的对象内部直接控制(new 对象)。从而降低了程序的耦合性。

@Bean 描述在方法上，把方法的返回值交给容器管理，不需要再手动调用该方法。
@Autowired 按byType自动注入 获取对应的bean对象。如果注入的类型有多个实现类，则需要注入具体实现类的名称。
@Resource 按byName自动注入 获取对应的bean对象
@Value 注入普通类型属性。

如果容器中有多个相同类型的 bean，则框架将抛出 NoUniqueBeanDefinitionException， 以提示有多个满足条件的bean。
bean会进行自动装配。程序无法正确做出判断使用哪一个时，可以使用以下注解👇

@Qualifier("") 在相同类型bean上命名后，可以按不同名称注入 配合@Autowired 使用。
@Primary 当存在多个相同类型的 bean 时，首选被@Primary注解过的bean。

Bean注解

把Bean理解可以理解为类的代理或代言人（实际上是通过反射、代理来实现的）当你使用上面SpringMVC注解时，Spring会把这些被注解的类的实例化对象转化成一个个的bean，也称 注册 成一个个的bean，并保存到IOC容器中。

Bean的使用范围注解：

@Scope(value="") 默认生成的类是单例的。

取值（value） 有：
　　　　1.singleton ：单例，默认，程序启动时立刻创建对象
　　　　2.prototype ：多例，需要注入时（调用方法）才创建对象。每次注入时，都会创建新对象
　　　　3.request ：request域，需要在web环境
　　　　4.session ：session域，需要在web环境。第一次访问时创建，关闭浏览器时回收。
　　　　5.application： context域，需要在web环境
　　　　6.globalsession 集群环境的session域，需要在web环境

Bean的生命周期注解：

@PostConstruct 相当于init-method
@PreDestroy 相当于destroy-method

Spring启动类注解(开箱即用)：

只需要导入简单的jar包文件,就可以实现对应的功能,无需(少量)繁琐的配置。

@SpringBootAppliction 用在启动类上，主要目的是开启自动配置 组合了：

1）@SpringBootConfiguration 继承自@Configuration，标注当前类是配置类，将当前类的一个或多个以@Bean注解标记的方法的实例纳入到Spring容器中，并且实例名就是方法名。

2）@EnableAutoConfiguration 自动化配置, 借助@Import的支持，收集和注册特定场景相关的bean定义。简单理解：借助@Import的帮助，将所有符合自动配置条件的bean定义加载到IOC容器中。
该注解里面有@AutoConfigurationPackage 自动配置的包扫描 @Import调用选择器去加载pom.xml文件中的启动项

3）@ComponentScan 定义包扫描 指定路径 哪些包中的对象注册成bean交给IOC容器管理。

请求Mapping注解

@RequestMapping("/xxx") 注解类上 通过"/xxx"来指定控制器可以处理哪些URL请求。

请求方式：
@GetMapping 通常注解 查询方法
@PostMapping 通常注解 增添保存方法
@DeleteMapping 通常注解 删除方法
@PutMapping 通常注解 更新方法
@PatchMapping 通常注解 更新局部方法

动态赋值注解

@PathVariable 接收的url动态传给被注解的参数（restFull风格）
@RequestBody 将接收的JSON格式的数据转为Java对象参数（适用于Post请求）
@RequestParam(value=“接收的xxx”) 讲接收的xxx传给被注解的参数 （适用于Post,Get请求）

缓存注解

@EnableCaching 启动springboot工程中的内置缓存。
@Cacheable(value=“缓存值取名”) 把返回值进行缓存，缓存通过切面自动切入，可用用于方法或者类上。

参数	描述
value	名称
key	key
condition	可判断key条件

@CacheEvict(value=“需要清空的缓存名”) 方法是一个清缓存的切入点方法，当这个方法被调用后，即会清空缓存。

参数	描述
value	名称
key	key
condition	缓存的条件，可以为空
allEntries	是否清空所有缓存内容
beforeInvocation	是否在方法执行前就清空

---

三，AOP切面注解

AOP(Aspect Oriented Programming) 面向切面编程。
Spring中的AOP代理还是离不开Spring的IOC容器，代理的生成，管理及其依赖关系都是由IOC容器负责，Spring默认使用 JDK动态代理。
AOP详解请参考官网

切入点表达式：
@Pointcut("@annotation(被切入方法的地址)") 设置切入点

1.bean(“包名.类名”) 具体某个类 按类匹配 粗粒度
2.within(“包名.类名”) 可以使用通配符 几个类一起匹配 粗粒度
3.execution(返回值类型 包名.类名.方法名(参数列表)) 细粒度
4.注解方式 @annotation(注解的类型) 细粒度

通知：
@before(“pointCut()”) 在目标方法前执行
@After(“pointCut()”) 在目标方法后执行 ，不管有没有异常
@AfterReturning 在目标方法正常返回值后执行
@AfterThrowing 在目标方法出现异常后执行
上述的4大通知，都不能控制目标方法是否执行，一般只会做程序的监控。
可以通过调用JoinPoint对象获取被切入方法 签名(getSignature())。
@Around(“pointCut()”) 在目标方法执行前后都要执行，可以控制目标方法在哪执行。
可以通过调用ProceedingJoinPoint对象的proceed方法来控制需要切入的方法的行动轨迹。

---

四，常用插件注解

Lombok 插件

@Data 动态添加get/set/toString/equals/hashcode/构造方法 适用于pojo / VO该注解等同于：

@Getter + @Setter + ToString + @EqualsAndHashCode +
@RequiredArgsConstructor

@Value 把所有的变量都设成 final 修饰 和 @Data相似
@AllArgsConstructor 添加构造方法
@NoArgsConstructor 添加无参构造
@sfl4g 自动生成该类的 log 静态常量
@Accessors(chain = true) 引用链式加载方式 方便做插入操作。

Lombok插件 官方文档说明：
https://projectlombok.org/

MybatisPlus 注解

MyBatis-Plus (opens new window)（简称 MP）是一个 MyBatis (opens new window)
的增强工具，在 MyBatis 的基础上只做增强不做改变，为简化开发、提高效率而生。

@TableName(value="", resultMap="") 表名与实体类名不一致时 需要在实体类上加入注解"value=表名"，xml 中 resultMap 的 id 不一致时需要赋值。
@TableId(value= “”, type = IdType.AUTO) 表示主键名/属性。 @IdType的值有：

AUTO 数据库自增
INPUT 自行输入
ID_WORKER 分布式全局唯一ID 长整型类型
UUID 32位UUID字符串
NONE 无状态
ID_WORKER_STR 分布式全局唯一ID 字符串类型

@TableField("…") 注解新增属性，如果字段名与属性一致(已开启驼峰规则)，则可省略，否则加入"exist=false"参数。

参数	描述
value	字段值，如果字段名与属性一致(已开启驼峰规则)则可省略
update	预处理 set 字段自定义注入
condition	预处理 WHERE 实体条件自定义运算规则
exist	是否为数据库表字段
fill	字段填充

@TableLogic 表字段逻辑处理注解（逻辑删除）

Mybatis-Plus官方文档说明：
https://mp.baomidou.com/guide/annotation.html

Shiro 注解

Shiro 提供了相应的注解用于权限控制，如果使用这些注解就需要使用AOP 的功能来进行判断

@RequiresAuthentication 表示当前Subject已经通过login 进行了身份验证，即Subject. isAuthenticated()返回true。
@RequiresGuest 表示当前Subject没有身份验证或通过记住我登录过，即是游客身份。
@RequiresUser 表示当前Subject已经身份验证或者通过记住我登录的。
@RequiresRoles
(value={“admin”, “user”}, logical= Logical.AND)
表示当前Subject需要角色 admin 和(AND) user ，value表示需要判断的角色，logical表示判断条件。
@RequiresPermissions
(value={“user:a”, “user:b”}, logical= Logical.OR)
表示当前Subject需要权限 user:a 或(OR) user:b ，value表示需要判断的权限，logical表示判断条件。

Shiro框架 官方文档说明：
http://shiro.apache.org/#

---

六， Javadoc注解

javadoc 是Sun公司提供的一个技术，它从程序源代码中抽取类、方法、成员等注释形成一个和源代码配套的API帮助文档。也就是说，只要在编写程序时以一套特定的标签作注释，在程序编写完成后，通过Javadoc就可以同时形成程序的开发文档了。
Java 支持三种注释方式。前两种分别是 // 和 /* /，第三种被称作说明注释，它以 /* 开始，以 */结束。
说明注释允许你在程序中嵌入关于程序的信息。你可以使用 javadoc 工具软件来生成信息，并输出到HTML文件中。
说明注释，使你更加方便的记录你的程序信息。

Javadoc官方说明：How to Write Doc Comments for the Javadoc Tool
Javadoc标签：

标签	描述
@author	标识一个类的作者 @author description
{@code}	一般在Javadoc中只要涉及到类名或者方法名，都需要使用@code进行标记 {@code text}
@deprecated	指名一个过期的类或成员 @deprecated description
{@docRoot}	指明当前文档根目录的路径 Directory Path
@exception	标志一个类抛出的异常 @exception exception-name explanation
{@inheritDoc}	从直接父类继承的注释 Inherits a comment from the immediate surperclass.
{@link}	插入一个到另一个主题的链接 {@link name text}
{@linkplain}	插入一个到另一个主题的链接，但是该链接显示纯文本字体 Inserts an in-line link to another topic.
@param	说明一个方法的参数 @param parameter-name explanation
@return	说明返回值类型 @return explanation
@see	指定一个到另一个主题的链接 @see anchor
@serial	说明一个序列化属性 @serial description
@serialData	说明通过writeObject( ) 和 writeExternal( )方法写的数据 @serialData description
@serialField	说明一个ObjectStreamField组件 @serialField name type description
@since	标记当引入一个特定的变化时 @since release
@throws	和 @exception标签一样. The @throws tag has the same meaning as the @exception tag.
{@value}	显示常量的值，该常量必须是static属性。 Displays the value of a constant, which must be a static field.
@version	指定类的版本 @version info

五，其他注解

Async异步/切面注解

@Async 注解描述的方法为一个异步切入点方法（声明该方法执行异步），启动类上需要加上@EnableAsync才能使其生效。
这个方法会在切面通知方法中通过一个新的线程调用执行,由spring线程池提供。
被注解的方法不要有返回值。如果需要有返回值，需要用AsyncResult对象封装。
@EnableAsync 可以使用多线程 描述该类支持异步

配置注解

不同的的业务文件放在不同的配置文件yml中，所以需要动态加载配置文件
@PropertySource(value=“classpath:/…”,ebcidubg=“UTF-8”) 可以将自定义属性文件中的属性变量值注入到当前类的使用@Value注解的成员变量中。
@ConfigurationProperties 可以将属性文件与一个Java类绑定，将属性文件中的变量值注入到该Java类的成员变量中。
@ImportResource 注解用来导入 Spring 的配置文件，如核心配置文件 “beans.xml”，从而让配置文件里面的内容生效

其他注解

@Select("…") 简单的sql语句可以用该注解直接在方法上描述。
@CrossOrigin 此注解描述的Controller，表示允许跨域访问。
@Transactional 生成AOP代理并开启事务，如果程序出现异常可回滚。
@ExceptionHandler(异常类型.class) 自定义异常处理类后，统一处理某一类异常，从而能够减少代码重复率和复杂度。

---