先说结论
Spring Boot 的注解看着多,底层机制其实只有四种:组件声明、依赖注入、条件装配、功能开关。组件声明类被 @ComponentScan 扫描注册;依赖注入类解决"从容器拿对象";条件装配类全部基于 @Conditional SPI;功能开关类(@EnableXxx)几乎全部是 @Import 的语法糖。按这四类记忆,注解就不再零散——遇到不认识的注解,先归类,再想它背后的机制,大多数问题不需要查文档就能推断出行为。反过来也成立:一个注解"加了没反应",先确认它的归类——声明类没反应多半是没被扫描到,注入类没反应多半是类型或名字没匹配上,条件类没反应去查条件评估报告,开关类没反应先查 @EnableXxx 是否真的被装配。归类对了,排查路径就唯一了。
四类注解速查
1. 组件声明类
@Component / @Service / @Repository / @Controller / @Configuration,语义不同,机制相同:被 @ComponentScan 扫描后注册成 BeanDefinition。@ComponentScan 的常用属性也值得认识:basePackages 指定扫描根、includeFilters/excludeFilters 做过滤、lazyInit 把扫描出的 Bean 全部改成懒加载。多模块项目里主类放根包 + 默认扫描是最稳的配置;确需多根扫描时显式列包名,比依赖"碰巧能扫到"的隐式行为可靠。@Configuration 特殊一点,会被 CGLIB 增强(proxyBeanMethods 默认 true),保证类内 @Bean 方法互调时拿到的还是容器里的单例。Spring Boot 2.2 起可用 @Configuration(proxyBeanMethods = false) 关掉代理换启动速度,前提是配置类内没有 @Bean 方法互调——有互调却关了代理,方法间拿到的就是 new 出来的新对象,单例语义被破坏。
2. 依赖注入类
@Autowired:按类型注入,多个候选时配合@Qualifier按名字筛选;找不到会启动报错,required = false可放宽;@Resource:JDK 标准注解,先按名字找,找不到再按类型;@Value:注入单个配置项,支持占位符与 SpEL;@ConfigurationProperties:把一组配置批量绑定到 POJO,支持松散绑定(app-key映射appKey)和 JSR303 校验,配置中心的动态刷新对它天然生效。
@Component
@ConfigurationProperties(prefix = "biz.sms")
@Validated
public class SmsProperties {
@NotBlank
private String appKey; // 对应配置 biz.sms.app-key,启动时为空直接失败
private int timeoutMs = 3000;
// getter / setter 必须齐全:重绑定与松散绑定都靠 setter 写入
}
注入类注解怎么选,看这张表:
| 注解 | 匹配规则 | 支持动态刷新 | 典型场景 |
|---|---|---|---|
| @Autowired | 先按类型,多候选时按 @Qualifier / 字段名筛选 | 否(创建时一次性注入) | 注入自家 Bean 的默认选择 |
| @Resource | 先按名字,找不到再按类型 | 否 | 同一类型多个实现时按名指定 |
| @Value | 占位符 / SpEL 单值注入 | 需配 @RefreshScope | 零散的开关、阈值类配置 |
| @ConfigurationProperties | 前缀批量绑定 POJO + 校验 | 是(rebinder 重新绑定) | 一组结构化配置,配配置中心最佳 |
表里"支持动态刷新"一列是配置中心场景的分水岭:刷新能力属于 @ConfigurationProperties 的 rebinder 机制而不是注解本身,@Value 要享受同样的能力,必须借助 @RefreshScope 的销毁重建来间接实现——机制细节见配置中心那篇的链路拆解。
3. 条件装配类
@Conditional 是根接口,衍生出 @ConditionalOnClass、@ConditionalOnMissingBean、@ConditionalOnProperty 等,是自动装配的筛子,自定义 starter 时最常用。理解它的关键是"条件在 BeanDefinition 注册阶段评估"——评估不通过,Bean 连创建的资格都没有,这与运行期的 if 判断完全是两个层面的事。
它也支持自定义:实现 Condition 接口,在 matches() 里拿到 ConditionContext(类路径、BeanFactory、Environment)与 AnnotatedTypeMetadata(注解属性),返回布尔值即可。团队内固定的装配策略——比如"测试环境自动装配 mock 实现、生产装配真实实现"——做成自定义条件注解,比散落各处的环境 if-else 干净得多,也更容易统一收口。
4. 功能开关类(@EnableXxx)
@EnableScheduling、@EnableAsync、@EnableFeignClients、@EnableCaching……点进去看源码,模式统一:@Import 一个 ImportSelector 或配置类,往容器里注册关键的 BeanPostProcessor / 扫描器。例如 @EnableFeignClients 注册 FeignClientsRegistrar 扫描 @FeignClient 接口;@EnableAsync 注册 AsyncAnnotationBeanPostProcessor 让 @Async 生效。理解了这一个模式,所有 @EnableXxx 都能自己看懂——这也是"注解只是语法糖"的最好注脚。顺带一个实用技巧:怀疑某个功能"开关没开"时,第一件事是确认 @EnableXxx 标注的类是否真的被扫描装配到——开关注解标在一个没被引用、也不在扫描范围内的类上,等于没标:
// @EnableAsync 的真实面目:一个 @Import,没有任何魔法
@Target(ElementType.TYPE)
@Retention(RetentionPolicy.RUNTIME)
@Import(AsyncConfigurationSelector.class) // 真正的注册逻辑全在 ImportSelector 里
public @interface EnableAsync { /* ... */ }
这类注解还有一个隐蔽特性:多数 @EnableXxx 内部带 @Conditional 逻辑,开启后如果关键设施不存在(比如 @EnableCaching 没有缓存管理器),开关可能静默不工作——排查顺序是先确认开关注解被装配,再确认开关注册的关键 Bean 存在。
Web 层高频注解
@RestController
@RequestMapping("/orders")
public class OrderController {
@GetMapping("/{id}")
public Order detail(@PathVariable Long id) { /* 路径参数:/orders/123 */ }
@PostMapping
public Order create(@RequestBody @Validated OrderReq req) {
// @RequestBody:JSON 反序列化;@Validated:JSR303 校验,失败抛 MethodArgumentNotValidException
/* ... */
}
}
配合 @ControllerAdvice + @ExceptionHandler 做全局异常处理:@ExceptionHandler 按异常类型路由,@ControllerAdvice 指定作用的包范围,返回体统一收敛成业务错误码——参数校验失败(MethodArgumentNotValidException)单独处理,把校验消息翻译成对调用方可读的提示,而不是把堆栈直接甩出去。注意 @RequestParam 取 query/form 参数、@PathVariable 取路径段、@RequestBody 取请求体,三者混用错位是 400 错误的常见来源——请求体用了 @RequestParam 接、路径参数用 @RequestBody 接,Spring 的报错信息往往只提示参数缺失,定位时先核对三个注解与参数来源是否匹配。
两个易错点
@Transactional、@Async这类"运行期增强"注解都依赖代理:@Async方法必须 public 且经代理调用,返回值要用Future/CompletableFuture接,否则异步不生效。同类内部this.asyncMethod()自调用是高频翻车点,行为是"注解静默失效、代码同步执行",测试环境流量小根本看不出来:
// 错误写法:this 调用绕过代理,@Async 静默失效,实际同步执行
@Service
public class CouponService {
public void grant() { this.sendCoupon(); } // 没有异步发生
@Async
public void sendCoupon() { /* ... */ }
}
// 正确写法:拆 Bean 或注入自身代理,让调用走代理对象
@Service
public class CouponService {
@Autowired @Lazy
private CouponService self;
public void grant() { self.sendCoupon(); } // 经代理调用,异步生效
}
@ConfigurationProperties的 Bean 可以直接标@Component,但在 starter 场景更推荐@EnableConfigurationProperties(XxxProperties.class)显式注册,避免依赖包扫描路径——starter 的配置类不该依赖消费方的扫描范围,这一点与自动配置类的位置原则一脉相承。另外,属性绑定是"创建 + setter 写入"两步,setter 缺失不会报错但字段静默为 null;@ConstructorBinding的构造器绑定是另一条路,适合不可变配置类,两种方式二选一,混用会出现一部分字段绑定、一部分不绑定的诡异状态。
一句话收尾:声明、注入、条件、开关——四类机制记牢,几十个注解都是排列组合。
生产案例
一次大促前的发券链路改造,团队把同步发券改成 @Async 异步执行以压缩接口耗时。上线前压测发现接口 RT 纹丝不动,顺着这条异常排查:@Async 方法确实标了注解,也开了 @EnableAsync,但调用方在本类内部用 this.sendCoupon() 触发——代理被绕过,所谓异步从未发生,所有发券一直在主线程同步执行。如果没有这次压测,问题会以"大促当晚发券接口把主线程池打满"的形式出现。修复用拆 Bean 方案:发券动作挪进独立的 CouponIssuer,由原服务注入调用。这次事件让团队形成了两个固定动作:一是任何代理类注解(事务/异步/缓存)落地时都验证一次调用路径是否经过代理;二是性能改造必须伴随改造前后的压测对比,靠"应该会更快"上线的方案一律驳回。
检查清单
- 能把项目里用到的注解按"声明、注入、条件、开关"四类归类
- 配置类内的 @Bean 方法存在互调时,没有关闭 proxyBeanMethods
- 注入同一类型的多个实现时,明确用的是 @Qualifier 还是 @Resource 按名匹配
- @Async 方法是 public、经代理调用、返回值用 Future / CompletableFuture 接收
- starter 场景的 Properties 用 @EnableConfigurationProperties 显式注册
- Web 参数注解与来源对齐:@RequestParam 对 query/form、@PathVariable 对路径段、@RequestBody 对请求体
- 代理类注解(事务/异步/缓存)落地时验证过调用路径经过代理对象