Spring Boot框架中常用注解

以下是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 {
      @Bean
      public DataSource dataSource() {
          return new HikariDataSource();
      }
  }

3. @Bean

• 用途：在配置类中定义Bean实例，交给Spring容器管理。

• 位置 ：方法级别。

• 示例 ：

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

---

二、依赖注入（DI）注解

1. @Autowired

• 用途：自动注入Bean，支持字段、构造器、方法注入。

• 位置 ：字段、构造器、方法参数。

• 示例 ：

  @Service
  public class UserService {
      @Autowired
      private UserRepository userRepository; // 字段注入
  }
  
  // 构造器注入（推荐）
  @Service
  public class OrderService {
      private final PaymentService paymentService;
  
      @Autowired
      public 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 {
      @Transactional
      public 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/mydb
    username: root
    password: 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 {
      @Autowired
      private UserService userService;
  }

2. @MockBean

• 用途：在测试中模拟Bean（结合Mockito）。

• 示例 ：

  @SpringBootTest
  class PaymentServiceTest {
      @MockBean
      private PaymentGateway paymentGateway;
  
      @Test
      void 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 {
    @Autowired
    private ProductService productService;

    @GetMapping("/products/{id}")
    public Product getProduct(@PathVariable Long id, @RequestParam String lang) { ... }

    @PostMapping("/products")
    @Transactional
    public Product createProduct(@RequestBody Product product) { ... }
}