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