Spring Framework 常用注解詳解（按所屬包分類整理）

在使用 Spring Framework 進行開發時，注解（Annotation）是實現 依賴注入（DI）、組件掃描、AOP 切面、事務管理 和 Web 請求映射 的核心手段。Spring 提供了豐富且結構清晰的注解體系，這些注解按照功能被組織在不同的包中。

本文?按注解所屬的包（package）進行分類，詳細說明每個包的用途，并列舉該包下的常用注解及其功能。

1.?`org.springframework.stereotype` —— 組件聲明注解

🔹 用途說明：

該包提供了用于 聲明 Spring 管理的組件（Bean） 的注解。Spring 容器通過組件掃描（@ComponentScan）自動發現這些類，并將其注冊為 Bean 實例。這些注解主要用于類級別，實現分層架構的語義化標注。

? 常用注解：

注解	詳細說明
`@Component`	通用組件注解，任何被 Spring 管理的類都可以使用。它是`@Service`、`@Repository`、`@Controller`的父注解。
`@Service`	專用于業務邏輯層（Service 層），語義更明確，便于代碼維護和分層設計。
`@Repository`	專用于數據訪問層（DAO/Repository），除了注冊為 Bean 外，還能自動將數據庫異常（如 SQLException）轉換為 Spring 的`DataAccessException`，便于統一異常處理。
`@Controller`	用于 Web 層控制器，通常與`@RequestMapping`配合使用，處理 HTTP 請求。
`@RestController`	雖然實際位于`org.springframework.web.bind.annotation`包中，但功能上屬于此分類。它是`@Controller + @ResponseBody`的組合注解，用于構建 RESTful API，返回 JSON/XML 數據，無需額外標注`@ResponseBody`。

💡 提示：使用這些注解后，需配合 @ComponentScan 啟用組件掃描，Spring 才能自動發現并注冊這些 Bean。

`2.?org.springframework.beans.factory.annotation` —— 依賴注入（DI）核心注解

🔹 用途說明：

該包提供了 Spring 依賴注入（DI）的核心注解，用于實現 自動裝配（Autowiring） 和 屬性注入。它們可以作用于字段、方法、構造器等位置，是實現松耦合設計的關鍵。

? 常用注解：

注解	詳細說明
`@Autowired`	自動裝配 Bean，默認按類型（byType）查找并注入。可作用于字段、setter 方法、構造器等。若存在多個同類型 Bean，需配合`@Qualifier`使用。
`@Qualifier`	與`@Autowired`配合使用，通過指定 Bean 的名稱（id）來解決類型沖突問題。例如：`@Qualifier("userServiceImpl")`。
`@Value`	用于注入基本類型或字符串值，支持從配置文件（如`application.properties`）讀取屬性值，語法為`${key}`；也支持 SpEL（Spring Expression Language）表達式，語法為`#{expression}`。例如： `@Value("${server.port}")` `@Value("#{systemProperties['os.name']}")`

💡 提示：@Value 是實現外部化配置（Externalized Configuration）的重要手段，常用于讀取環境變量、配置項等。

3.?`org.springframework.context.annotation` —— 配置與條件化注解

🔹 用途說明：

該包提供了基于 Java 的配置方式（Java Config），用于替代傳統的 XML 配置文件。它支持 配置類定義、組件掃描、條件化加載、環境隔離 等高級功能，是構建現代化 Spring 應用的基礎。

? 常用注解：

注解	詳細說明
`@Configuration`	標記一個類為配置類，相當于一個 XML 配置文件。此類中通常包含`@Bean`方法。
`@Bean`	標注在方法上，表示該方法返回的對象將被注冊為 Spring 容器中的 Bean。常用于配置第三方組件（如 DataSource、RedisTemplate 等）。
`@ComponentScan`	啟用組件自動掃描，指定掃描的包路徑。Spring 會自動發現并注冊帶有`@Component`及其衍生注解的類。
`@PropertySource`	用于加載`.properties`屬性文件，通常與`@Configuration`一起使用。例如： `@PropertySource("classpath:app.properties")` 配合`@Value`注入屬性值。
`@Import`	導入其他配置類，實現配置的模塊化管理。例如： `@Import(DatabaseConfig.class)`
`@Profile`	指定某個 Bean 或配置類僅在特定環境下生效（如`dev`、`test`、`prod`）。例如： `@Profile("dev")` 結合`spring.profiles.active`屬性控制環境切換。
`@Scope`	定義 Bean 的作用域，常見值有： -`singleton`（默認，單例） -`prototype`（每次獲取都創建新實例） -`request`、`session`（Web 環境下）
`@Lazy`	標記 Bean 為延遲初始化，僅在首次使用時創建，可提升應用啟動速度。
`@Primary`	當容器中存在多個相同類型的 Bean 時，標記該 Bean 為“首選”，避免`@Autowired`報錯。

💡 提示：這些注解是實現“零 XML 配置”的關鍵，尤其在 Spring Boot 中被廣泛使用。

4.?`org.springframework.web.bind.annotation` —— Web 與 MVC 注解

🔹 用途說明：

該包是 Spring MVC 的核心注解集合，用于處理 HTTP 請求映射、參數綁定、響應處理 等 Web 層功能。適用于構建傳統的 MVC 應用或 RESTful 風格的 Web 服務。

? 常用注解：

注解	詳細說明
`@RequestMapping`	最基礎的請求映射注解，可作用于類或方法，支持設置 URL 路徑、請求方法（GET/POST）、參數、請求頭等。
`@GetMapping`	快捷方式，等價于`@RequestMapping(method = RequestMethod.GET)`，用于映射 GET 請求。
`@PostMapping`	映射 POST 請求，常用于表單提交或創建資源。
`@PutMapping`	映射 PUT 請求，用于更新資源。
`@DeleteMapping`	映射 DELETE 請求，用于刪除資源。
`@PatchMapping`	映射 PATCH 請求，用于部分更新資源。
`@RequestParam`	綁定請求參數（如`?name=張三`）到方法參數。支持設置是否必填（`required`）、默認值（`defaultValue`）。
`@PathVariable`	綁定 URL 路徑中的變量（如`/users/{id}`），常用于 RESTful 風格接口。
`@RequestBody`	將 HTTP 請求體（如 JSON）反序列化為 Java 對象，常用于 POST/PUT 請求體數據綁定。
`@ResponseBody`	將方法返回值直接寫入 HTTP 響應體（如返回 JSON），常用于 AJAX 或 REST 接口。
`@RestController`	組合注解，等價于`@Controller + @ResponseBody`，所有方法默認返回數據而非視圖名。
`@RequestHeader`	獲取 HTTP 請求頭信息，如`User-Agent`、`Authorization`等。
`@CookieValue`	獲取 Cookie 的值。
`@ModelAttribute`	用于綁定表單數據到對象，或在請求處理前向模型中添加屬性。

💡 提示：@RestController 是構建前后端分離項目的核心注解，推薦用于 REST API 開發。

5.?`org.springframework.transaction.annotation` —— 事務管理注解

🔹 用途說明：

該包提供了聲明式事務管理的支持，通過注解方式控制數據庫事務的邊界，避免手動管理 Connection、commit、rollback，提升代碼可讀性和一致性。

? 常用注解：

注解	詳細說明
`@Transactional`	標記方法或類需要事務管理。支持配置： - 傳播行為（Propagation） - 隔離級別（Isolation） - 超時時間（timeout） - 是否只讀（readOnly） - 回滾規則（rollbackFor）例如： `@Transactional(rollbackFor = Exception.class)`

?? 注意：需在配置類上添加 @EnableTransactionManagement 啟用事務支持（Spring Boot 自動配置）。

6. `org.aspectj.lang.annotation` —— AOP 切面編程注解

🔹 用途說明：

該包來自 AspectJ 框架，Spring 借助它實現 面向切面編程（AOP），用于處理日志、權限、性能監控、事務等橫切關注點（Cross-cutting Concerns）。

? 常用注解：

注解	詳細說明
`@Aspect`	定義一個切面類，該類中包含通知（Advice）方法。
`@Before`	前置通知，在目標方法執行前執行。
`@After`	最終通知，無論目標方法是否拋出異常，都會執行。
`@AfterReturning`	返回通知，在目標方法成功執行并返回后執行。
`@AfterThrowing`	異常通知，在目標方法拋出異常后執行。
`@Around`	環繞通知，最強大的通知類型，可以控制目標方法的執行（如前置邏輯 → 執行方法 → 后置邏輯）。
`@Pointcut`	定義切點表達式，用于復用切點邏輯。例如： `@Pointcut("execution(* com.example.service..(..))")`

?? 注意：使用這些注解需引入 aspectjweaver 依賴，并啟用 AOP 支持（如 @EnableAspectJAutoProxy）。

7. 測試相關注解（Spring Boot Test 模塊）

雖然嚴格來說不屬于純 Spring Framework，但在實際開發中極為常用，特此補充。

🔹 所屬包：

org.springframework.boot.test.context
org.springframework.boot.test.autoconfigure.web.servlet
org.springframework.boot.test.mock.mockito

? 常用注解：

注解	詳細說明
`@SpringBootTest`	啟動完整的 Spring 上下文，用于集成測試。
`@WebMvcTest`	僅加載 Web 層（Controller），用于測試控制器邏輯。
`@DataJpaTest`	僅加載 JPA 相關配置，常用于 Repository 層測試，自動配置內存數據庫。
`@MockBean`	在測試中創建一個 Mock Bean（如 Mockito 對象），并注冊到 Spring 容器中，用于模擬依賴。

💡 提示：這些注解屬于 spring-boot-test 模塊，適用于 Spring Boot 項目。

? 總結：Spring 注解體系概覽

包名	主要功能	典型使用場景
`org.springframework.stereotype`	組件聲明	分層架構 Bean 標注
`org.springframework.beans.factory.annotation`	依賴注入	自動裝配、屬性注入
`org.springframework.context.annotation`	配置管理	Java Config、條件化加載
`org.springframework.web.bind.annotation`	Web 請求處理	MVC、REST API 開發
`org.springframework.transaction.annotation`	事務管理	數據庫操作一致性控制
`org.aspectj.lang.annotation`	AOP 切面	日志、權限、性能監控
`spring-boot-test`相關包	測試支持	單元測試、集成測試