当前位置：首页 > article >正文

Spring Boot框架中常用注解

article 2025/3/29 11:59:42

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