掌握這九大類50個Spring Boot常用注解，開發效率飆升
環境：SpringBoot3.4.2
1. 簡介
高效開發是每一位開發者追求的目標，Spring Boot 憑借其強大功能與便捷性，成為開發者的首選框架。Spring Boot 之所以能助力開發者快速搭建項目，很大程度上得益于它豐富多樣的注解。這些注解能簡化代碼、優化配置，讓開發過程變得輕松又高效。
Spring Boot 注解數量眾多、功能各異，對于開發者來說，全面掌握并非易事。為了幫助到大家，本篇文章精心梳理了 9 大類共 50 個 Spring Boot 常用注解。無論是項目初始化、依賴注入，還是數據處理、安全控制等各個環節，都有對應的注解詳解。掌握這些注解，能讓你在項目開發中游刃有余，開發效率實現質的飛躍，輕松應對各種復雜開發場景。
圖片
2.實戰案例
2.1 組件相關注解（@Component）
@Controller
用于在 MVC 模式中修飾控制器層的組件。Spring Boot 中的組件掃描功能會識別該注解，并為被修飾的類實例化一個對象。它通常與 @RequestMapping 配合使用。當 Spring MVC 接收到一個請求時，會將其轉發到指定路徑對應的方法進行處理。如下示例：
@Controller
@RequestMapping("/users")
public class UserController {
}@Service
通常用于修飾服務層的組件。如下示例：
@Service
public class UserService {
}@Repository
用于修飾數據訪問對象（DAO）層的組件。DAO 層的組件專注于系統數據的處理，例如數據庫中的數據，如果你使用Spring Data JPA，定義的Repository你可以不使用任何注解。如下示例：
@Repository
public interface UserRepository extends JpaRepository<Role, Long> {
}該接口上的@Repository注解可有可無。
@Component
一般指組件。當組件難以歸類時，可使用此注解進行標記。其功能與 @Service 類似。如下示例：
@Component
public class MessageHandler {
}2.2 與Bean實例及生命周期相關的注解
@Bean
用于修飾方法，表明該方法將創建一個Bean實例，并由Spring容器進行管理。如下示例：
@Configuration
public class AppConfig {
@Bean
public MessageHandler messageHandler() {
return new MessageHandler() ;
}
}@Scope
用于聲明Spring Bean實例的作用域。作用域類型如下：
- singleton：單例模式。該實例在Spring容器中是唯一的。這是Spring中的默認實例模式
- prototype：原型模式。每次使用時都會重新創建實例
- request：在同一個請求中使用同一個實例。不同的請求會創建新實例
- session：在同一個會話（Session）中使用同一個實例。不同的會話會創建新實例
- application：用于定義其生命周期與當前 Web 應用程序綁定（即作用域為整個 Web 應用）的組件。
@Configuration
public class RestTemplateConfig {
@Bean
@Scope("proptotype")
public RestTemplate restTemplate(){
return new RestTemplate();
}
}@Primary
當存在同一類型的多個對象實例時，標注此注解的實例將被優先選用。如下示例：
@Configuration
public class JavaConfig {
@Bean("b1")
@Primary
B b1() {
return new B();
}
@Bean("b2")
B b2() {
return new B();
}
}@PostConstruct
用于修飾一個方法。該方法會在對象實例創建完成且依賴注入結束后執行，可用于對對象實例進行初始化操作。如下示例：
public class UserService {
private final UserRepository userRepository;
public UserService(UserRepository userRepository) {
this.userRepository = userRepository;
}
@PostConstruct
public void init() {
// TODO
}
}@PreDestroy
用于修飾一個方法。當對象實例即將被 Spring 容器銷毀時，該方法會被執行。它可用于釋放對象實例所持有的資源。
@Service
public class UserService {
@PreDestroy
public void preDestroy(){
// TODO
}
}2.3 依賴注入相關注解
@Autowired
根據對象的類型自動注入依賴對象。默認情況下，它要求被注入的對象實例必須存在。你可以通過配置 required=false 來注入一個可能并不一定存在的對象。
@RestController
@RequestMapping("/users")
public class UserController {
@Autowired
private UserService userService ;
@Autowired(required = false)
private CommonService commonService ;
}@Resource
默認情況下，它根據對象名稱自動注入依賴對象。若想按類型進行注入，可將屬性設置為 type = UserService.class 。
@RestController
@RequestMapping("/users")
public class UserController {
@Resource(name = "userServiceImpl")
private UserService userService;
}@Qualifier
當存在多個同類型的 Bean 時，若使用 @Autowired 進行注入，會導致報錯，提示當前對象不唯一，Spring 不知道該注入哪個依賴。此時，我們可以使用 @Qualifier 進行更精細的控制，從候選 Bean 中選擇一個。它通常與 @Autowired 配合使用。示例如下：
@Autowired
@Qualifier("userService")
private UserService userService ;2.4 Spring MVC相關注解
@RequestMapping
提供路由信息，負責將 URL 映射到 Controller 中的特定方法。當用于方法上時，它可以指定請求協議，例如 GET、POST、PUT、DELETE 等。
@RequestBody
表示請求體的 Content-Type 必須為 application/json 格式的數據。接收到數據后，它會自動將數據綁定到 Java 對象上。
@ResponseBody
表示該方法的返回結果將直接寫入 HTTP 響應體中。返回數據的格式為 application/json。如下完整示例：
@Controller
@RequestMapping("/api")
public class LoginController {
@RequestMapping(value = "/login", method = RequestMethod.POST)
@ResponseBody
public ResponseEntity<?> login(@RequestBody UserLoginDTO request){
// TODO
return ResponseEntity.ok("success") ;
}
}@RestController
和 @Controller 一樣，用于標注控制器層組件。不同之處在于，它是 @ResponseBody 和 @Controller 兩個注解的組合。
也就是說，當在類上使用 @RestController 時，意味著當前類中所有對外暴露的接口方法，其返回數據的格式均為 application/json。如下示例：
@RestController
@RequestMapping("/api")
public class LoginController {
@RequestMapping(value = "/login", method = RequestMethod.POST)
public ResponseEntity login(@RequestBody UserLoginDTO request){
// TODO
return new ResponseEntity(HttpStatus.OK);
}
}@RequestParam
用于接收以表單形式（form type）傳遞的請求參數數據。它通常被放置在方法的參數前面。如下示例：
@RequestMapping(value = "login", method = RequestMethod.POST)
@ResponseBody
public ResponseEntity<?> login(
@RequestParam(value = "username", required = true) String username,
@RequestParam(value = "pwd",required = true) String password){
// TODO
return ResponseEntity.ok("success");
}@PathVariable
用于獲取請求路徑中的參數，通常用于 RESTful 風格的 API 中。如下示例：
@RequestMapping(value = "/products/{id}", method = RequestMethod.POST)
@ResponseBody
public ResponseEntity<?> queryProduct(@PathVariable("id") Long id){
// TODO
return ResponseEntity.ok(product);
}@GetMapping、@PostMapping、@PutMapping、@DeleteMapping
除了 @RequestMapping 可以指定請求方法外，還有一些其他注解可用于標注接口路徑請求。例如，當在方法上使用 @GetMapping 時，表示僅支持 GET 請求方法。它等價于 @RequestMapping(value="/get", method=RequestMethod.GET) 。如下示例：
@GetMapping("get")
public ResponseEntity get(){
// TODO
}
@PostMapping("post")
public ResponseEntity post(){
// TODO
}
@PutMapping("put")
public ResponseEntity put(){
// TODO
}
@DeleteMapping("delete")
public ResponseEntity delete(){
// TODO
}2.5 配置類相關
@Configuration
用于聲明一個基于 Java 的配置類。Spring Boot 倡導使用基于 Java 的配置方式，這相當于之前在 XML 文件中配置 beans。例如，聲明一個配置類 AppConfig，然后初始化一個 CommonUtils 對象。
@Configuration
public class AppConfig {
@Bean
public CommonUtils commonUtils() {
return new CommonUtils();
}
}@EnableAutoConfiguration
@EnableAutoConfiguration 能夠助力 Spring Boot 應用程序將所有符合條件的 @Configuration 配置類加載到當前的 Spring Boot 環境中，創建與這些配置類相對應的 Bean，并將這些 Bean 實體交由 IoC 容器進行管理。如下示例：
@Configuration
@EnableAutoConfiguration
public class PackAutoConfiguration {
}@ComponentScan
用于標注 Spring 需要掃描哪些路徑下的類。它用于自動發現和裝配一些 Bean 對象。默認配置是掃描當前文件夾及其子目錄中的所有類。如果我們想指定只掃描某些特定的包路徑，可以按如下方式處理。如下示例：
@Configuration
@ComponentScan(basePackages = {"com.pack", "com.xg"})
public class AppConfig {}@SpringBootApplication
它等效于同時使用 @Configuration、@EnableAutoConfiguration 和 @ComponentScan 這三個注解。通常用于全局啟動類上。如下示例：
@SpringBootApplication
public class App {
public static void main(String[] args) {
SpringApplication.run(App.class, args);
}
}使用 @Configuration、@EnableAutoConfiguration 和 @ComponentScan 這三個注解替代 @SpringBootApplication 也能成功啟動應用。@SpringBootApplication 只是對這三個注解的簡化。
@EnableTransactionManagement
表示啟用事務支持，其作用等同于 XML 配置方式中的 <tx:annotation-driven />。
@SpringBootApplication
@EnableTransactionManagement`
public class App {
public static void main(String[] args) {
SpringApplication.run(App.class, args);
}
}@ConfigurationProperties
用于批量注入外部配置，并以對象形式導入帶有指定前綴的配置項。如下示例：
配置文件
pack:
app:
title: xxxooo
version: 1.0.0配置類
@Component
@ConfigurationProperties(prefix = "pack.app")
public class AppProperties {
private String title ;
private String version ;
// getters, setters
}@Conditional
從 Spring 4 開始，可以使用 @Conditional 注解根據條件有條件地加載 Bean 對象。目前，在 Spring Boot 的源代碼中，@Conditional 注解已被廣泛擴展，用于實現智能自動配置，以滿足各種使用場景。以下是一些常用的注解：
- @ConditionalOnBean：當存在特定的 Bean 時，配置生效
- @ConditionalOnMissingBean：當不存在特定的 Bean 時，配置生效
- @ConditionalOnClass：當 Classpath 中存在指定的類時，配置生效
- @ConditionalOnMissingClass：當 Classpath 中不存在指定的類時，配置生效
- @ConditionalOnExpression：當給定的 SpEL 表達式計算結果為 true 時，配置生效
- @ConditionalOnProperty：當指定的配置屬性具有確定值且匹配時，配置生效
如下示例：
@Configuration
public class ConditionalConfig {
/**當 Test 對象存在時，創建對象 A。*/
@ConditionalOnBean(Test.class)
@Bean
public A createA() {
return new A();
}
/**當 Test 對象不存在時，創建對象 B。*/
@ConditionalOnMissingBean(Test.class)
@Bean
public B createB() {
return new B();
}
/**當 Test 類存在時，創建對象 C。*/
@ConditionalOnClass(Test.class)
@Bean
public C createC() {
return new C();
}
/**當 Test 類不存在時，創建對象 D。*/
@ConditionalOnMissingClass(Test.class)
@Bean
public D createD() {
return new D();
}
/**當 enableConfig 配置為 true 時，創建對象 E。*/
@ConditionalOnExpression("${enableConfig:false}")
@Bean
public E createE() {
return new E();
}
/**當 filter.loginFilter 配置為 true 時，創建對象 F*/
@ConditionalOnProperty(prefix = "filter", name = "loginFilter", havingValue = "true")
@Bean
public F createF() {
return new F();
}
}@Value
在 Spring 管理的任何 Bean 中，都可以通過該注解從任意配置源（如 application.properties、application.yml 或環境變量等）獲取配置的屬性值。
配置文件
pack:
app:
title: xxxooo使用@Value
@RestController
public class HelloController {
@Value("${pack.app.title:}")
private String title;
@GetMapping("title")
public String getTitle(){
return title;
}
}@PropertySource
該注解用于加載自定義配置文件（而非默認的 application.properties 或 application.yml）。如下示例：
@Component
@PropertySource(value = {"app.properties", "bussiness.properties"})
public class LoadConfig {
}@ImportResource
該注解用于加載 XML 格式的 Spring 配置文件。例如，若需導入自定義的 aaa.xml 配置文件，如下示例：
@ImportResource(locations = "classpath:ureport.xml")
@Component
public class UReportConfig {
}2.6 JPA相關注解
@Entity 和 @Table
用于標識一個類為實體類（與數據庫表映射的 Java 類）。這兩個注解通常一起使用，但若表名與實體類名相同，可省略 @Table 注解。
@Id
標識該屬性字段對應數據庫表中的主鍵字段。
@Column
標識該屬性字段對應的數據庫表中的列名。若字段名與列名相同，可省略此注解。
@GeneratedValue
定義主鍵的生成策略，共有以下四種選項：
- AUTO（默認）：由程序自動控制主鍵生成方式（未顯式指定時默認使用此策略）
- IDENTITY：由數據庫自動生成主鍵（依賴數據庫的自增機制，Oracle 不支持）
- SEQUENCE：通過數據庫序列（Sequence）生成主鍵（MySQL 不支持）
- TABLE：通過特定的數據庫表生成主鍵（便于數據庫遷移）。
@SequenceGenerator
用于定義一個數據庫序列生成器（用于生成主鍵），需與 @GeneratedValue 配合使用才生效。如下完整示例：
@Entity
@Table(name = "TB_ROLE")
@SequenceGenerator(name = "id_seq", sequenceName = "seq_repair",allocationSize = 1)
public class Role {
@Id
@GeneratedValue(strategy = GenerationType.SEQUENCE, generator = "id_seq")
private Long id;
@Column(nullable = false)
private String roleName;
@Column(nullable = false)
private String roleType;
}@Transient
該注解用于標識某個屬性不映射到數據庫表的字段，ORM 框架（如 JPA/Hibernate）在執行數據庫操作時會自動忽略此屬性。
@Column(nullable = false)
@Transient
private String lastTime;@Basic(fetch = FetchType.LAZY)
該注解用于指定特定屬性的加載策略，可實現懶加載（延遲加載）效果。即：僅當程序實際訪問該字段時，才會從數據庫加載其值。若配置為 fetch = FetchType.EAGER，則表示立即加載（默認加載方式），如下示例：
@Column(nullable = false)
@Basic(fetch = FetchType.LAZY)
private String content;@JoinColumn
該注解用于標注表示表間關聯關系的字段，通常與 @OneToOne、@OneToMany 或 @ManyToOne 等關聯映射注解配合使用。它定義了外鍵列的映射規則，即當前實體與關聯實體在數據庫表中的連接方式。
@Entity
@Table(name = "t_user")
public class User {
@OneToOne
@JoinColumn(name = "user_id")
private IdCard card ;
}@OneToOne、@OneToMany 和 @ManyToOne
這三個注解分別對應 Hibernate 配置文件中的一對一（one-to-one）、一對多（one-to-many）和多對一（many-to-one）關聯關系配置。例如，在下述客戶-地址表的場景中，可通過客戶 ID 查詢關聯的客戶信息。
@Entity
@Table(name = "t_cutomer")
public class Customer {
@Id
private Long id;
private String name;
// 一對多關聯：一個客戶有多個地址
@OneToMany(mappedBy = "customer", cascade = CascadeType.ALL)
private List<Address> addresses = new ArrayList<>();
}
@Entity
@Table(name = "t_address")
public class Address {
@Id
private Long id;
private String detail;
@ManyToOne
@JoinColumn(name = "c_id", nullable = false)
private Customer customer;
}2.7 異常相關注解
@ControllerAdvice 與 @ExceptionHandler
這兩個注解通常結合使用，用于實現全局異常處理。如下示例：
@RestControllerAdvice
public class GlobalExceptionHandler {
private static final Integer GLOBAL_ERROR_CODE = 500;
@ExceptionHandler(value = Exception.class)
public void exceptionHandler(HttpServletRequest request, HttpServletResponse response, Exception e) throws Exception {
ResultMsg<Object> resultMsg = new ResultMsg<>();
resultMsg.setCode(GLOBAL_ERROR_CODE);
if (e instanceof CommonException) {
CommonException ex = (CommonException) e;
if(ex.getErrCode() != 0) {
resultMsg.setCode(ex.getErrCode());
}
resultMsg.setMsg(ex.getErrMsg());
} else {
resultMsg.setMsg(CommonErrorMsg.SYSTEM_ERROR.getMessage());
}
WebUtil.out(response, resultMsg);
}
}2.8 AOP相關
@Aspect
用于定義一個切面（Aspect）。切面是通知（Advice）和切入點（Pointcut）的組合，它定義了何時（When）以及在何處（Where）應用通知的功能。
@Before
表示前置通知（Before Advice）。通知方法會在目標方法調用之前執行。通知描述了切面要執行的工作及其執行時機。
@After
表示后置通知（After Advice）。通知方法會在目標方法返回或拋出異常之后執行。
@AfterReturning
表示返回通知（Returning Advice）。通知方法會在目標方法成功返回后執行。
@AfterThrowing
表示異常通知（Throwing Advice）。通知方法會在目標方法拋出異常后執行。
@Around
表示環繞通知（Around Advice）。通知方法會包裹目標方法，并在目標方法調用前后執行自定義邏輯（可通過參數 ProceedingJoinPoint 控制目標方法的執行）。
@Pointcut
定義一個切入點表達式，用于指定通知功能的應用范圍（即哪些方法會被攔截）。
@Order
用于定義組件的執行順序。在 AOP 中，它指定切面的執行優先級。value 屬性值越小，優先級越高（先執行）。
@Aspect
@Component
@Order(1)
public class WebLogAspect {
private static final Logger logger = LoggerFactory.getLogger(WebLogAspect.class);
@Pointcut("execution(public * com.dylan.smith.web.controller.*.*(..))")
public void webLog() {
// TODO
}
@Before("webLog()")
public void doBefore(JoinPoint joinPoint) throws Throwable {
// TODO
}
@AfterReturning(value = "webLog()", returning = "ret")
public void doAfterReturning(Object ret) throws Throwable {
// TODO
}
@Around("webLog()")
public Object doAround(ProceedingJoinPoint joinPoint) throws Throwable {
WebLog webLog = new WebLog();
Object result = joinPoint.proceed();
logger.info("{}", JSONUtil.parse(webLog));
return result;
}
}2.9 測試相關
@Test
將一個方法指定為測試方法。
@ActiveProfiles
通常應用于測試類，用于聲明激活的Spring配置文件。例如，指定application-dev.properties配置文件。
@RunWith 和 @SpringBootTest
通常應用于測試類，用于單元測試，如下示例：
@ActiveProfiles("dev")
@RunWith(SpringRunner.class)
@SpringBootTest
public class TestJunit {
@Test
public void testTask() {
// TODO
}
}
