Spring Boot 常用注解全解析:20 个高频注解

还在对着 Spring Boot 项目里的注解一脸懵？@Controller 和 @RestController 到底有啥区别？@Autowired 注入总出问题该咋整？别慌！今天这篇文章，我把 Spring Boot 开发中最常用的 20 个注解一次性讲透，每个注解都配上真实业务场景的代码示例，看完让你对注解的使用豁然开朗，开发效率直接翻倍！

一、Spring Boot 核心注解：项目启动与配置

1. @SpringBootApplication：项目入口的 “门面担当”

这是 Spring Boot 项目的核心注解，放在主启动类上，一眼就能认出这是个 Spring Boot 项目。它其实是 @Configuration、@EnableAutoConfiguration、@ComponentScan 三个注解的组合体。

@SpringBootApplication


public class MyApplication {


   public static void main(String[] args) {


       SpringApplication.run(MyApplication.class, args);


   }


}

作用 ：开启自动配置、组件扫描和配置类功能，少了它 Spring Boot 就没法正常启动。

2. @Configuration：替代 XML 配置文件

标记一个类是配置类，相当于传统的 XML 配置文件，里面可以用 @Bean 注解定义 bean。

@Configuration


public class AppConfig {


   // 定义一个 RestTemplate 实例，全局可用


   @Bean


   public RestTemplate restTemplate() {


       return new RestTemplate();


   }


}

优势 ：用 Java 代码写配置，比 XML 更灵活，还能加逻辑判断。

3. @ComponentScan：指定组件扫描范围

告诉 Spring 要扫描哪些包下的组件（@Controller、@Service 等），@SpringBootApplication 已经包含了它，默认扫描当前类所在的包及其子包。

// 手动指定扫描范围


@SpringBootApplication


@ComponentScan(basePackages = {"com.example.controller", "com.example.service"})


public class MyApplication {


   // ...


}

坑点 ：如果你的组件不在默认扫描范围内，就会注入失败，此时必须手动指定。

二、Web 开发注解：处理 HTTP 请求

4. @Controller：页面交互的控制器

标记一个类是 Spring MVC 的控制器，负责接收用户请求并返回视图（如 HTML 页面）。

@Controller


public class UserController {


   // 处理 GET 请求，返回 user.html 页面


   @GetMapping("/user")


   public String getUser(Model model) {


       model.addAttribute("name", "张三"); // 向页面传递数据


       return"user"; // 返回 templates 目录下的 user.html


   }


}

5. @RestController：API 接口的 “懒人注解”

这是 @Controller + @ResponseBody 的组合，返回的是 JSON 数据，不用再在每个方法上写 @ResponseBody 了。

@RestController


public class ApiController {


   // 直接返回 JSON 数据


   @GetMapping("/api/user")


   public User getUser() {


       User user = new User();


       user.setName("李四");


       user.setAge(25);


       return user; // 自动转为 JSON


   }


}

适用场景 ：前后端分离项目的 API 接口，现在 90% 的 Spring Boot 项目都用它。

6. @RequestMapping：请求映射的 “万能注解”

指定方法处理哪些 HTTP 请求，可用于类和方法上，支持 GET、POST 等所有请求方式。

// 类上指定统一前缀

@RequestMapping("/user")


@RestController

public class UserController {


   // 处理 GET 请求：/user/1

   @RequestMapping(value = "/{id}", method = RequestMethod.GET)


   public User getUserById(@PathVariable Long id) {


       // ...

   }


}

简化注解 ：

7. @PathVariable：获取 URL 路径参数

从 URL 路径中提取参数，比如从 /users/123 中获取 123 这个 id。

@GetMapping("/users/{id}")


public User getUser(@PathVariable Long id) {


   return userService.findById(id);


}


// 多个参数

@GetMapping("/users/{id}/orders/{orderId}")


public Order getOrder(@PathVariable Long id, @PathVariable Long orderId) {


   // ...

}

8. @RequestParam：获取 URL 查询参数

获取 URL 中？后面的参数，比如从 /users?page=1&size=10 中获取 page 和 size。

@GetMapping("/users")


public Page getUsers(

   @RequestParam(defaultValue = "1") Integer page, // 默认值 1

   @RequestParam(defaultValue = "10") Integer size) {


   return userService.findPage(page, size);


}

常用属性 ：

9. @RequestBody：接收 JSON 请求体

接收请求体中的 JSON 数据，并把它转换成对应的 Java 对象，POST、PUT 请求传递复杂对象时常用。

@PostMapping("/users")


public User addUser(@RequestBody User user) {


   // user 已经是转换好的对象，直接保存即可

   return userService.save(user);


}

注意 ：前端必须设置 Content-Type: application/json，否则会报错。

三、依赖注入注解：管理组件关系

10. @Autowired：自动注入依赖

让 Spring 自动找到合适的 bean 并注入进来，不用自己 new 对象了。

@Service

public class UserService {


   // 自动注入 UserDao

   @Autowired

   private UserDao userDao;


   public User getUserById(Long id) {


       return userDao.findById(id);


   }


}

坑点 ：如果有多个同类型的 bean，直接用 @Autowired 会报错，此时要配合 @Qualifier 指定名称。

@Autowired

@Qualifier("userDaoImpl") // 指定注入名称为 userDaoImpl 的 bean

private UserDao userDao;

11. @Service：标记业务逻辑层

告诉 Spring 这是一个服务层组件，负责处理业务逻辑，会被自动扫描并注入。

@Service

public class UserService {


   // 业务逻辑处理

}

同类注解 ：@Repository（数据访问层）、@Component（通用组件），它们都是为了让代码分层更清晰。

12. @Resource：按名称注入依赖

和 @Autowired 类似，但它默认按名称匹配，而 @Autowired 默认按类型匹配。

@Service

public class OrderService {


   // 按名称注入（name 可省略，默认取属性名）

   @Resource(name = "orderDao")


   private OrderDao orderDao;


}

小技巧 ：如果你更在意 bean 的名称，用 @Resource 更方便。

四、数据访问注解：操作数据库

13. @Transactional：声明式事务管理

加在方法或类上，让方法执行在事务中，出现异常时自动回滚，保证数据一致性。

@Service

public class OrderService {


   // 该方法在事务中执行

   @Transactional

   public void createOrder(Order order) {


       orderDao.save(order); // 保存订单

       inventoryService.reduceStock(order.getProductId(), order.getNum()); // 扣减库存

       // 如果上面的代码抛出异常，事务会回滚，订单和库存操作都取消

   }


}

常用属性 ：

14. @Mapper：MyBatis 接口映射

标记一个接口是 MyBatis 的 Mapper 接口，不用写实现类就能直接调用。

@Mapper

public interface UserMapper {


   // 直接写方法，SQL 在 XML 中或用注解写

   User selectById(Long id);


}

替代方案 ：在主启动类上用 @MapperScan 扫描整个包，不用每个接口都加 @Mapper。

@SpringBootApplication

@MapperScan("com.example.mapper") // 扫描所有 Mapper 接口

public class MyApplication {


   // ...

}

五、配置与参数绑定

15. @Value：读取配置文件的值

直接读取 application.properties 或 application.yml 中的配置，注入到变量中。

# application.properties

app.name=我的应用


app.version=1.0.0

@Component

public class AppInfo {


   // 注入配置值

   @Value("${app.name}")


   private String appName;


   @Value("${app.version}")


   private String appVersion;


}

小技巧 ：可以用 {} 拼接字符串，比如 @Value(" {app.name}-${app.version}")。

16. @ConfigurationProperties：批量绑定配置

批量读取配置文件中的属性，绑定到一个类的字段上，比 @Value 更适合读取多个相关配置。

# 数据库配置


db.url=jdbc:mysql://localhost:3306/test

db.username=root


db.password=123456

@Component

@ConfigurationProperties(prefix = "db") // 配置前缀

public class DbConfig {


   private String url;


   private String username;


   private String password;


   // getter 和 setter 必须有，否则无法绑定

}

优势 ：支持嵌套属性、校验（加 @Validated），还能在 IDE 中自动提示配置项。

六、其他高频注解

17. @ResponseBody：返回 JSON 数据

让方法返回的对象自动转为 JSON 数据，一般用在 @Controller 类的方法上。

@Controller

public class ApiController {


   // 返回 JSON 数据

   @GetMapping("/api/user")


   @ResponseBody

   public User getUser() {


       // ...

   }


}

注意 ：@RestController 已经包含了它，所以不用重复加。

18. @PathVariable：获取 URL 路径参数

从 URL 路径中提取参数，比如从 /users/123 中获取 123 这个 id。

@GetMapping("/users/{id}")


public User getUser(@PathVariable Long id) {


   return userService.findById(id);


}

19. @RequestParam：获取查询参数

获取 URL 中？后面的参数，比如从 /users?page=1&size=10 中获取 page 和 size。

@GetMapping("/users")


public Page getUsers(

   @RequestParam(defaultValue = "1") Integer page,


   @RequestParam(defaultValue = "10") Integer size) {


   return userService.findPage(page, size);


}

20. @ExceptionHandler：全局异常处理

统一处理控制器中的异常，不用在每个方法中写 try-catch 了。

@RestControllerAdvice // 全局异常处理类

public class GlobalExceptionHandler {


   // 处理空指针异常

   @ExceptionHandler(NullPointerException.class)


   public Result handleNullPointerException(NullPointerException e) {


       return Result.error("空指针异常：" + e.getMessage());


   }


   // 处理所有异常（兜底）

   @ExceptionHandler(Exception.class)


   public Result handleException(Exception e) {


       return Result.error("系统异常，请联系管理员");


   }


}

效果 ：控制器抛出异常后，会自动被这里的方法捕获并处理，返回统一的错误格式。

为什么这些注解能让你少加班？

Spring Boot 的注解看似繁多，但核心都是为了简化开发。掌握这些高频注解，你能：

这些注解就像是 Spring Boot 的 “快捷键”，熟练运用它们，别人写一天的代码，你半天就能搞定！

觉得有用的话，转发给团队里还在为注解头疼的同事，一起提升开发效率！