Spring 常用註解速查表：核心、Web、資料層全覆蓋

前言

Spring 註解驅動開發已成主流。本文整理最實用的註解分類速查，涵蓋元件掃描、Bean 定義、注入、生命週期、AOP、事務、異步等核心場景，附關鍵屬性說明，適合開發時快速查閱。

一、啟用註解掃描

<context:component-scan base-package="com.example"/>
<!-- 或 Java Config -->
@ComponentScan("com.example")

base-package 指定掃描根套件，遞迴掃描子套件。

二、元件刻板印象註解

三、Bean 定義與作用域

四、依賴注入註解

五、生命週期回調

@PostConstruct  // 初始化後執行（相當於 init-method）
@PreDestroy     // 銷毀前執行（相當於 destroy-method）

方法簽名：void methodName()，不可有參數、不可拋受檢例外。

六、AOP 與事務

@Transactional 關鍵屬性：propagation（傳播行為）、isolation（隔離級別）、timeout、readOnly、rollbackFor。

七、異步與排程

@EnableAsync           // 啟用非同步支援
@Async("taskExecutor") // 方法標示非同步執行，可指定執行緒池 Bean 名稱

@EnableScheduling      // 啟用排程
@Scheduled(cron="0 0 12 * * ?") // 方法定時執行

需配置 ThreadPoolTaskExecutor Bean 名為 taskExecutor。

八、條件裝配與設定檔

九、Web 專用（Spring MVC / WebFlux）

@RequestMapping("/api")     // 類別/方法層級路徑映射
@GetMapping("/users")       // 組合註解：@RequestMapping(method=GET)
@PostMapping("/users")
@PathVariable Long id       // 路徑變數綁定
@RequestParam String name   // 查詢參數綁定
@RequestBody UserDTO dto    // JSON 請求體綁定
@ResponseBody               // 直接寫入 HTTP Response Body
@RestController             // @Controller + @ResponseBody
@ControllerAdvice           // 全域例外處理、資料綁定
@ExceptionHandler(Exception.class)

十、測試註解

@SpringBootTest           // 整合測試啟動完整上下文
@MockBean                 // 替換為 Mockito Mock
@AutoConfigureMockMvc     // 自動配置 MockMvc
@Test
@Transactional            // 測試結束自動回滾

總結

熟練掌握上述註解可大幅提升 Spring 開發效率。建議：

1. 優先使用建構子注入（不可變、易測試）。
2. 善用 @Primary/@Qualifier 解決多實例歧義。
3. 事務邊界盡量加在 Service 方法，避免 Controller 加事務。
4. 條件裝配實現多環境差異化配置。