Java常见注解及其使用汇总

@SpringBootApplication 注解是SpringBoot最核心的注解，用于SpringBoot的主类，标识这是一个 SpringBoot 应用，用来开启 Spring Boot 的各项能力。是 @SpringBootConfiguration，@EnableAutoConfiguration，@ComponentScan三个注解的组合。由于这些注解一般一起使用，所以干脆整合成了一个统一的注解@SpringBootApplication。

1.1 @SpringBootConfiguration 注解

继承@Configuration注解，主要用于加载配置文件，二者功能致，标注当前类为配置类，将当前类内声明的一个或多个以@Bean注解标记的方法的实例纳入到spring容器中，且实例名为方法名。

1.2 @EnableAutoConfiguration 注解

开启自动配置功能，帮助SpringBoot应用将所有符合条件的@Configuration配置都加载到当前SpringBoot创建并使用的IoC容器。智能的自动配置功效借助于Spring框架原有的一个工具类：SpringFactoriesLoader的支持。

1.3 @ComponentScan注解

主要用于组件扫描和自动装配，自动扫描并加载符合条件的组件或bean定义，最终将这些bean定义加载到容器中。可以通过basePackages等属性指定@ComponentScan自动扫描的范围，若不指定，则Spring框架实现默认从声明@ComponentScan所在类的package进行扫描，SpringBoot的启动类最好放在root package下。

2. 配置文件相关注解

2.1 @Configuration

用于定义配置类，指出该类是 Bean 配置的信息源，相当于传统的xml配置文件，一般加在主类上。如果有些第三方库需要用到xml文件，建议仍然通过@Configuration类作为项目的配置主类,可以使用@ImportResource注解加载xml配置文件。

2.2 @ComponentScan

组件扫描。让spring Boot扫描到Configuration类并把它加入到程序上下文。@ComponentScan注解默认就会装配标识了@Controller，@Service，@Repository，@Component注解的类到spring容器中。

3. controller层相关注解

3.1 RestController 复合注解

@RestController注解= @ResponseBody+@Controller,效果是将方法返回的对象直接在浏览器上展示成json格式。用于标记控制器类，表示该类是一个RESTful风格的控制器，用于API的请求和响应

3.2 @ResponseBody 注解

@ResponseBody这个注解通常使用在控制层（controller）的方法上，其作用是将方法的返回值以特定的格式写入到response的body区域，进而将数据返回给客户端。当方法上面没有写ResponseBody,底层会将方法的返回值封装为ModelAndView对象。
是字符串则直接将字符串写到客户端。
是一个对象，此时会将对象转化为json串然后写到客户端。这里需要注意的是，如果返回对象,按utf-8编码。如果返回String，默认按iso8859-1编码，页面可能出现乱码。因此在注解中我们可以手动修改编码格式，比如@RequestMapping(value=“/cat/query”,produces=“text/html;charset=utf-8”)，前面是请求的路径，后面是编码格式。
转化为json格式的字符串是通过HttpMessageConverter中的方法实现的，因为它是一个接口，因此由其实现类完成转换。如果是bean对象，会调用对象的getXXX()方法获取属性值并且以键值对的形式进行封装，进而转化为json串。如果是map集合，采用get(key)方式获取value值，然后进行封装。
一般在异步获取数据时使用，在使用@RequestMapping 后，返回值通常解析为跳转路径，加上@responsebody 后返回结果不会被解析为跳转路径，而是直接写入 HTTP response body 中。比如异步获取json 数据，加上 @responsebody 后，会直接返回 json 数据。

3.3 @Controller 注解

用于标注控制层。这里控制层里面的每个方法，都可以去调用@Service标识的类（业务逻辑层），
@Service标识的类中的方法可以继续调用@Resposity标识的接口实现类（Dao层/持久层）。用的较少，都是直接使用@RestController

3.4 @RequestBody

通过HttpMessageConverter读取Request Body并反序列化为Object（泛指）对象
@RequestBody主要用来接收前端传递给后端的json字符串中的数据的(请求体中的数据的)；而最常用的使用请求体传参是POST请求，所以使用@RequestBody接收数据时，一般都用POST方式进行提交。在后端的同一个接收方法里，@RequestBody与@RequestParam可以同时使用，@RequestBody最多只能有一个，而@RequestParam可以有多个。
需要注意的是，使用@RequestBody注解时，请求的Content-Type必须为application/json或application/xml，以确保请求体的数据能够正确地被解析和绑定到对应的Java对象上。

3.5 @RequestParam

@RequestParam注解用于从请求的URL或表单中获取参数的值。它通常用于处理GET请求中的请求参数，并将参数的值绑定到方法的参数上。简单来说，当我们需要获取URL中的参数或表单中的参数时，就可以使用@RequestParam注解。
总结：
@RequestBody主要用于处理请求体中的数据，适用于POST请求；而@RequestParam主要用于处理URL或表单中的参数，适用于GET请求。简单来说，@RequestBody注解用于获取请求体中的数据，@RequestParam注解用于获取URL或表单中的参数。

3.6 PathVariable 注解

用于从URL路径中提取参数，将URL的一部分绑定到处理方法的参数上。
RequestParam的参数是以参数拼接形式拼接在地址后面，
例如： http://127.0.0.1:8080/test?id=1
PathVariable则是从路径中的一部分提取
例如：http://127.0.0.1:8080/test/1
通过@RequestMapping("test/{id}")解析路径中test后面的为参数

3.7 RequestMapping

用于映射请求路径和HTTP方法到相应的处理方法，指定URL路径和请求方法，支持类级别和方法级别。
将 HTTP 请求映射到 MVC 和 REST 控制器的处理方法上,提供路由信息，负责URL到Controller中的具体函数的映射。
@GetMapping是组合注解，是@RequestMapping(method = RequestMethod.GET)的缩写。
@PostMapping是组合注解，是@RequestMapping(method = RequestMethod.POST)的缩写。
其他delete、put方法等类似。

3.8 @RequestHeader

把Request请求header部分的值绑定到方法的参数上，用的较少

3.9 @CookieValue

把Request header中关于cookie的值绑定到方法的参数上，用的较少

3.10 @Value

注入 application.properties 或 application.yml 配置的属性的值；

4.注入bean相关

4.1 @Bean

用于标记方法，该方法返回的对象将被注册为一个bean，并由Spring容器进行管理

4.2 @Component

通用的Spring组件注解，表示这个类是一个可被Spring容器托管的组件。
在类路径扫描期间找到装饰有@Component的 Java 类，并在上下文中注册为 Bean。也泛指各种组件，就是说当我们的类不属于各种归类的时候（不属于@Controller、@Services等的时候），使用@Component来标注这个类。

4.3 @Controller

同上，用于标注控制层

4.4 @Service

用于标记业务层的类，表示该类是一个服务类。
@Component注解的一个特例，作用在类上，使用注解配置和类路径扫描时，被@Service注解标注的类会被Spring扫描并注册为Bean，用于标注服务层组件,表示定义一个bean
注解作用域默认单例
使用时没有传参数，Bean名称默认为当前类的类名，首字母小写
@Service(“serviceBeanId”)或@Service(value=”serviceBeanId”)使用时传参数，使用value作为Bean名字

4.5 @Repository

标识为DAO层，通常要配合@MapperScannerConfigurer使用，配置扫描地址

4.6 @Mapper

@Mapper注解是由Mybatis框架中定义的一个描述数据层接口的注解，即dao层开发。注解往往起到的都是一个描述性作用，用于告诉sprigng框架此接口的实现类由Mybatis负责创建，并将其实现类对象存储到spring容器中。
作用就是将一个接口或类标识为MyBatis的Mapper，并实现了数据库操作的功能，简化了编写和配置数据访问层的代码。

4.7 @Autowired

自动导入
@Autowired注解作用在构造函数、方法、方法参数、类字段以及注解上
@Autowired注解可以实现Bean的自动注入

4.8 @Entity

实体类注解
@Table(name =“数据库表名”)，这个注解也注释在实体类上，对应数据库中相应的表。
@Id、@Column注解用于标注实体类中的字段，pk字段标注为@Id，其余@Column。

4.9 @Qualifier

当有多个同一类型的Bean时，可以用@Qualifier(“name”)来指定。与@Autowired配合使用

4.10 @Scope作用域注解

@Scope在和@Component注解一起修饰在类上，作为类级别注解时，@Scope表示该类实例的范围
在和@Bean一起修饰在方法上，作为方法级别注解时，@Scope表示该方法返回的实例的范围。
对于@Scope注解，我们常用的属性一般就是：value和proxyMode，value就是指明作用域范围，proxyMode指明哪种作用域代理。
value
singleton 表示该bean是单例的。(默认)
prototype 表示该bean是多例的，即每次使用该bean时都会新建一个对象。
request 在一次http请求中，一个bean对应一个实例。
session 在一个httpSession中，一个bean对应一个实例。
proxyMode
DEFAULT 不使用代理。(默认)
NO 不使用代理，等价于DEFAULT。
INTERFACES 使用基于接口的代理(jdk dynamic proxy)。
TARGET_CLASS 使用基于类的代理(cglib)。

5.事务

5.1事务注解 @Transactional

在Spring中，事务有两种实现方式，分别是编程式事务管理和声明式事务管理两种方式
编程式事务管理：编程式事务管理使用TransactionTemplate或者直接使用底层的PlatformTransactionManager。对于编程式事务管理，spring推荐使用TransactionTemplate。
声明式事务管理：建立在AOP之上的。其本质是对方法前后进行拦截，然后在目标方法开始之前创建或者加入一个事务，在执行完目标方法之后根据执行情况提交或者回滚事务，通过@Transactional就可以进行事务操作，更快捷而且简单。推荐使用

二、校验相关注解合集

1. @NotNull

适用对象：任何类型。
注解作用：校验对象不能为null

2. @NotEmpty

适用对象： String、集合、数组、Map、链表List。
注解作用：不能为null，不能是空字符，集合、数组、map等size()不能为0；字符串trim()后可以等于“”

3. @NotBlank

适用对象：字符串。
注解作用：检查字符串是否不为空，并且长度大于0。

4. @Min

适用对象：数字类型、数字字符串。
注解作用：限定数字的最小值(整型)。

5. @Max

适用对象：数字类型、数字字符串。
注解作用：限定数字的最大值(整型)。

6. @DecimalMin

适用对象：数字类型、数字字符串。
注解作用：限定数字的最小值(可以是小数)。

7. @DecimalMax

适用对象：数字类型、数字字符串。
注解作用：限定数字的最大值(可以是小数)。

8. @Range

适用对象：数字类型、数字字符串。
注解作用：限定对象的数字值要在一个合理的区域范围内

9. @Length

适用对象：字符串。
注解作用：限定字符串的长度最大值、最小值

10. @Size

适用对象：集合、数组、字符串、Map等
注解作用：校验对象的长度或尺寸大小在设置的最小、最大值区间内
需要注意的是，对于集合和字符串类型，@Size注解校验的是元素的个数或字符串的长度；对于数组和Map类型，@Size注解校验的是数组的长度或Map的大小，而非元素个数。

11. @Pattern

适用对象：字符串
注解作用：正则匹配该字符串

12. @Email

适用对象：字符串
注解作用：字符串必须满足邮箱的正则格式

13. @AssertTrue

适用对象：Boolean，
注解作用：布尔属性必须是true

14. @AssertFalse

适用对象：Boolean，
注解作用：布尔属性必须是false

15. @Digits(integer,fraction)

适用对象：小数
注解作用：整数部分的位数不能超过integer，小数部分的位数不能超过fraction

16. @Future

适用对象：日期Date
注解作用：限制必须是一个将来的日期

17. @Past

适用对象：日期Date
注解作用：限制必须是一个过去的日期

1. @NotNull
适用对象：任何类型。
注解作用：校验对象不能为null
2. @NotEmpty
适用对象： String、集合、数组、Map、链表List。
注解作用：不能为null，不能是空字符，集合、数组、map等size()不能为0；字符串trim()后可以等于“”
3. @NotBlank
适用对象：字符串。
注解作用：检查字符串是否不为空，并且长度大于0。
4. @Min
适用对象：数字类型、数字字符串。
注解作用：限定数字的最小值(整型)。
5. @Max
适用对象：数字类型、数字字符串。
注解作用：限定数字的最大值(整型)。
6. @DecimalMin 
适用对象：数字类型、数字字符串。
注解作用：限定数字的最小值(可以是小数)。
7. @DecimalMax 
适用对象：数字类型、数字字符串。
注解作用：限定数字的最大值(可以是小数)。
8. @Range
适用对象：数字类型、数字字符串。
注解作用：限定对象的数字值要在一个合理的区域范围内
9. @Length
适用对象：字符串。
注解作用：限定字符串的长度最大值、最小值
10. @Size
适用对象： 集合、数组、字符串、Map等
注解作用： 校验对象的长度或尺寸大小在设置的最小、最大值区间内
需要注意的是，对于集合和字符串类型，@Size注解校验的是元素的个数或字符串的长度；对于数组和Map类型，@Size注解校验的是数组的长度或Map的大小，而非元素个数。
11. @Pattern
适用对象：字符串
注解作用：正则匹配该字符串
12. @Email
适用对象：字符串
注解作用：字符串必须满足邮箱的正则格式
13. @AssertTrue  
适用对象：Boolean，
注解作用：布尔属性必须是true
14. @AssertFalse  
适用对象：Boolean，
注解作用：布尔属性必须是false
15. @Digits(integer,fraction) 
适用对象： 小数
注解作用： 整数部分的位数不能超过integer，小数部分的位数不能超过fraction
16. @Future
适用对象： 日期Date
注解作用：限制必须是一个将来的日期
16. @Past 
适用对象： 日期Date
注解作用：限制必须是一个过去的日期

三、swagger相关注解

1. @Api

Api 用在类上，说明该类的作用。可以标记一个Controller类做为swagger 文档资源,用于对整个API文档进行说明，包括API的描述、作者、版本等信息。

@Api(tags = "用户管理", description = "用户管理操作相关Api接口")
@RestController
@RequestMapping("/user")
public class UserController {
    // ...
}

2. @ApiOperation

@ApiOperation用在请求方法上，说明该方法的作用。用于对某个具体的API接口进行说明，包括接口的描述、请求方法、请求路径等信息

@GetMapping("/{id}")
@ApiOperation(value = "获取用户信息", notes = "根据用户ID获取用户详细信息", httpMethod = "POST")
public User getUserById(@PathVariable Long id){
    // ...
}

3. @ApiParam

用于对API接口的参数进行说明，包括参数的名称、类型、描述等信息。

@PostMapping("/create")
@ApiOperation(value = "创建用户", notes = "根据用户信息创建新用户")
public User createUser(
    @ApiParam(name = "user", value = "用户对象", required = true) @RequestBody User user){
    // ...
}

4. @ApiModel

用于对数据模型进行说明，包括模型的名称、描述等信息。一般用在实体上。

@ApiModel(value = "用户对象", description = "用户对象详细信息")
public class User {
    // ...
}

5. @ApiModelProperty

用于对数据模型的属性进行说明，包括属性的名称、类型、描述等信息。
一般用于解释实体内某个属性的含义

@ApiModel(value = "用户对象", description = "用户对象详细信息")
public class User {
    @ApiModelProperty(value = "用户ID", example = "1")
    private Long id;
    
    @ApiModelProperty(value = "用户名", example = "John")
    private String username;
    // ...
}

6. @ApiResponse

用于对API接口的响应进行说明，包括响应的状态码、描述等信息。

@GetMapping("/{id}")
@ApiOperation(value = "获取用户信息", notes = "根据用户ID获取用户详细信息")
@ApiResponse(code = 200, message = "请求成功", response = User.class)
public User getUserById(@PathVariable Long id){
    // ...
}

7. @ApiResponses

用于对API接口的多个响应进行说明，可以嵌套多个@ApiResponse注解。

@GetMapping("/{id}")
@ApiOperation(value = "获取用户信息", notes = "根据用户ID获取用户详细信息")
@ApiResponses({
    @ApiResponse(code = 200, message = "请求成功", response = User.class),
    @ApiResponse(code = 401, message = "未授权"),
    @ApiResponse(code = 403, message = "禁止访问"),
    @ApiResponse(code = 404, message = "未找到资源")
})
public User getUserById(@PathVariable Long id){
    // ...
}

8. @ApiIgnore

用于指定不在Swagger文档中显示的API接口。可以忽略部分API接口，与@Api同层级

@GetMapping("/{id}")
@ApiIgnore
public void ignoreApi(){
    // ...
}

9. @ApiImplicitParam

用于对API接口的参数进行说明，包括参数的名称、类型、描述等信息，与@ApiParam类似，但用于指定非@RequestParam注解的参数

@PostMapping("/upload")
@ApiOperation(value = "上传文件", notes = "上传文件接口")
@ApiImplicitParams({
    @ApiImplicitParam(name = "file", value = "文件", required = true, dataType = "MultipartFile")
})
public void uploadFile(@RequestParam("file") MultipartFile file){
    // ...
}

10. @ApiImplicitParams

用于对API接口的多个参数进行说明，可以嵌套多个@ApiImplicitParam注解

@PostMapping("/create")
@ApiOperation(value = "创建用户", notes = "根据用户信息创建新用户")
@ApiImplicitParams({
    @ApiImplicitParam(name = "username", value = "用户名", required = true, dataType = "String"),
    @ApiImplicitParam(name = "password", value = "密码", required = true, dataType = "String"),
    // ...
})
public void createUser(@RequestParam("username") String username, @RequestParam("password") String password){
    // ...
}

11、@ApiOperationSupport

用于对API接口的特殊操作进行说明，比如文件上传、请求体为多个实体等

@PostMapping("/upload")
@ApiOperation(value = "上传文件", notes = "上传文件接口")
@ApiOperationSupport(
    consumes = MediaType.MULTIPART_FORM_DATA_VALUE,
    parameters = {
        @DynamicParameters(name = "file", value = "文件", dataTypeClass = MultipartFile.class)
    }
)
public void uploadFile(@RequestPart("file") MultipartFile file){
    // ...
}

四、mybatis相关

1. @Mapper

标识当前为mapper层，不可缺少，否则springboot则找不到该mapper文件；在接口上使用该注解，表示该接口是一个MyBatis的Mapper接口，可以方便地进行SQL操作。

@Mapper
public interface UserMapper {
    //...
}

2. @Param

标识参数，用于给SQL语句中的参数命名，方便传入多个参数，不对参数进行注释，可能会导致执行xml中sql语句时找不到对应参数

@Select("SELECT * FROM users WHERE name = #{name} AND age = #{age}")
User getUserByNameAndAge(@Param("name") String name, @Param("age") int age);

以下注解使用较少，不推荐直接在mapper层通过注解形式书写sql

3. @Select

用于声明一个查询操作的SQL语句。

@Select("SELECT * FROM users WHERE id = #{id}")
User getUserById(int id);

4. @Update

用于声明一个更新操作的SQL语句。

@Update("UPDATE users SET name = #{name}, age = #{age} WHERE id = #{id}")
int updateUser(User user);

5. @Delete

用于声明一个删除操作的SQL语句。

@Delete("DELETE FROM users WHERE id = #{id}")
int deleteUserById(int id);

6. @ResultMap

用于将查询结果映射到对象上。

@Select("SELECT * FROM users")
@ResultMap("userResultMap")
List<User> getUsers();

@ResultMap("userResultMap")
User getUserById(int id);

<resultMap id="userResultMap" type="User">
    <id property="id" column="id"/>
    <result property="name" column="name"/>
    <result property="age" column="age"/>
</resultMap>

7.小结

尽管MyBatis提供了注解形式书写SQL语句的功能，但是在实际使用中，更多的人还是倾向于使用XML形式的配置。以下是一些原因：

分离SQL和Java代码：使用XML配置可以将SQL语句和Java代码分离，使得维护更加清晰和可读。而注解形式需要将SQL直接写在Java代码中，使得代码变得冗长和难以维护。
动态SQL支持：XML配置可以使用MyBatis提供的动态SQL功能，通过使用if、choose、when等标签可以实现灵活的条件判断和动态拼接SQL语句。而注解形式的SQL语句难以实现复杂的动态SQL。
可重用性：XML配置中的SQL语句可以被多个Mapper接口和方法共享，提高了SQL语句的可重用性。而注解形式的SQL语句必须在每个Mapper接口中单独定义，导致SQL重复的问题。
防止SQL注入：使用XML配置的方式可以使用MyBatis的参数处理器进行参数的转义和防止SQL注入。而注解形式的SQL语句则需要手动进行参数处理，容易忽略防止SQL注入的措施。

尽管使用XML形式配置SQL语句需要更多的编写和配置工作，但它提供了更灵活、可维护和可重用的方式来定义和管理SQL。所以，大部分情况下，MyBatis还是更推荐使用XML形式的配置来编写SQL语句。
但是对于一些简单的SQL操作，注解形式也可以是一个方便的选择。

五、 lombok相关

使用Lombok可以大大减少编写样板代码的工作量，使得代码更加简洁和可读性。
需要注意的是，使用Lombok的项目需要在编译时依赖Lombok插件，以确保注解生效。

1. @Getter / @Setter

自动生成属性的getter/setter方法。

2. @ToString

自动生成toString方法。

3. @EqualsAndHashCode

自动生成equals和hashCode方法。

4. @NoArgsConstructor / @AllArgsConstructor

自动生成无参构造方法/全参构造方法。

5. @Data

包含了@Getter、@Setter、@ToString、@EqualsAndHashCode和@NoArgsConstructor注解的组合

6. @Builder

生成一个建造者模式的构造器

六、EasyExcel注解

1. @ExcelProperty

标记需要导出的实体类中的某个字段，设定表头的列名，导出顺序等等

public static class User {
    @ExcelProperty("用户姓名")
    private String username;

    @ExcelProperty("用户性别")
    private String gender;

    @ExcelProperty("用户年龄")
    private int age;

    @ExcelProperty("用户电话号码")
    private String phoneNumber;

    // 省略构造方法、Getter和Setter
}

2. @ExcelIgnore

用于标记忽略某个字段，不进行Excel读写操作。

public static class User {
    @ExcelProperty("用户姓名")
    private String username;

    @ExcelProperty("用户性别")
    private String gender;

    @ExcelProperty("用户年龄")
    private int age;

    @ExcelIgnore
    private String phoneNumber;

    // 省略构造方法、Getter和Setter
}

3. @ExcelIgnoreUnannotated

用于标记在读取Excel时忽略未注解的字段。默认没有标注@ExcelIgnore的字段也会被处理，加上了则不会。

@ExcelIgnoreUnannotated
public static class User {
    @ExcelProperty("用户姓名")
    private String username;

    @ExcelProperty("用户性别")
    private String gender;

    @ExcelProperty("用户年龄")
    private int age;
    
    //该字段不会再被读写
    private String phoneNumber;

    // 省略构造方法、Getter和Setter
}

4. @ExcelPropertyIndex

指定属性在Excel中的列序号，用于解析导入Excel数据。
也可直接使用@ExcelProperty(index = 1)

public class User {
    @ExcelPropertyIndex(index = 0) // 将name属性与Excel文件的第一列进行映射
    private String name;
    
    @ExcelPropertyIndex(index = 1) // 将age属性与Excel文件的第二列进行映射
    private int age;
    
    // 省略getter和setter方法
}

5. @ExcelHeadRowNumber

指定表头行号，用于解析导入Excel数据。

6. @ColumnWidth(25)

设置列宽

7. @ContentRowHeight(10)

设置内容行高度

8. @HeadRowHeight(20)

设置表头高度

更多详细注解参考EasyExcel官网示例。

老衲有点帅

关注

8
点赞
踩
28

收藏

觉得还不错? 一键收藏
0
评论
Java常见注解及其使用汇总

SpringBootApplication 注解是SpringBoot最核心的注解，用于SpringBoot的主类，标识这是一个 SpringBoot 应用，用来开启 Spring Boot 的各项能力。是 @SpringBootConfiguration，@EnableAutoConfiguration，@ComponentScan三个注解的组合。由于这些注解一般一起使用，所以干脆整合成了一个统一的注解@SpringBootApplication。
复制链接

扫一扫

专栏目录