先说结论

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 的报错信息往往只提示参数缺失,定位时先核对三个注解与参数来源是否匹配。

两个易错点

  1. @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(); } // 经代理调用,异步生效
}
  1. @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 对请求体
  • 代理类注解(事务/异步/缓存)落地时验证过调用路径经过代理对象