【Spring】常用注解分类整理

Spring常用注解分类整理

一、核心容器注解

1. 组件标识类

注解	作用	应用场景
@Component	通用组件标识，将类注册为Spring Bean	工具类、通用服务类
@Service	业务逻辑层组件（语义化）	Service层，如UserService
@Repository	数据访问层组件，自动转换持久层异常	DAO层、MyBatis Mapper接口
@Controller	Web控制器组件（返回视图）	MVC架构的Controller层
@RestController	@Controller + @ResponseBody组合（返回JSON）	RESTful API接口层

示例：

@RestController
@RequestMapping("/api/users")
public class UserController {
    @Autowired
    private UserService userService;
}

2. 依赖注入类

注解	作用	应用场景
@Autowired	按类型自动装配（Spring核心注解）	构造函数、字段、Setter注入
@Qualifier	指定Bean名称，解决同一类型多个Bean冲突	配合@Autowired精准匹配
@Resource	按名称自动装配（JDK标准注解）	需要与Spring解耦的场景
@Value	注入配置文件中的值或SpEL表达式	注入application.yml中的配置项

示例：

@Service
public class OrderService {
    // 推荐：构造函数注入（无需@Autowired）
    private final UserService userService;
    
    public OrderService(UserService userService) {
        this.userService = userService;
    }
    
    @Value("${app.max-order-limit}")
    private Integer maxOrderLimit;
}

3. Bean作用域与生命周期

注解	作用	应用场景
@Scope	指定Bean作用域（singleton/prototype/request/session）	每次请求需要新实例时（如多线程环境）
@PostConstruct	Bean属性设置后执行初始化方法	缓存预热、连接池初始化
@PreDestroy	Bean销毁前执行清理方法	资源释放、线程池关闭
@Lazy	延迟初始化Bean	优化启动速度、大对象按需加载

---

二、Web层注解（Spring MVC）

1. 请求映射

注解	作用	应用场景
@RequestMapping	通用请求路径映射（支持GET/POST等）	类或方法级别路由定义
@GetMapping	GET请求快捷注解	查询接口（如/api/users/{id}）
@PostMapping	POST请求快捷注解	创建资源接口
@PutMapping	PUT请求快捷注解	全量更新接口
@PatchMapping	PATCH请求快捷注解	部分更新接口
@DeleteMapping	DELETE请求快捷注解	删除资源接口

2. 参数处理

注解	作用	应用场景
@RequestParam	获取URL查询参数或表单参数	?page=1&size=10分页参数
@PathVariable	获取URL路径变量	REST风格/users/{userId}
@RequestBody	将请求体JSON转为Java对象	POST/PUT请求接收复杂对象
@ResponseBody	将返回值转为JSON响应（@RestController已包含）	需要返回JSON而非视图时
@RequestHeader	获取请求头信息	获取Authorization、Trace-Id
@CookieValue	获取Cookie值	读取会话Cookie

示例：

@GetMapping("/{id}")
public ResponseEntity<UserDTO> getUser(
    @PathVariable Long id,
    @RequestParam(defaultValue = "false") boolean includeDetails) {
    return ResponseEntity.ok(userService.getUser(id, includeDetails));
}

3. 响应与异常

注解	作用	应用场景
@ResponseStatus	指定HTTP响应状态码	创建资源返回201，无内容返回204
@ExceptionHandler	局部异常处理方法	单个Controller内异常处理
@ControllerAdvice	全局异常处理类	统一处理所有Controller异常
@RestControllerAdvice	@ControllerAdvice + @ResponseBody	全局异常返回JSON

---

三、数据访问与事务注解

1. JPA/Hibernate

注解	作用	应用场景
@Entity	标识JPA实体类	数据库表映射对象
@Table	指定实体对应的表名	自定义表名、schema
@Id	标识主键字段	实体主键
@GeneratedValue	主键生成策略	自增ID、UUID
@Column	字段映射配置	列名、长度、非空约束

2. MyBatis

注解	作用	应用场景
@Mapper	标识MyBatis Mapper接口	DAO接口（替代XML配置）
@Select/Insert/Update/Delete	直接写SQL语句	简单SQL场景

3. 事务管理

注解	作用	应用场景
@Transactional	声明式事务管理	Service层方法，确保数据一致性
@EnableTransactionManagement	启用事务管理功能	主配置类上开启事务支持

事务传播行为 （@Transactional(propagation = ...)）：

• REQUIRED：默认，需要事务（无则创建，有则加入）
• REQUIRES_NEW：总是创建新事务
• NESTED：嵌套事务（需数据库支持）

---

四、AOP注解

注解	作用	应用场景
@Aspect	标识切面类	日志、权限、性能监控等横切关注点
@Pointcut	定义切点表达式	复用切点定义
@Before	前置通知	权限校验、参数验证
@After	后置通知（finally块）	资源释放
@AfterReturning	返回后通知	日志记录、结果处理
@AfterThrowing	抛出异常后通知	异常日志、告警
@Around	环绕通知（功能最强大）	性能统计、事务管理、缓存

示例：

@Aspect
@Component
public class LoggingAspect {
    @Around("@within(org.springframework.web.bind.annotation.RestController)")
    public Object logAround(ProceedingJoinPoint joinPoint) throws Throwable {
        long start = System.currentTimeMillis();
        try {
            return joinPoint.proceed();
        } finally {
            log.info("执行时间: {}ms", System.currentTimeMillis() - start);
        }
    }
}

---

五、配置与条件注解

1. 配置类

注解	作用	应用场景
@Configuration	标识配置类（替代XML配置）	第三方Bean注册、复杂配置
@Bean	注册第三方库Bean	如RestTemplate、DataSource
@Import	导入其他配置类	模块化配置拆分
@PropertySource	加载外部properties文件	自定义配置文件
@ConfigurationProperties	批量绑定配置文件到Bean	配置项分组管理

2. 条件注解

注解	作用	应用场景
@Conditional	条件化注册Bean	自定义条件逻辑
@ConditionalOnClass	类路径存在某类时注册	自动配置（如存在DataSource类）
@ConditionalOnMissingBean	缺失某Bean时注册	提供默认实现，可被覆盖
@ConditionalOnProperty	配置项匹配时注册	功能开关（如app.feature.xxx.enabled=true）

---

六、异步与调度注解

注解	作用	应用场景
@Async	异步执行方法	不影响主流程的操作（如发邮件、日志）
@EnableAsync	启用异步功能	主配置类
@Scheduled	定时任务（cron/fixedDelay/fixedRate）	定时数据同步、清理任务
@EnableScheduling	启用定时任务	主配置类

示例：

@Async("taskExecutor")
public CompletableFuture<String> sendEmailAsync(String to) {
    // 异步发送邮件
}

@Scheduled(cron = "0 0 3 * * ?") // 每天凌晨3点执行
public void cleanExpiredData() {
    // 清理过期数据
}

---

七、缓存注解

注解	作用	应用场景
@Cacheable	缓存查询结果	低频变更的数据（如字典、配置）
@CachePut	更新缓存（不影响方法执行）	数据更新时同步缓存
@CacheEvict	删除缓存	数据删除时清除缓存
@Caching	组合多个缓存操作	复杂缓存逻辑
@EnableCaching	启用缓存功能	主配置类

示例：

@Cacheable(value = "users", key = "#id")
public User getUser(Long id) {
    return userMapper.selectById(id);
}

@CacheEvict(value = "users", key = "#id")
public void deleteUser(Long id) {
    userMapper.deleteById(id);
}

---

八、测试相关注解

注解	作用	应用场景
@SpringBootTest	启动完整Spring容器进行集成测试	全流程功能测试
@WebMvcTest	仅测试MVC层（轻量级）	Controller层单元测试
@MockBean	创建Mock对象注入容器	隔离外部依赖
@DataJpaTest	仅测试JPA数据访问层	Repository层测试

---

九、总结与选型建议

高频组合

1. REST API ：@RestController + @RequestMapping + @GetMapping/PostMapping
2. 分层架构 ：@Controller → @Service → @Repository
3. 依赖注入 ：构造函数 + @Autowired（或无需注解）
4. 事务控制 ：@Service + @Transactional
5. 配置管理 ：@ConfigurationProperties + @Configuration

最佳实践

• 构造函数注入：优先于字段注入，可测试性更好
• @Qualifier：解决同一类型多个Bean冲突
• @RestControllerAdvice ：统一异常处理和响应封装
• @ConditionalOnProperty：实现功能开关和灰度发布
• @Async + @Transactional：异步方法无法传递事务上下文

通过合理使用这些注解，可以实现声明式编程，大幅减少样板代码，提升开发效率。