1. 学注解之前先把容器和扫描机制想明白1.1 注解不是魔法它只是一张贴着元数据的标签很多新手学 spring 的时候第一反应就是背注解Component加在类上Autowired加在字段上Configuration加在配置类上……背得滚瓜烂熟但真正遇到问题照样抓瞎。我带过不少刚从学校出来的同事最常见的情况是注解能写出来但被问到这个注解为什么生效它在哪个环节被读到的就答不上来。这里先说一个我非常想强调的结论注解本身不干活它只是一段元数据。元数据的意思就是描述数据的数据。你可以把注解想象成贴在行李上的托运标签——标签上写了航班号、目的地、重量但真正把行李送上飞机的是地勤人员标签只是给地勤看的说明。Java 里的注解也一样Transactional不会自己开启事务Autowired不会自己把依赖塞进来它们只是把我想怎么做的信息贴在类上、方法上、字段上然后由 Spring 框架里对应的处理器比如BeanPostProcessor、EventListener这样的组件来读取并执行。这个理解为什么重要因为当你以后遇到注解没生效的时候第一反应就不会是注解是不是写错了而是会去想这个注解被谁处理了我的类有没有被容器扫描到处理器有没有被触发顺着这个思路排查通常两分钟就能定位问题而不是对着配置干瞪眼。1.2 IoC 容器、组件扫描与 BeanPostProcessor注解生效的三块地基要让注解真正产生作用需要同时满足三个前提条件缺一个都不行。第一容器要启动。Spring 里的 IoC 容器负责创建对象、维护依赖关系。无论是用AnnotationConfigApplicationContext还是 Spring Boot 的自动装配本质上都是先启动一个容器让容器有机会看到你的类。第二类要被组件扫描发现。ComponentScan告诉容器去哪些包下面找带有Component、Service、Controller、Repository、Configuration等注解的类把它们注册成 Bean。如果你把带注解的类放在扫描路径之外容器根本不知道它的存在后续一切处理都无从谈起。第三对应的注解处理器要起作用。Spring 容器在创建 Bean 的过程中会穿插调用各种BeanPostProcessor。举个例子AutowiredAnnotationBeanPostProcessor就是专门扫描Autowired、Value这类注解的处理器它会在 Bean 实例化之后、初始化前后把被标注的字段和方法注入进去。Transactional则由另一个处理链路——BeanFactoryTransactionAttributeSourceAdvisor配合TransactionInterceptor来解析和增强。这三块地基要是脑子里没有写再多注解也没用。我见过一个新人把Service加在了一个通过new直接创建对象的类上然后问我为什么自动注入进去的 Mapper 是null。其实答案很简单new出来的对象根本不归容器管容器连这个对象的出生都不知道自然没有处理器去给它做任何后处理。1.3 为什么 Spring 会从 XML 配置走向注解有经验的开发者可能还记得早期 Spring 是用 XML 配置 Bean 的一个稍微大点的项目applicationContext.xml 能写几百行。XML 的好处是配置和代码分离坏处也很明显——你要看一个类注入了哪些依赖得跑去 XML 里搜半天改一个 Bean 名字可能牵连十几处引用。注解的出现本质上把配置信息放到了离使用点最近的地方这就是就近原则。你打开一个 Service 类直接就能看到它注入了哪些依赖、事务怎么配置、作用域是什么可读性大幅提升。不过这并不意味着注解是银弹。注解把配置写死在源码里想在不改代码的前提下调整配置就很不方便所以后来又出现了Profile、Conditional这类条件注解以及把配置外置到 properties/yaml 文件的方案。用一句话总结注解解决的是配置和代码分离太远的问题代价是牺牲了一部分运行时动态调整的能力。这个权衡关系新手一开始就要有概念后面理解为什么会有那么多EnableXxx拓展开关才不费劲。2. 按功能拆一张注解地图七大类别与设计逻辑2.1 组件注册Component家族是 Bean 的入场券Spring 手册里最基础的一组注解就是把一个普通类变成容器管理的 Bean。Component是通用组件Service标注业务层Repository标注数据访问层Controller标注控制层。很多人以为它们只是语义不同其实在 Spring 的扫描逻辑里这四者是等价的都用同一个ClassPathScanningCandidateComponentProvider去识别。只不过 Spring 会额外为Repository做一些翻译比如把持久层异常翻译成 Spring 的DataAccessException为Controller关联 Web 层的映射处理。所以新手不用纠结我这个类该用Service还是Component。从功能上讲都一样但从团队协作的语义约定来说建议按分层分别使用这样代码阅读者扫一眼就能知道这个类属于哪一层。类似的思路还有Configuration它其实也被Component元标注过所以能参与组件扫描。这里稍微提一嘴元注解的概念Service上面标着Component说明Service是一个被Component修饰过的注解。Spring 在处理的时候会自动把带有Service的类理解为带有Component的类。理解这个机制你以后看SpringBootApplication这类复合注解时才不会懵。2.2 依赖注入Autowired、Resource、Value、Qualifier第二类是依赖注入注解解决的是这个 Bean 需要哪些合作者的问题。Autowired按类型注入Resource优先按名称注入Value负责把配置文件里的值或者 SpEL 表达式的结果注入进来Qualifier通常和Autowired配合用于指定具体 bean 名称。这类注解背后的设计逻辑也很清晰Bean 之间总是有依赖的如果都靠手动new来组装类与类之间就写死了难以替换和测试。容器负责把依赖关系梳理出来在创建每个 Bean 的过程中把合作者塞进对应位置这就是控制反转IoC落地到代码层面的具体表现。2.3 配置类与 Bean 声明Configuration、Bean、ImportConfiguration标记一个类为配置类类里面的Bean方法用于显式声明 Bean。当你需要注册一个第三方库的对象或者组件扫描覆盖不了的对象的时就用这组注解。Import则可以按类或者按ImportSelector批量导入是很多框架自动装配的底层入口。这里要特别记住一个细节Configuration类本身也是一个 Bean它默认是 full 模式Spring 会用 CGLIB 对这个类做代理确保你调用另一个Bean方法时拿到的还是同一个实例。如果你在普通类上只用了Beanlite 模式那每次调用Bean方法都可能 new 出新的对象这往往是单例失效类 bug 的隐藏源头。后面我会专门展开讲。2.4 生命周期与作用域Scope、Lazy、PostConstruct、PreDestroyScope决定 Bean 是单例还是每次新建prototype还可以扩展 request、session 等 Web 作用域。Lazy让 Bean 延迟到第一次使用时再初始化可用来打断初始化链条上的死结。PostConstruct和PreDestroy则让你在 Bean 初始化完成后、销毁之前插入自定义逻辑属于 JSR-250 的标准注解Spring 也原生支持。这类注解回答的是Bean 什么时候创建、存活多长时间、创建前后做什么的问题。它们最容易出问题的场景就是一个prototype类型的 Bean 被注入到一个单例 Bean 里面然后你发现拿到的对象永远是同一个。这涉及 Spring 对作用域的处理边界新手遇到时不要慌后面我会讲怎么用代理模式解决。2.5 运行条件与配置项Conditional、Profile、PropertySourceConditional是 Spring 4 引入的条件化装配注解后面 Spring Boot 的ConditionalOnClass等一大批注解都是在它之上扩展的。Profile可以按环境dev/test/prod决定哪些 Bean 生效适合处理不同环境使用不同实现的需求。PropertySource则用于加载额外的配置文件。这一类的设计思路是把要不要创建这个 Bean的决策从代码里抽出来让容器在运行期根据条件来判断。对整个框架生态来说它是最有想象力的部分——Spring Boot 的自动配置之所以能那么聪明就是靠这种条件判断一层层叠加出来的。2.6 Web 层注解RestController、RequestMapping、PathVariable、RequestBody这一类是每个做接口开发的人每天都在用的。RestController是Controller和ResponseBody的组合声明该类是一个返回 JSON 数据的控制器。RequestMapping及其简化写法GetMapping、PostMapping等负责把 HTTP 请求映射到具体方法。PathVariable、RequestParam、RequestBody分别用来取出路径参数、查询参数、请求体内容。它们的底层逻辑是通过RequestMappingHandlerMapping在容器启动时建立URL HTTP 方法 → 处理方法的映射关系。理解了这一点你就知道为什么一个 Contorller 方法上的路径不能重复也就能理解 404 排查的切入点。2.7 AOP 与事务Aspect、Transactional、EnableTransactionManagementTransactional声明式事务注解Aspect、Around、Before、After等是面向切面编程的注解EnableTransactionManagement用来开启注解事务管理。Spring Boot 中事务管理默认是开启的但你在原生 Spring 项目中还是需要显式加这个开关。这组注解的核心思想是横切关注点事务、日志、权限校验这类逻辑会散落在各个业务方法里AOP 把它们统一收口通过代理模式在方法执行前后插入通用处理。注解在这里就是切点表达式的一部分告诉框架哪些方法需要被增强、增强逻辑是什么。上面这七大分类并不是 Spring 官方文档里的标准分法而是我自己学的时候为了便于记忆梳理的。好处是遇到任何一个新注解你可以先问自己它属于哪一类然后立刻能想起来 Spring 在哪个环节处理它学习效率会明显高很多。3. 高频注解逐个过用法、陷阱和实战示例3.1Autowired与Resource类型注入和名称注入的取舍你说Autowired和Resource有什么区别很多面试题会问但真正写代码的时候新手很少亲自踩进去。简单版本是这样的Autowired是 Spring 提供默认按类型注入Resource是 JSR-250 标准默认按名称注入。当你只有一个实现类的时候两者写法都能跑通可一旦一个接口有两个实现类Autowired就会抛出NoUniqueBeanDefinitionException这时候你需要在注入点补一个Qualifier(xxx)指明你要哪个。我建议新手默认用构造器注入而不是字段注入。为什么字段注入写起来是爽但有个问题依赖关系写得不明显而且不方便做不可变设计。构造器注入则强制你在创建对象时把所有依赖一次性给齐后续做单元测试也方便——可以直接手动构造对象传入 mock。写法如下Service public class OrderService { private final OrderRepository orderRepository; public OrderService(OrderRepository orderRepository) { this.orderRepository orderRepository; } }如果你用的是 Spring 4.3 以上版本一个类只有一个构造函数时Autowired可以省略Spring 会直接使用那个构造函数。这套写法配合 Lombok 的RequiredArgsConstructor更是清爽。注意Resource是 JDK 扩展包里的标准注解Spring 支持它但在构造器注入场景下我们通常只谈Autowired。3.2Value的两种写法${}与#{}Value看起来简单其实水不浅。${...}是从配置源读取占位符这里的配置源包括 application.properties、application.yml、环境变量等#{...}则是 SpEL 表达式可以做运算和调用方法。举个例子Component public class AppConfig { // 从配置文件读取key 不存在则使用默认值 Value(${app.name:myApp}) private String appName; // SpEL 表达式调用系统方法得到结果 Value(#{systemProperties[user.home]}) private String userHome; // 占位符和表达式也可以混合 Value(#{${app.pool.size:10} * 2}) private int poolSize; }新手最容易犯的错是分不清什么时候用$什么时候用#。简单记想读配置文件就用${}想写表达式就算#{}。还有一类很隐蔽的问题Value注入到静态字段是没用的因为 Spring 的注入发生在实例化阶段而静态字段属于类不属于对象。如果你确实要把配置值放到静态变量里标准做法是先注入到实例字段再在PostConstruct方法里赋给静态字段而不是直接在静态字段上写Value。如果你有十几二十个配置项要注入别写一堆Value改成ConfigurationProperties(prefix xxx)绑定到一个 POJO 上更优雅类型安全也更好。3.3Transactional加在哪个位置为什么有时无效Transactional是业务开发里出镜率最高的注解之一也是最容易栽跟头的。先说最简单的正确姿势只加在public方法上类级别也可以但别加在private方法上——private方法根本不会被代理处理。另外方法被外部调用时事务才会经过代理对象如果是同类内部this.xxx()自调用事务是不生效的。为什么会这样因为 Spring 声明式事务依赖 AOP 代理。你调用的是容器返回的代理对象代理对象会在真正方法执行前开启事务、方法抛异常时回滚。可同类内部调用走的是this也就是原始对象事务拦截器压根没有机会介入。解决办法有三个把这个方法拆到另一个 Bean 里调用或者在类里注入自身代理或者开启exposeProxy后使用AopContext.currentProxy()强制走代理。第一个方案最干净我实践中也最推荐。再来说回滚行为Transactional默认只在抛出RuntimeException或Error时才回滚如果你在方法里 throw 了一个IOException这种受检异常事务会照常提交。要让受检异常触发回滚必须显式加rollbackFor Exception.class。这算得上面试高频考点也是实际生产里一个很经典的隐藏 bug。Transactional(rollbackFor Exception.class) public void createOrder(OrderDTO dto) throws IOException { orderDao.insert(dto); // 模拟远程调用失败抛出一个受检异常 throw new IOException(remote call failed); }3.4Configuration与Beanfull 模式与 lite 模式用纯 Java 配置类替换 XML 配置是现代 Spring 项目的主流。Configuration类里面写了若干个Bean方法这样声明的好处是类型安全IDE 跳转方便编译期就能发现一部分问题。但我见过一个很隐蔽的坑Bean方法明明想实现单例结果每次调用都返回新对象。这多半是因为配置类上没有Configuration或者被代理的逻辑被破坏了。Spring 对Configuration类会做 CGLIB 代理当一个Bean方法内部调用另一个Bean方法时调用会被代理拦截返回的是容器中的同一个单例实例。如果类只用了Component或根本没有被代理lite 模式那么Bean方法就是一个普通方法每次调用都执行一遍new单例自然就破了。Configuration public class DataSourceConfig { Bean public DataSource dataSource() { return new HikariDataSource(); } Bean public JdbcTemplate jdbcTemplate() { // 这样调用dataSource() 其实是代理返回的同一个实例 return new JdbcTemplate(dataSource()); } }判断当前是 full 模式还是 lite 模式有一个简单办法打断点看配置类实例的 class看到 CGLIB 生成的代理类就是 full 模式否则就是 lite。新版 Spring 对 lite 模式的使用场景做了收紧但理解这个代理机制仍然很重要。3.5 实战从零写一个LogRecord自定义注解如果只学别人的注解会缺乏注解到底怎么被处理的体感。我自己强烈建议新手动手写一个自定义注解不用复杂能跑就行。这里分享一个最经典的例子方法级日志注解LogRecord打印方法入参和执行耗时。第一步定义注解Target(ElementType.METHOD) Retention(RetentionPolicy.RUNTIME) Documented public interface LogRecord { String value() default ; boolean printParams() default true; }Target(ElementType.METHOD)说明只能标在方法上Retention(RetentionPolicy.RUNTIME)表示这个注解会被保留到运行期这样 Spring 才能通过反射读到它。这两个元注解是自定义注解最基础也最关键的配置。第二步定义一个切面Aspect Component public class LogRecordAspect { Around(annotation(logRecord)) public Object around(ProceedingJoinPoint joinPoint, LogRecord logRecord) throws Throwable { long start System.currentTimeMillis(); try { return joinPoint.proceed(); } finally { long cost System.currentTimeMillis() - start; if (logRecord.printParams()) { System.out.println(String.format([%s] params%s, cost%dms, logRecord.value(), Arrays.toString(joinPoint.getArgs()), cost)); } else { System.out.println(String.format([%s] cost%dms, logRecord.value(), cost)); } } } }第三步用法Service public class UserService { LogRecord(value user.query, printParams true) public User queryUser(Long id) { return new User(id, demo); } }跑一次你会发现Around里的表达式annotation(logRecord)会自动绑定额外参数LogRecord logRecord直接拿到注解上填的值这个写法是 AspectJ 注解支持里最实用的一招。通过这个例子你就能直观理解注解只负责贴上标签具体的行为全由切面里的代码来控制。这也呼应了开头说的核心结论——注解不是魔法背后一定有人在处理它。4. 注解失效的五个经典坑从现象到根因的排查链路4.1 自己new出来的对象容器管不着这是个现象极端常见的坑。我举个例子某同事写了一个OrderValidator类上面标着Component里面注入了OrderDao。然后在另一个类里他用new OrderValidator()创建了对象结果一运行就空指针——orderDao是null。排查链路应该是这样的先确认OrderValidator有没有被扫进容器启动日志或调试BeanFactory再确认调用方是不是用容器获取的实例。之所以空指针是因为new走的完全不是 Spring 的生命周期AutowiredAnnotationBeanPostProcessor根本没有机会处理这个对象。我排查这类问题的第一反应永远是这个对象是从哪来的如果是new的十有八九是这里的问题。4.2 同类内部自调用Transactional悄悄失效现象非常迷惑日志里明明没有报错数据库里数据却乱套了批量操作执行到一半前面的一部分竟然已经提交了。你一翻代码方法上确实加了Transactional——那问题出在哪问题在于同类内部调用。比如OrderService里有一个submitOrder()方法它内部调用了this.cancelInventory()。cancelInventory()虽然标了Transactional但它是通过this直接调用的没有经过代理对象所以事务拦截器没被触发。排查链路要分三步走先确认调用链是不是跨类调用。跨类调用通常没问题同类内部调用就有嫌疑。看 Spring 版本和 AOP 机制是否生效。可以通过打印当前对象类型来验证是不是代理对象如果 class 里没有 CGLIB 字样说明代理没生效。解耦把被调用方法挪到另一个 Bean 中或者按前面讲的方式注入代理对象。侧根因其实不太难难的是意识到自调用是一个独立问题。4.3 启动类位置不对扫描范围覆盖不到NoSuchBeanDefinitionException是另一个高频看到的长日志最常见的原因是启动类放的位置不对。Spring Boot 启动类默认扫描自己所在包及其子包如果你的业务类放在别的包层级里容器根本扫不到Service、Repository这些注解等于白写。排查链路也不复杂先看包结构从启动类所在的包出发检查业务类是否在它的子包中如果确实不在就需要显式加ComponentScan(basePackages ...)来指定扫描路径。不过我更推荐的做法是直接调整包结构让启动类位于包的顶层这样可以避免后续一堆扫描路径的声明堆积在一起。有时候这个异常也可能是注入类型对不上导致的接口有多个实现或者接口和实现类的包名拼写错了这类需要再翻一遍注解声明的实现。4.4Value注入进不来先查配置源和占位符写法Value(${demo.value})注入不进来的情况排查思路基本按照两个方向走。第一个方向是配置源demo.value这个 key 到底有没有定义配置文件有没有被加载Spring Boot 里application.properties默认会被加载但如果 key 写错占位符不会被替换注入进来的可能就是字符串${demo.value}本身。第二个方向是写法注意Value只能注入到 Spring 管理的 Bean 中如果你在一个new出来的对象里写Value它同样不会工作。我在实际排查时有个习惯先 Debug 看一下Environment里有没有这个配置项再检查注解写法。两分钟就能定位。如果你发现配置项很多还是建议用ConfigurationProperties(prefix xxx)把配置绑定到对象里Spring 启动时失败也会给更明确的报错提示比一堆Value更容易治。4.5 循环依赖导致的注入失败设计上迂回解决当两个 Bean 互相注入对方时容器会报BeanCurrentlyInCreationException。早年 Spring 对单例 Bean 的 setter/字段循环依赖用三级缓存解决了但构造器注入的场景无法解决而且 Spring Boot 2.6 开始默认禁止循环依赖报错更快更明显。遇到循环依赖不要第一时间想着怎么开开关绕过这属于治标不治本。正确做法是先审视类设计是不是把属于 A 的职责塞进了 B或者把 B 的协作逻辑依赖到了 A 的初始化上。通常把公共依赖抽成第三个 Bean或者把调用改成方法参数传递都能绕开循环依赖。真要说临时缓解Lazy是一个可选项让一个 Bean 延迟初始化从而打断循环但它掩盖了设计问题根子还是要改模块划分。5. 把注解学成体系一套给新手的整理模板与查资料方法5.1 七问法模板把陌生注解快速变成自己的知识我带新人时经常给一个建议每学一个新注解别急着抄先试着回答下面七个问题回答完了这个注解就基本长在你脑子里了。这个注解是干什么的它能标在哪里方法、类、字段还是参数回想Target它是编译期生效、类加载期生效还是运行期生效回想Retention谁在处理它Spring 里对应的BeanPostProcessor、AOP Advisor或自动配置类是什么如果我不加它默认行为是什么它有哪些常用属性和默认值它和哪些注解长得像、边界在哪儿拿Transactional举例答完这七问你就知道它管理事务边界只能标在类或 public 方法上运行期生效处理它的是TransactionInterceptor加BeanFactoryTransactionAttributeSourceAdvisor不加它则无事务属性有propagation、isolation、rollbackFor它和Async一样依赖代理但两者注入的拦截器不同。这样整理出来的知识是网状结构的不是一条条孤立背诵的死记硬背。5.2 从易到难的学习路径先核心组件再 Web再 AOP/事务我的建议是分四个阶段推进每个阶段都配一个能跑的小项目。第一阶段把 IoC 容器和 Bean 定义搞熟练习用Configuration、Bean、Component和Autowired搭建一个不含 Web 依赖的控制台项目完成对象创建与依赖注入的闭环。第二阶段引入ConfigurationProperties、Profile、Conditional玩一玩多环境配置切换。第三阶段加上RestController、GetMapping、RequestBody等 Web 注解写一个简单的 REST 接口。第四阶段再进入Aspect与Transactional用统一的示例项目把日志 AOP 和声明式事务结合起来跑通。这个顺序的逻辑在于每一阶段都在前一个阶段的地基上增加一个新的注解处理机制。比如你只有先理解了代理模式才能明白Transactional为什么放在不同位置结果会不同。5.3 学会三件套查资料源码调试、文档索引、日志验证查文档当然是基本功但我更推荐三步连招。第一步对某个注解产生疑问时直接按住 Ctrl 点击注解名跳进源码看它的Target、Retention和注释先确认它的基本声明。第二步在 Spring 容器初始化处打断点比如AnnotationConfigApplicationContext的构造方法再在可疑的BeanPostProcessor上打断点看它有没有处理到你的目标类。第三步打开 Spring 的 debug 日志或者在代码里临时加输出验证你的猜测——比如观察配置类是不是 CGLIB 代理类型。遇到注解为什么不生效这类问题最快的路径往往不是反复看别人博客而是基于上面的三件套自己定位。我记得有一次排查一个ComponentScan不生效的问题就是靠打断点看ConfigurationClassPostParser到底解析了哪些配置类两分钟豁然开朗。这个能力越早练越好它让你从一个背注解的人变成一个理解容器的人。这里再分享一个我个人的小习惯每学一个注解我都会建一个annotation-notes的 markdown 文件按七问法记录再配一个 30 行以内的最小复现 demo。这个习惯保持了挺久效果远胜于收藏几十篇文章——因为收藏是别人的而笔记是你自己消化的。等你积累到三四十个注解以后你会发现自己对 Spring 的整体理解已经完全不是一个级别了。说白了Spring 注解体系虽然庞大但它背后始终围绕着一个核心逻辑把程序的结构信息、行为信息通过元数据暴露给容器再由容器和它内部的处理器协同完成装配。抓住这个主线浮躁的注解速查表就只是工具而你的知识体系可以持续生长。