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) { ... }
}