以下是Spring Boot框架中常用注解的詳細說明，包括名稱、用途、用法、使用位置及擴展示例，按功能模塊分類整理：

---

一、核心啟動與配置注解

1. @SpringBootApplication

• 用途：主啟動類注解，整合了 @Configuration、@EnableAutoConfiguration 和 @ComponentScan。
• 用法：標記主類，啟動Spring Boot應用。
• 位置：類級別。
• 示例：

  @SpringBootApplication
  public class MyApp {public static void main(String[] args) {SpringApplication.run(MyApp.class, args);}
  }
  

2. @Configuration

• 用途：聲明一個類為配置類，用于定義Bean。
• 位置：類級別。
• 示例：

  @Configuration
  public class AppConfig {@Beanpublic DataSource dataSource() {return new HikariDataSource();}
  }
  

3. @Bean

• 用途：在配置類中定義Bean實例，交給Spring容器管理。
• 位置：方法級別。
• 示例：

  @Bean
  public RestTemplate restTemplate() {return new RestTemplate();
  }
  

---

二、依賴注入（DI）注解

1. @Autowired

• 用途：自動注入Bean，支持字段、構造器、方法注入。
• 位置：字段、構造器、方法參數。
• 示例：

  @Service
  public class UserService {@Autowiredprivate UserRepository userRepository; // 字段注入
  }// 構造器注入（推薦）
  @Service
  public class OrderService {private final PaymentService paymentService;@Autowiredpublic OrderService(PaymentService paymentService) {this.paymentService = paymentService;}
  }
  

2. @Qualifier

• 用途：按名稱指定注入的Bean（解決多個同類型Bean沖突）。
• 位置：字段、參數。
• 示例：

  @Autowired
  @Qualifier("mysqlDataSource")
  private DataSource dataSource;
  

3. @Component

• 用途：通用組件注解，標記類為Spring管理的Bean。
• 子注解：@Service、@Repository、@Controller。
• 位置：類級別。
• 示例：

  @Component
  public class EmailValidator { ... }
  

4. @Primary

• 用途：當存在多個同類型Bean時，優先注入標記為@Primary的Bean。
• 位置：類或方法級別。
• 示例：

  @Bean
  @Primary
  public DataSource primaryDataSource() { ... }
  

---

三、Web開發注解

1. @RestController

• 用途：標記為REST控制器，返回JSON/XML數據（等價于@Controller + @ResponseBody）。
• 位置：類級別。
• 示例：

  @RestController
  @RequestMapping("/api/users")
  public class UserController {@GetMapping("/{id}")public User getUser(@PathVariable Long id) { ... }
  }
  

2. @RequestMapping

• 用途：映射HTTP請求路徑和方法。
• 屬性：path（路徑）、method（請求方法）、produces（返回類型）。
• 位置：類或方法級別。
• 示例：

  @RequestMapping(value = "/books", method = RequestMethod.GET)
  public List<Book> getBooks() { ... }
  

3. @GetMapping / @PostMapping 等

• 用途：簡化的請求映射注解，支持GET、POST、PUT、DELETE等。
• 示例：

  @PostMapping("/create")
  public ResponseEntity<User> createUser(@RequestBody User user) { ... }
  

4. @PathVariable

• 用途：從URL路徑中獲取參數。
• 位置：方法參數。
• 示例：

  @GetMapping("/orders/{orderId}")
  public Order getOrder(@PathVariable("orderId") String id) { ... }
  

5. @RequestParam

• 用途：從請求參數中獲取值（如?name=John）。
• 屬性：required（是否必填）、defaultValue（默認值）。
• 示例：

  @GetMapping("/search")
  public List<User> searchUsers(@RequestParam(required = false) String keyword) { ... }
  

6. @RequestBody

• 用途：將請求體中的JSON/XML數據反序列化為Java對象。
• 位置：方法參數。
• 示例：

  @PostMapping("/users")
  public User createUser(@RequestBody User user) { ... }
  

7. @RequestHeader

• 用途：從HTTP請求頭中獲取值。
• 示例：

  @GetMapping("/info")
  public String getInfo(@RequestHeader("User-Agent") String userAgent) { ... }
  

8. @CrossOrigin

• 用途：允許跨域請求。
• 位置：類或方法級別。
• 示例：

  @CrossOrigin(origins = "http://localhost:3000")
  @RestController
  public class ApiController { ... }
  

---

四、數據訪問（JPA/Hibernate）注解

1. @Entity

• 用途：標記類為JPA實體，對應數據庫表。
• 位置：類級別。
• 示例：

  @Entity
  @Table(name = "employees")
  public class Employee { ... }
  

2. @Id / @GeneratedValue

• 用途：定義主鍵字段及生成策略。
• 示例：

  @Id
  @GeneratedValue(strategy = GenerationType.IDENTITY)
  private Long id;
  

3. @Column

• 用途：定義實體字段與數據庫列的映射關系。
• 屬性：name（列名）、nullable（是否允許空值）、length（長度）。
• 示例：

  @Column(name = "full_name", nullable = false, length = 50)
  private String name;
  

4. @Transactional

• 用途：聲明方法或類需要事務管理（如數據庫操作失敗自動回滾）。
• 位置：類或方法級別。
• 示例：

  @Service
  public class OrderService {@Transactionalpublic void placeOrder(Order order) {orderRepository.save(order);inventoryService.updateStock(order.getProductId());}
  }
  

---

五、配置管理注解

1. @Value

• 用途：注入配置文件中的屬性值。
• 位置：字段、方法參數。
• 示例：

  @Value("${app.name}")
  private String appName;@Value("${app.timeout:30}") // 默認值30
  private int timeout;
  

2. @ConfigurationProperties

• 用途：批量綁定配置文件屬性到Java對象。
• 位置：類級別。
• 示例：

  # application.yml
  database:url: jdbc:mysql://localhost:3306/mydbusername: rootpassword: secret
  

  @ConfigurationProperties(prefix = "database")
  @Component
  public class DatabaseConfig {private String url;private String username;private String password;// getters & setters
  }
  

---

六、測試注解

1. @SpringBootTest

• 用途：啟動完整Spring上下文進行集成測試。
• 位置：測試類。
• 示例：

  @SpringBootTest
  class UserServiceTest {@Autowiredprivate UserService userService;
  }
  

2. @MockBean

• 用途：在測試中模擬Bean（結合Mockito）。
• 示例：

  @SpringBootTest
  class PaymentServiceTest {@MockBeanprivate PaymentGateway paymentGateway;@Testvoid testPayment() {Mockito.when(paymentGateway.process(any())).thenReturn(true);// 測試邏輯}
  }
  

---

七、高級功能注解

1. @Scheduled

• 用途：定時任務調度。
• 屬性：fixedRate（固定頻率）、cron（Cron表達式）。
• 位置：方法級別。
• 示例：

  @Scheduled(cron = "0 0 2 * * ?") // 每天凌晨2點執行
  public void generateDailyReport() { ... }
  // 需在啟動類添加 @EnableScheduling
  

2. @Async

• 用途：異步執行方法。
• 位置：方法級別。
• 示例：

  @Async
  public void sendEmailAsync(String email) { ... }
  // 需在啟動類添加 @EnableAsync
  

3. @Cacheable / @CacheEvict

• 用途：聲明方法結果緩存或清除緩存。
• 示例：

  @Cacheable(value = "users", key = "#userId")
  public User getUser(Long userId) { ... }@CacheEvict(value = "users", key = "#userId")
  public void deleteUser(Long userId) { ... }
  // 需在啟動類添加 @EnableCaching
  

---

八、異常處理注解

1. @RestControllerAdvice

• 用途：全局異常處理，結合@ExceptionHandler使用。
• 示例：

  @RestControllerAdvice
  public class GlobalExceptionHandler {@ExceptionHandler(ResourceNotFoundException.class)@ResponseStatus(HttpStatus.NOT_FOUND)public ErrorResponse handleNotFound(ResourceNotFoundException ex) {return new ErrorResponse(ex.getMessage(), 404);}
  }
  

---

總結

通過合理使用這些注解，可以顯著簡化Spring Boot開發：

• 依賴管理：@Autowired、@Qualifier、@Primary。
• Web開發：@RestController、@GetMapping、@RequestBody。
• 數據訪問：@Entity、@Transactional。
• 配置管理：@Value、@ConfigurationProperties。
• 測試與擴展：@SpringBootTest、@Scheduled、@Async。

實際開發中，可結合具體場景靈活組合這些注解，例如：

@RestController
@RequestMapping("/api")
@CrossOrigin
public class ProductController {@Autowiredprivate ProductService productService;@GetMapping("/products/{id}")public Product getProduct(@PathVariable Long id, @RequestParam String lang) { ... }@PostMapping("/products")@Transactionalpublic Product createProduct(@RequestBody Product product) { ... }
}