Spring Boot 常用注解全解析：20 个高频注解 + 使用场景实例

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

@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 就没法正常启动。

@Configuration：替代 XML 配置文件

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


@Configuration


public class AppConfig {


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


   @Bean


   public RestTemplate restTemplate() {


       return new RestTemplate();


   }


}

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

@ComponentScan：指定组件扫描范围

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


// 手动指定扫描范围

@SpringBootApplication

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

public class MyApplication {

   // ...

}

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

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

@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 项目都用它。

@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) {

 // ...

}

}

简化注解：

@GetMapping：处理 GET 请求（常用）

@PostMapping：处理 POST 请求（常用）

@PutMapping：处理 PUT 请求

@DeleteMapping：处理 DELETE 请求

@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<User> getUsers(

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

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


   return userService.findPage(page, size);


}

常用属性：

required：是否必填（默认 true，不填会报错）

defaultValue：默认值（设置后 required 自动变为 false）

@RequestBody：接收 JSON 请求体

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


@PostMapping("/users")


public User addUser(@RequestBody User user) {


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

   return userService.save(user);


}

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

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

@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（通用组件），它们都是为了让代码分层更清晰。

@Resource：按名称注入依赖

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


@Service

public class OrderService {


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

   @Resource(name = "orderDao")


   private OrderDao orderDao;


}

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

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

@Transactional：声明式事务管理

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


@Service

public class OrderService {


   // 该方法在事务中执行

   @Transactional

   public void createOrder(Order order) {


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

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

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

   }


}

常用属性：

rollbackFor：指定哪些异常会触发回滚（默认只有 RuntimeException 才回滚）

propagation：事务传播行为（如 REQUIRED、SUPPORTS 等）

@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 {


   // ...

}

五、配置与参数绑定

@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}")。

@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 中自动提示配置项。

六、其他高频注解

@ResponseBody：返回 JSON 数据

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


@Controller

public class ApiController {


   // 返回 JSON 数据

   @GetMapping("/api/user")


   @ResponseBody

   public User getUser() {


       // ...

   }


}

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

@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<User> 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("系统异常，请联系管理员");


   }


}

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