Spring - 注解整理

Documented注解

Documented 注解表明这个注解应该被 javadoc工具记录. 默认情况下,javadoc是不包括注解的. 但如果声明注解时指定了 @Documented,则它会被 javadoc 之类的工具处理, 所以注解类型信息也会被包括在生成的文档中.

更多内容可以参考：Annotation深入研究——@Documented注释使用

Retention注解

• @Retention是用来修饰注解的，注解的注解，也称为元注解
• @Retention修饰注解，用来表示注解的生命周期，生命周期的长短取决于@Retention的属性RetentionPolicy指定的值，例如@Retention(RetentionPolicy.RUNTIME)
  
• 上面三种类型生命周期：SOURCE<CLASS<RUNTIME，使用RUNTIME会包含前面两个生命周期

Target注解

• @Target : 表明注解的作用目标
• @Target(ElementType.TYPE) //接口、类、枚举
• @Target(ElementType.FIELD) //字段、枚举的常量
• @Target(ElementType.METHOD) //方法
• @Target(ElementType.PARAMETER) //方法参数
• @Target(ElementType.CONSTRUCTOR) //构造函数
• @Target(ElementType.LOCAL_VARIABLE)//局部变量
• @Target(ElementType.ANNOTATION_TYPE)//注解
• @Target(ElementType.PACKAGE) ///包

Configuration注解

• @Configuration用于定义配置类，可替换xml配置文件，被注解的类内部包含有一个或多个被@Bean注解的方法，这些方法将会被AnnotationConfigApplicationContext或AnnotationConfigWebApplicationContext类进行扫描，并用于构建bean定义，初始化Spring容器。
• 注意：@Configuration注解的配置类有如下要求：

  • 用@Configuration加载Spring
    1、 @Configuration配置spring并启动spring容器
    2、 @Configuration启动容器+@Bean注册Bean
    3、 @Configuration启动容器+@Component注册Bean，使用 AnnotationConfigApplicationContext 注册 AppContext 类的两种方法，配置Web应用程序(web.xml中配置AnnotationConfigApplicationContext)

  • 组合多个配置类
    1、在@configuration中引入spring的xml配置文件
    2、在@configuration中引入其它注解配置
    3、@configuration嵌套（嵌套的Configuration必须是静态类）

Component注解

• @component （把普通pojo实例化到spring容器中，相当于配置文件中的
  ）
• 泛指各种组件，就是说当我们的类不属于各种归类的时候（不属于@Controller、@Services等的时候），我们就可以使用@Component来标注这个类。

RestControllerAdvice注解

• 主要配合@ExceptionHandler使用，统一处理异常情况。
• @RestControllerAdvice 注解，可以用于定义@ExceptionHandler、@InitBinder、@ModelAttribute，并应用到所有@RequestMapping中。
• @RestControllerAdvice 是组件注解，他使得其实现类能够被classpath扫描自动发现，如果应用是通过MVC命令空间或MVC Java编程方式配置，那么该特性默认是自动开启的。

ExceptionHandler注解

• @ExceptionHandler必须要求该方法必须要和出现问题的控制器在一个类中，才能生效。
• 如果别的类报空指针异常，则不会进该异常处理方法。
• 必须要结合@ControllerAdvice和@ExceptionHandler一起使用。

Autowired注解

• 带有@Autowired注解（属性required默认为true）的构造方法，在Spring初始化对象实例时，会调用此构造函数，进行对象的实例化。
• 如果构造方法上带有了@Autowired注解，那么这个构造方法不是public修饰的，也可以被实例化。private修饰的，也可以被实例化出来。
• 当一个对象只有一个构造方法时，Spring实例化对象会默认选择这个构造方法进行实例化，无需加@Autowired注解。只有当多个构造方法存在时，才用加@Autowired注解，告诉Spring选择哪个构造方法进行实例化。
• 构造方法的@Autowired且required属性为true只允许存在一个。其他的@Autowired直接的required属性必须设置为false。
• 实例化带参数的构造方法时，Spring会先实例化构造方法中参数对象。
• 当一个类中有多个构造方法，且我们要选择某一个构造方法进行Spring实例化时，可以在构造方法上加@Autowired注解。

GroupSequence注解

• 在@GroupSequence内可以指定，分组校验的顺序。比如说@GroupSequence({Insert.class, Update.class, UserForm.class})先执行Insert校验，然后执行Update校验。如果Insert分组，校验失败了，则不会进行Update分组的校验。

Bean注解

• @Bean：Spring的@Bean注解用于告诉方法，产生一个Bean对象，然后这个Bean对象交给Spring管理。产生这个Bean对象的方法Spring只会调用一次，随后这个Spring将会将这个Bean对象放在自己的IOC容器中；
• SpringIOC 容器管理一个或者多个bean，这些bean都需要在@Configuration注解下进行创建，在一个方法上使用@Bean注解就表明这个方法需要交给Spring进行管理；
• @Bean是一个方法级别上的注解，主要用在@Configuration注解的类里，也可以用在@Component注解的类里。添加的bean的id为方法名；
• 使用Bean时，即是把已经在xml文件中配置好的Bean拿来用，完成属性、方法的组装；比如@Autowired , @Resource，可以通过byTYPE（@Autowired）、byNAME（@Resource）的方式获取Bean；
• 注册Bean时，@Component , @Repository , @ Controller , @Service , @Configration这些注解都是把你要实例化的对象转化成一个Bean，放在IoC容器中，等你要用的时候，它会和上面的@Autowired , @Resource配合到一起，把对象、属性、方法完美组装；
• @Configuration与@Bean结合使用：@Configuration可理解为用spring的时候xml里面的标签，@Bean可理解为用spring的时候xml里面的标签；

EnableSwagger2注解

• 使用swagger2构建restful接口测试

• @Api注解可以用来标记当前Controller的功能。

• @ApiOperation注解用来标记一个方法的作用。

• @ApiImplicitParam注解用来描述一个参数，可以配置参数的中文含义，也可以给参数设置默认值，这样在接口测试的时候可以避免手动输入。

• 如果有多个参数，则需要使用多个@ApiImplicitParam注解来描述，多个@ApiImplicitParam注解需要放在一个@ApiImplicitParams注解中。

• 需要注意的是，@ApiImplicitParam注解中虽然可以指定参数是必填的，但是却不能代替@RequestParam(required = true)，前者的必填只是在Swagger2框架内必填，抛弃了Swagger2，这个限制就没用了，所以假如开发者需要指定一个参数必填，@RequestParam(required = true)注解还是不能省略。如果参数是一个对象（例如上文的更新接口），对于参数的描述也可以放在实体类中。

• @RequestHeader
  · query --> 请求参数的获取：@RequestParam
  · path（用于restful接口）–> 请求参数的获取：@PathVariable
  · body（不常用）
  · form（不常用）
  dataType：参数类型，默认String，其它值dataType=“Integer”
  defaultValue：参数的默认值

• @ApiResponses：用在请求的方法上，表示一组响应
  @ApiResponse：用在@ApiResponses中，一般用于表达一个错误的响应信息
  code：数字，例如400
  message：信息，例如"请求参数没填好"
  response：抛出异常的类

• @ApiModel：用于响应类上，表示一个返回响应数据的信息

• @ApiModelProperty：用在属性上，描述响应类的属性

Inherited注解

• 允许子类继承父类的注解。 即在两个类之间存在继承关系，且父类标记的注解使用了 @Inherited 注解（注： 总感觉这里表述不清，参考 @ParentAnnotation 注解的定义即可），这时继承的子类可以使用父类的注解。

Order注解

• @Order的作用是定义Spring IOC容器中Bean的执行顺序的优先级，而不是定义Bean的加载顺序，Bean的加载顺序不受@Order或Ordered接口的影响；

EnableConfigurationProperties注解

• @EnableConfigurationProperties注解的作用是：使 使用 @ConfigurationProperties 注解的类生效。

RestController注解

• 在Spring中@RestController的作用等同于@Controller + @ResponseBody。所以想要理解@RestController注解就要先了解@Controller和@ResponseBody注解。
• @Controller注解
  1、 在一个类上添加@Controller注解，表明了这个类是一个控制器类。但想要让这个类成为一个处理请求的处理器光有@Controller注解是不够的，他还需要进一步修炼才能成为一个处理器。
  2、@RequestMapping注解是用来映射请求的，即指明处理器可以处理哪些URL请求，该注解既可以用在类上，也可以用在方法上。
• @ResponseBody注解
  1、@ResponseBody表示方法的返回值直接以指定的格式写入Http response body中，而不是解析为跳转路径。
  2、格式的转换是通过HttpMessageConverter中的方法实现的，因为它是一个接口，因此由其实现类完成转换。

PostMapping注解

• 映射一个POST请求
• @GetMapping，处理get请求
• @PostMapping，处理post请求
• @PutMapping，处理put请求
• @DeleteMapping，处理delete请求

Mapper注解

• 在接口类上添加了@Mapper，在编译之后会生成相应的接口实现类
• 接口方法注解主要是四个：@Insert、@Delete、@Update、@Select

MapperScan注解

• 指定要变成实现类的接口所在的包，然后包下面的所有接口在编译之后都会生成相应的实现类

Data注解

• @Data注解是lombok.jar包下的注解，该注解通常用在实体bean上，不需要写出set和get方法，但是具备实体bean所具备的方法，简化编程提高变成速度。
• @Data相当于@Getter @Setter @RequiredArgsConstructor @ToString @EqualsAndHashCode这5个注解的合集。

TableName注解

• @TableName 注解用来将指定的数据库表和 JavaBean 进行映射。
• value属性，字符串类型，可以不填，用来指定数据表名称。
• schema属性，用来指定模式名称。如果你使用的是 mysql 数据库，则指定数据库名称。如果你使用的是 oracle，则为 schema，例如：schema=“scott”，其中：scott 就是 oracle 中的 schema。

TableId注解

• 指定数据库主键

NotNull注解

• 不能为null，但可以为empty

NotEmpty注解

• 不能为null，而且长度必须大于0

NotBlank注解

• 只能作用在String上，不能为null，而且调用trim()后，长度必须大于0

Range注解

• 表示范围。

Service注解

• @Service(“serviceName”)注解相当于applicationContext.xml配置文件中配置的，表示给当前类命名一个别名，方便注入到其他需要用到的类中。@Service注解也可以不指定serviceName,如果不指定相当于，com.study.service.ServiceName就是这个类的全限定名,不加的话，默认别名就是当前类名，但是首字母小写。

RequiresPermissions注解

• 要求subject中必须同时含有file:read和write:aFile.txt的权限才能执行方法someMethod()。否则抛出异常AuthorizationException。

RequiresRoles注解

• 如果subject中有aRoleName角色才可以访问方法someMethod。如果没有这个权限则会抛出异常AuthorizationException。

RequiresGuest注解

• 验证是否是一个guest的请求，与@RequiresUser完全相反。

RequiresUser注解

• 验证用户是否被记忆，user有两种含义：
• 一种是成功登录的（subject.isAuthenticated() 结果为true）；
• 另外一种是被记忆的（subject.isRemembered()结果为true）。

RequiresAuthentication注解

• 验证用户是否登录，等同于方法subject.isAuthenticated() 结果为true时。