Spring Boot常用注解-详细解析+示例 - 指南

1. @SpringBootApplication

• 详细解析：
  组合注解，包含@Configuration（标记配置类）、@EnableAutoConfiguration（开启自动配置）、@ComponentScan（组件扫描）。启动类标注后，Spring Boot 会自动完成组件扫描、配置类加载和自动配置逻辑。
• 注意事项：
  通常放在项目根包下（如com.example.demo），确保@ComponentScan能扫描到所有子包中的组件。若需自定义扫描范围，可通过scanBasePackages属性指定。
• 示例：

@SpringBootApplication(scanBasePackages = "com.example.service")
public class DemoApplication {
public static void main(String[] args) {
SpringApplication.run(DemoApplication.class, args);
}
}

• 对比：
  与@Configuration的区别：@SpringBootApplication是更高层次的封装，包含自动配置和组件扫描，而@Configuration仅标记配置类。

2. @Controller

• 详细解析：
  标记类为 Spring MVC 控制器，负责接收 HTTP 请求并返回视图（如 JSP、Thymeleaf 模板）或通过@ResponseBody返回数据。
• 注意事项：
  需配合@RequestMapping等注解映射请求路径，单独使用时返回的是视图名称，需依赖视图解析器。
• 示例：

@Controller
@RequestMapping("/pages")
public class PageController {
@GetMapping("/home") // 返回home.html视图
public String home() {
return "home";
}
}

• 对比：
  与@RestController的区别：@RestController = @Controller + @ResponseBody，默认返回数据（如 JSON）而非视图；@Controller需显式添加@ResponseBody才返回数据。

3. @RestController

• 详细解析：
  专为 RESTful API 设计，方法返回值会直接作为 HTTP 响应体（默认序列化为 JSON），无需额外添加@ResponseBody。
• 注意事项：
  无法返回视图（如 HTML 页面），适合纯数据接口开发。
• 示例：

@RestController
@RequestMapping("/api/users")
public class UserApiController {
@GetMapping // 返回JSON数据
public List getUsers() {
return Arrays.asList(new User(1, "Alice"));
}
}

• 对比：
  与@Controller的区别：核心差异在返回值处理（视图 vs 数据）。

4. @RequestMapping

• 详细解析：
  基础请求映射注解，可用于类或方法，支持指定 URL 路径、HTTP 方法（GET/POST 等）、请求参数、请求头、媒体类型等。
• 注意事项：
  Spring 4.3 + 推荐使用更具体的@GetMapping、@PostMapping等注解，避免重复指定method属性。
• 示例：

@RequestMapping(value = "/users", method = RequestMethod.GET, params = "type=admin")
public List getAdminUsers() {
// 仅处理带type=admin参数的GET请求
}

• 对比：
  与@GetMapping等的区别：@RequestMapping是通用注解，需显式指定method；而@GetMapping等是简化版，已固化 HTTP 方法。

5. @GetMapping

• 详细解析：
  @RequestMapping(method = RequestMethod.GET)的快捷注解，专门处理 HTTP GET 请求，用于查询资源。
• 注意事项：
  适合读取数据，幂等（多次请求结果一致）且不应修改资源状态。
• 示例：

@GetMapping("/users/{id}")
public User getUser(@PathVariable Long id) {
return userService.findById(id);
}

• 对比：
  与@PostMapping的区别：@GetMapping用于查询，@PostMapping用于创建资源；@GetMapping参数暴露在 URL 中，@PostMapping参数在请求体中。

6. @PostMapping

• 详细解析：
  @RequestMapping(method = RequestMethod.POST)的快捷注解，用于处理 HTTP POST 请求，适合创建新资源。
• 注意事项：
  非幂等（多次请求可能创建多个资源），参数通常放在请求体中（如 JSON）。
• 示例：

@PostMapping("/users")
public ResponseEntity createUser(@RequestBody User user) {
User saved = userService.save(user);
return ResponseEntity.status(201).body(saved);
}

• 对比：
  与@PutMapping的区别：@PostMapping用于创建资源（URL 通常不包含 ID），@PutMapping用于全量更新（URL 包含 ID）。

7. @PutMapping

• 详细解析：
  处理 HTTP PUT 请求，用于全量更新资源（需提供资源的完整信息）。
• 注意事项：
  幂等（多次请求结果一致），通常要求客户端提交资源的完整数据。
• 示例：

@PutMapping("/users/{id}")
public User updateUser(@PathVariable Long id, @RequestBody User user) {
return userService.update(id, user); // 覆盖整个用户信息
}

• 对比：
  与@PatchMapping的区别：@PutMapping用于全量更新，@PatchMapping用于部分更新（仅提交需要修改的字段）。

8. @DeleteMapping

• 详细解析：
  处理 HTTP DELETE 请求，用于删除资源。
• 注意事项：
  幂等，删除后再次请求应返回 404（资源不存在）。
• 示例：

@DeleteMapping("/users/{id}")
public ResponseEntity deleteUser(@PathVariable Long id) {
userService.delete(id);
return ResponseEntity.noContent().build();
}

9. @PatchMapping

• 详细解析：
  处理 HTTP PATCH 请求，用于部分更新资源（仅修改指定字段）。
• 注意事项：
  非幂等（如递增计数器操作），请求体通常包含部分字段。
• 示例：

@PatchMapping("/users/{id}")
public User updateUserName(@PathVariable Long id, @RequestBody Map updates) {
return userService.updateField(id, "name", updates.get("name"));
}

• 对比：
  与@PutMapping的区别：如上述，核心是部分更新 vs 全量更新。

10. @PathVariable

• 详细解析：
  绑定 URL 路径中的变量到方法参数，支持单个参数或复杂对象（需配合@ModelAttribute）。
• 注意事项：
  若参数名与 URL 占位符不一致，需通过value指定（如@PathVariable("userId") Long id）。
• 示例：

@GetMapping("/users/{userId}/orders/{orderId}")
public Order getOrder(
@PathVariable("userId") Long uId,
@PathVariable Long orderId
) {
return orderService.findByUserAndOrder(uId, orderId);
}

• 对比：
  与@RequestParam的区别：@PathVariable获取 URL 路径中的参数（如/users/1中的 1），@RequestParam获取查询参数（如/users?page=1中的 page）。

11. @RequestParam

• 详细解析：
  绑定 HTTP 请求参数（查询字符串或表单数据）到方法参数，支持设置是否必填、默认值等。
• 注意事项：
  对于非基本类型参数（如自定义对象），需配合@ModelAttribute使用。
• 示例：

@GetMapping("/users")
public List getUsers(
@RequestParam(required = false, defaultValue = "0") int page,
@RequestParam(required = false, defaultValue = "10") int size
) {
return userService.findPage(page, size);
}

• 对比：
  与@RequestBody的区别：@RequestParam处理 URL 查询参数或表单数据，@RequestBody处理请求体中的数据（如 JSON）。

12. @RequestBody

• 详细解析：
  将 HTTP 请求体（如 JSON/XML）转换为方法参数对象，依赖消息转换器（如 Jackson）实现序列化。
• 注意事项：
  仅支持 POST/PUT/PATCH 等包含请求体的方法，GET 请求无请求体，使用会报错。
• 示例：

@PostMapping("/users")
public User createUser(@RequestBody @Valid User user) { // @Valid用于参数校验
return userService.save(user);
}

• 对比：
  与@RequestParam的区别：如上述，核心是请求体 vs 查询参数。

13. @ResponseBody

• 详细解析：
  将方法返回值直接作为 HTTP 响应体（如 JSON），跳过视图解析器。
• 注意事项：
  @RestController已包含此注解，无需重复添加。
• 示例：

@Controller
public class DataController {
@GetMapping("/api/data")
@ResponseBody // 返回JSON而非视图
public Map getData() {
return Collections.singletonMap("key", "value");
}
}

14. @RequestHeader

• 详细解析：
  绑定 HTTP 请求头信息到方法参数，如User-Agent、Content-Type等。
• 注意事项：
  若请求头不存在且未设置默认值，会抛出MissingRequestHeaderException。
• 示例：

@GetMapping("/headers")
public String getHeaders(
@RequestHeader("User-Agent") String userAgent,
@RequestHeader(value = "Accept", defaultValue = "*/*") String accept
) {
return "User-Agent: " + userAgent;
}

15. @CookieValue

• 详细解析：
  绑定请求中的 Cookie 值到方法参数，可获取客户端存储的 Cookie 信息。
• 注意事项：
  若 Cookie 不存在且required = true，会抛出异常。
• 示例：

@GetMapping("/session")
public String getSessionId(@CookieValue("JSESSIONID") String sessionId) {
return "Session ID: " + sessionId;
}

16. @Component

• 详细解析：
  通用组件注解，标记类为 Spring 管理的 Bean，由 Spring 自动扫描并实例化。
• 注意事项：
  是@Service、@Repository、@Controller的父注解，通常优先使用更具体的注解以提高代码可读性。
• 示例：

@Component // 通用组件，如工具类
public class DateUtils {
public String format(Date date) {
return new SimpleDateFormat("yyyy-MM-dd").format(date);
}
}

• 对比：
  与@Service的区别：@Component是通用注解，@Service专为业务逻辑层设计，语义更明确。

17. @Service

• 详细解析：
  继承自@Component，标记类为业务逻辑层组件，Spring 会自动扫描并注入依赖。
• 注意事项：
  事务管理（@Transactional）通常应用于@Service标注的类，确保业务操作的原子性。
• 示例：

@Service
public class UserServiceImpl implements UserService {
private final UserRepository userRepository;
@Autowired
public UserServiceImpl(UserRepository userRepository) {
this.userRepository = userRepository;
}
}

• 对比：
  与@Repository的区别：@Service处理业务逻辑，@Repository处理数据访问；@Repository会自动转换数据库异常为 Spring 统一的DataAccessException。

18. @Repository

• 详细解析：
  继承自@Component，标记类为数据访问层（DAO）组件，负责与数据库交互。
• 注意事项：
  Spring 会为其添加异常转换器，将 JDBC/Hibernate 等原生异常转换为DataAccessException。
• 示例：

@Repository
public class UserRepositoryImpl implements UserRepository {
@Override
public User findById(Long id) {
// 数据库查询逻辑
}
}

19. @Autowired

• 详细解析：
  自动注入 Spring 容器中的 Bean，支持构造函数、字段、setter 方法注入，默认按类型匹配。
• 注意事项：
  • 构造函数注入是推荐方式（便于测试且强制依赖）；
  • 若存在多个同类型 Bean，需配合@Qualifier指定名称；
  • Spring 4.3 + 对单个构造函数的类，可省略@Autowired。
• 示例：

@Service
public class OrderService {
private final UserService userService;
// 构造函数注入（推荐）
@Autowired
public OrderService(UserService userService) {
this.userService = userService;
}
}

• 对比：
  与@Resource的区别：
  • @Autowired默认按类型注入，@Resource默认按名称注入；
  • @Autowired是 Spring 注解，@Resource是 JSR-250 规范注解；
  • @Autowired可配合@Qualifier指定名称，@Resource通过name属性指定。

20. @Qualifier

• 详细解析：
  与@Autowired配合使用，当存在多个同类型 Bean 时，通过名称指定要注入的 Bean。
• 注意事项：
  value属性必须与目标 Bean 的名称一致（默认是类名首字母小写）。
• 示例：

@Service
public class PaymentService {
@Autowired
@Qualifier("alipayProcessor") // 指定注入alipayProcessor
private PaymentProcessor processor;
}
// 两个同类型Bean
@Service("alipayProcessor")
public class AlipayProcessor implements PaymentProcessor { ... }
@Service("wechatProcessor")
public class WechatProcessor implements PaymentProcessor { ... }

21. @Resource

• 详细解析：
  JSR-250 规范注解，用于依赖注入，默认按名称匹配，名称可通过name属性指定，若名称不匹配则按类型匹配。
• 注意事项：
  不支持required属性（默认必须存在，否则报错），需确保容器中存在匹配的 Bean。
• 示例：

@Service
public class CartService {
@Resource(name = "userRepository") // 按名称注入
private UserRepository userRepo;
}

22. @Configuration

• 详细解析：
  标记类为配置类，替代传统 XML 配置文件，内部可通过@Bean定义 Bean。
• 注意事项：
  配置类本身也是 Bean，可被@Autowired注入；@SpringBootApplication已包含此注解。
• 示例：

@Configuration
public class AppConfig {
@Bean // 定义Bean，名称默认是方法名
public RestTemplate restTemplate() {
return new RestTemplate();
}
}

• 对比：
  与@Component的区别：@Configuration用于定义 Bean 配置，@Component用于标记被管理的组件；@Configuration中的@Bean方法会被 CGLIB 代理，确保单例性。

23. @Bean

• 详细解析：
  用于@Configuration类中，定义一个 Bean，Spring 会将方法返回值纳入容器管理。
• 注意事项：
  • 默认 Bean 名称是方法名，可通过name属性指定；
  • 支持initMethod和destroyMethod指定初始化和销毁方法。
• 示例：

@Configuration
public class DatabaseConfig {
@Bean(name = "dataSource", destroyMethod = "close")
public DataSource dataSource() {
HikariConfig config = new HikariConfig();
// 配置数据源
return new HikariDataSource(config);
}
}

24. @Value

• 详细解析：
  注入外部配置值（如application.properties中的属性）到字段或方法参数，支持 SpEL 表达式。
• 注意事项：
  对于复杂配置，推荐使用@ConfigurationProperties而非多个@Value。
• 示例：

@Component
public class AppProperties {
@Value("${app.name}") // 注入application.properties中的app.name
private String appName;
@Value("#{T(java.lang.Math).random() * 100}") // SpEL表达式
private double randomValue;
}

• 对比：
  与@ConfigurationProperties的区别：
  • @Value适合单个属性注入，@ConfigurationProperties适合批量绑定（如前缀相同的属性）；
  • @ConfigurationProperties支持类型转换和校验，@Value需手动处理。

25. @ConfigurationProperties

• 详细解析：
  将外部配置（如application.yml）批量绑定到 Bean 的字段，通常配合prefix指定属性前缀。
• 注意事项：
  需要添加@Component或在@Configuration类中通过@EnableConfigurationProperties启用。
• 示例：

# application.yml
app:
name: MyApp
version: 1.0.0
server:
port: 8080

@Component
@ConfigurationProperties(prefix = "app")
public class AppConfig {
private String name;
private String version;
private ServerConfig server; // 嵌套对象
// getter/setter
public static class ServerConfig {
private int port;
// getter/setter
}
}

26. @Transactional

• 详细解析：
  声明事务管理，确保方法内的操作要么全部成功，要么全部回滚，支持设置隔离级别、传播行为等。
• 注意事项：
  • 仅对public方法有效；
  • 自调用（同一类中方法调用）不会触发事务，需通过 AOP 代理调用；
  • 默认只回滚RuntimeException及其子类。
• 示例：

@Service
public class OrderService {
@Transactional(isolation = Isolation.READ_COMMITTED, rollbackFor = Exception.class)
public void createOrder(Order order) {
// 数据库操作1
// 数据库操作2
}
}

27. @CrossOrigin

• 详细解析：
  解决跨域请求问题，允许指定来源、方法、 headers 等跨域参数。
• 注意事项：
  可用于类或方法，方法级注解会覆盖类级注解；生产环境需限制origins避免安全风险。
• 示例：

@RestController
@CrossOrigin(origins = "https://example.com", methods = {GET, POST})
public class ApiController {
@GetMapping("/data")
public String getData() {
return "cross-origin data";
}
}

28. @Validated

• 详细解析：
  开启方法参数校验（基于 JSR-303/JSR-380 规范），配合@Valid使用，支持分组校验。
• 注意事项：
  需添加依赖（如spring-boot-starter-validation），校验失败会抛出MethodArgumentNotValidException。
• 示例：

@RestController
@Validated // 类级别开启校验
public class UserController {
@PostMapping("/users")
public User createUser(@Valid @RequestBody User user) { // @Valid触发校验
return userService.save(user);
}
}
// 实体类
public class User {
@NotNull(message = "ID不能为空")
private Long id;
@Size(min = 2, max = 20, message = "姓名长度必须在2-20之间")
private String name;
}

29. @Profile

• 详细解析：
  标记 Bean 或配置类仅在特定环境（如 dev/test/prod）下生效，通过spring.profiles.active指定激活的环境。
• 注意事项：
  可指定多个环境（如@Profile({"dev", "test"})），!dev表示排除 dev 环境。
• 示例：

@Configuration
public class DataSourceConfig {
@Bean
@Profile("dev") // 仅dev环境生效
public DataSource devDataSource() {
// 开发环境数据源
}
@Bean
@Profile("prod") // 仅prod环境生效
public DataSource prodDataSource() {
// 生产环境数据源
}
}

30. @Conditional

• 详细解析：
  基于条件判断是否创建 Bean，需配合条件类（实现Condition接口）使用，Spring Boot 提供了多种派生注解（如@ConditionalOnClass、@ConditionalOnMissingBean）。
• 注意事项：
  条件判断在 Bean 创建前执行，常用于自动配置逻辑。
• 示例：

@Configuration
public class RedisConfig {
@Bean
@ConditionalOnClass(RedisTemplate.class) // 当RedisTemplate类存在时创建Bean
@ConditionalOnMissingBean // 当容器中不存在该类型Bean时创建
public RedisTemplate redisTemplate() {
return new RedisTemplate<>();
}
}