Spring Boot 常用注解全解析：20 個高頻注解 + 使用場景實例
還在對著 Spring Boot 項目里的注解一臉懵？@Controller 和 @RestController 到底有啥區(qū)別？@Autowired 注入總出問題該咋整？別慌！今天這篇文章，我把 Spring Boot 開發(fā)中最常用的 20 個注解一次性講透，每個注解都配上真實業(yè)務場景的代碼示例，看完讓你對注解的使用豁然開朗，開發(fā)效率直接翻倍！
一、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 配置文件
標記一個類是配置類，相當于傳統(tǒng)的 XML 配置文件，里面可以用 @Bean 注解定義 bean。
@Configuration
public class AppConfig {
// 定義一個 RestTemplate 實例，全局可用
@Bean
public RestTemplate restTemplate() {
return new RestTemplate();
}
}優(yōu)勢：用 Java 代碼寫配置，比 XML 更靈活，還能加邏輯判斷。
3. @ComponentScan：指定組件掃描范圍
告訴 Spring 要掃描哪些包下的組件（@Controller、@Service 等），@SpringBootApplication 已經(jīng)包含了它，默認掃描當前類所在的包及其子包。
// 手動指定掃描范圍
@SpringBootApplication
@ComponentScan(basePackages = {"com.example.controller", "com.example.service"})
public class MyApplication {
// ...
}坑點：如果你的組件不在默認掃描范圍內，就會注入失敗，此時必須手動指定。
二、Web 開發(fā)注解：處理 HTTP 請求
4. @Controller：頁面交互的控制器
標記一個類是 Spring MVC 的控制器，負責接收用戶請求并返回視圖（如 HTML 頁面）。
@Controller
public class UserController {
// 處理 GET 請求，返回 user.html 頁面
@GetMapping("/user")
public String getUser(Model model) {
model.addAttribute("name", "張三"); // 向頁面?zhèn)鬟f數(shù)據(jù)
return"user"; // 返回 templates 目錄下的 user.html
}
}5. @RestController：API 接口的 “懶人注解”
這是 @Controller + @ResponseBody 的組合，返回的是 JSON 數(shù)據(jù)，不用再在每個方法上寫 @ResponseBody 了。
@RestController
public class ApiController {
// 直接返回 JSON 數(shù)據(jù)
@GetMapping("/api/user")
public User getUser() {
User user = new User();
user.setName("李四");
user.setAge(25);
return user; // 自動轉為 JSON
}
}適用場景：前后端分離項目的 API 接口，現(xiàn)在 90% 的 Spring Boot 項目都用它。
6. @RequestMapping：請求映射的 “萬能注解”
指定方法處理哪些 HTTP 請求，可用于類和方法上，支持 GET、POST 等所有請求方式。
// 類上指定統(tǒng)一前綴
@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 請求
7. @PathVariable：獲取 URL 路徑參數(shù)
從 URL 路徑中提取參數(shù)，比如從 /users/123 中獲取 123 這個 id。
@GetMapping("/users/{id}")
public User getUser(@PathVariable Long id) {
return userService.findById(id);
}
// 多個參數(shù)
@GetMapping("/users/{id}/orders/{orderId}")
public Order getOrder(@PathVariable Long id, @PathVariable Long orderId) {
// ...
}8. @RequestParam：獲取 URL 查詢參數(shù)
獲取 URL 中？后面的參數(shù)，比如從 /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 自動變?yōu)?false）
9. @RequestBody：接收 JSON 請求體
接收請求體中的 JSON 數(shù)據(jù)，并把它轉換成對應的 Java 對象，POST、PUT 請求傳遞復雜對象時常用。
@PostMapping("/users")
public User addUser(@RequestBody User user) {
// user 已經(jīng)是轉換好的對象，直接保存即可
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：標記業(yè)務邏輯層
告訴 Spring 這是一個服務層組件，負責處理業(yè)務邏輯，會被自動掃描并注入。
@Service
public class UserService {
// 業(yè)務邏輯處理
}同類注解：@Repository（數(shù)據(jù)訪問層）、@Component（通用組件），它們都是為了讓代碼分層更清晰。
12. @Resource：按名稱注入依賴
和 @Autowired 類似，但它默認按名稱匹配，而 @Autowired 默認按類型匹配。
@Service
public class OrderService {
// 按名稱注入（name 可省略，默認取屬性名）
@Resource(name = "orderDao")
private OrderDao orderDao;
}小技巧：如果你更在意 bean 的名稱，用 @Resource 更方便。
四、數(shù)據(jù)訪問注解：操作數(shù)據(jù)庫
13. @Transactional：聲明式事務管理
加在方法或類上，讓方法執(zhí)行在事務中，出現(xiàn)異常時自動回滾，保證數(shù)據(jù)一致性。
@Service
public class OrderService {
// 該方法在事務中執(zhí)行
@Transactional
public void createOrder(Order order) {
orderDao.save(order); // 保存訂單
inventoryService.reduceStock(order.getProductId(), order.getNum()); // 扣減庫存
// 如果上面的代碼拋出異常，事務會回滾，訂單和庫存操作都取消
}
}常用屬性：
- rollbackFor：指定哪些異常會觸發(fā)回滾（默認只有 RuntimeException 才回滾）
- propagation：事務傳播行為（如 REQUIRED、SUPPORTS 等）
14. @Mapper：MyBatis 接口映射
標記一個接口是 MyBatis 的 Mapper 接口，不用寫實現(xiàn)類就能直接調用。
@Mapper
public interface UserMapper {
// 直接寫方法，SQL 在 XML 中或用注解寫
User selectById(Long id);
}替代方案：在主啟動類上用 @MapperScan 掃描整個包，不用每個接口都加 @Mapper。
@SpringBootApplication
@MapperScan("com.example.mapper") // 掃描所有 Mapper 接口
public class MyApplication {
// ...
}五、配置與參數(shù)綁定
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 更適合讀取多個相關配置。
# 數(shù)據(jù)庫配置
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 必須有，否則無法綁定
}優(yōu)勢：支持嵌套屬性、校驗（加 @Validated），還能在 IDE 中自動提示配置項。
六、其他高頻注解
17. @ResponseBody：返回 JSON 數(shù)據(jù)
讓方法返回的對象自動轉為 JSON 數(shù)據(jù)，一般用在 @Controller 類的方法上。
@Controller
public class ApiController {
// 返回 JSON 數(shù)據(jù)
@GetMapping("/api/user")
@ResponseBody
public User getUser() {
// ...
}
}注意：@RestController 已經(jīng)包含了它，所以不用重復加。
18. @PathVariable：獲取 URL 路徑參數(shù)
從 URL 路徑中提取參數(shù)，比如從 /users/123 中獲取 123 這個 id。
@GetMapping("/users/{id}")
public User getUser(@PathVariable Long id) {
return userService.findById(id);
}19. @RequestParam：獲取查詢參數(shù)
獲取 URL 中？后面的參數(shù)，比如從 /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：全局異常處理
統(tǒng)一處理控制器中的異常，不用在每個方法中寫 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("系統(tǒng)異常，請聯(lián)系管理員");
}
}效果：控制器拋出異常后，會自動被這里的方法捕獲并處理，返回統(tǒng)一的錯誤格式。
為什么這些注解能讓你少加班？
Spring Boot 的注解看似繁多，但核心都是為了簡化開發(fā)。掌握這些高頻注解，你能：
- 告別 XML 配置，用注解快速實現(xiàn)功能
- 精準處理 HTTP 請求，輕松獲取參數(shù)和返回數(shù)據(jù)
- 合理管理組件依賴，避免注入失敗的坑
- 用事務和異常處理保證系統(tǒng)穩(wěn)定性
這些注解就像是 Spring Boot 的 “快捷鍵”，熟練運用它們，別人寫一天的代碼，你半天就能搞定！
