外观
Spring 速记手册
摘要
以命令式 Spring Framework、Spring Boot 应用为主要范围。先区分容器元数据、对象实例、代理与实际调用,再判断依赖注入、事务及自动配置是否生效。响应式事务、AOT 和 Native Image 的执行边界需另查对应实现。
快速入口
知识速记
| 知识点 | 结论与条件 |
|---|---|
| BeanDefinition | 是创建对象的元数据,不是对象本身;扫描注册后还要经过容器处理及实例创建 |
| refresh | 容器刷新分阶段准备定义、处理器、对象和事件;不同阶段获取 Bean 可能改变初始化顺序 |
| 依赖注入 | 构造器、字段、setter 的时机不同;候选类型、限定符和优先级共同决定选择 |
| 生命周期 | 实例化、属性填充、初始化和代理包装不是同一步,不能在半初始化对象上依赖全部能力 |
| 两类处理器 | BeanFactoryPostProcessor 处理定义等容器元数据,BeanPostProcessor 参与实例加工 |
| FactoryBean | 工厂 Bean 与产物有不同身份;getBean 名称与 & 前缀语义不同 |
| AOP | 代理拦截依赖调用经过代理;同类内部调用通常不经过代理,不能按有注解判断生效 |
| 事务边界 | 命令式事务常与线程及资源绑定;新线程、远程调用不自动加入同一本地事务 |
| 回滚规则 | 默认回滚规则区分异常类型;捕获异常、吞掉异常或错误调用路径可能改变结果 |
| 传播行为 | REQUIRED、REQUIRES_NEW、NESTED 的资源与回滚边界不同;NESTED 依事务管理器与保存点能力 |
| 自动配置 | 条件装配依 classpath、已有 Bean 和属性;starter 存在不保证某配置生效 |
| 属性绑定 | 外部配置来源与优先级、类型转换及校验共同决定结果;环境变量名不能随意映射 |
| MVC | 参数绑定、消息转换和异常处理是不同阶段;响应头、状态码与序列化要分别验证 |
| 异步、缓存、定时 | 通常还受代理、执行器、上下文和实例数量约束;注解不提供跨实例唯一执行 |
容器、对象和生命周期
BeanDefinition 描述如何创建对象,Bean 是实例;同一个容器中 singleton 通常一份,并不等于 JVM 全局唯一。prototype 每次按容器契约创建,注入 singleton 的 prototype 不自动每次业务调用重新获取,生命周期与销毁责任需明确。
普通创建主线为实例化 → 属性填充 → Aware 等回调 → 初始化处理与回调 → 后续包装;具体后处理器可参与不同环节。BeanFactoryPostProcessor 面向定义和容器元数据,BeanPostProcessor 面向实例加工。FactoryBean 是工厂 Bean,按名称取通常得到产物,使用 &名称取工厂本身。
构造器依赖必须在构造时就满足,字段/setter 注入发生在实例化后。候选多个时用明确限定符或优先级表达意图,不能靠扩大扫描范围解决所有注入问题。三级缓存与提前引用服务于特定单例循环场景,不解决所有构造器循环、作用域和代理组合。
AOP:调用什么才会生效
代理把调用包装起来执行增强。JDK 动态代理围绕接口,类代理依类与方法可覆盖等限制。默认代理模式下,经代理进入的可拦截方法才有增强;对象内部 this 调用通常绕过代理。手动 new 的对象、过早初始化调用、不可代理方法和错误对象来源都要查。
多个切面有进入、返回和异常路径,@Order 不能只记成数值大小;缓存、事务、重试组合必须验证具体嵌套关系,避免在事务外重试错误的片段或缓存未提交结果。
事务传播、回滚与调用线程
| 传播 | 直接记忆规则 | 常见代价或限制 |
|---|---|---|
| REQUIRED | 有合适现有事务就参与,否则创建 | 共享回滚状态,内层失败可能影响外层提交 |
| REQUIRES_NEW | 挂起现有事务并新建独立事务 | 常需额外连接,内外提交结果独立 |
| NESTED | 可用时在现有事务内用嵌套/保存点语义 | 依管理器和资源支持,不等于独立新事务 |
| SUPPORTS | 有则参与,没有则按非事务运行 | 不能认为总有事务 |
| MANDATORY | 要求存在现有事务 | 没有时失败 |
| NOT_SUPPORTED / NEVER | 前者挂起并非事务运行,后者要求无事务 | 与业务原子边界要一致 |
传统默认规则下 RuntimeException/Error 触发回滚,受检异常需按 rollbackFor 等配置确认;可配置的新版本规则和管理器差异应以实际设置为准。捕获并吞掉异常可能让代理看见正常返回;内层标记 rollback-only 后,捕获异常也不自动清除标志,外层提交可能失败。
命令式事务通常绑定执行线程及资源,@Async 新线程不自动参加原线程事务,@Transactional 也不能包远程服务的提交。timeout 依管理器/资源支持,不替代所有连接、远端和等待超时。
Boot 条件、属性和 MVC
自动配置依 classpath、条件、已有 Bean 和属性;starter 只是引入依赖和能力,不保证某个配置必生效。条件报告的 positive/negative match 表示匹配结果,找到失败条件后再修依赖、属性或冲突 Bean。
配置值来源包括文件、profile、环境和启动参数等,优先级按 Boot 版本规则;查最终绑定值和来源,不只读 YAML。@ConfigurationProperties 适合结构化绑定与校验,@Value 用于具体表达式/值,两者功能不完全相同。
MVC 请求经过处理映射、参数解析/绑定、调用、返回值处理与消息转换。@RequestParam 面向参数,@RequestBody 依消息转换读取请求体;绑定错误、业务异常和序列化失败是不同阶段。全局异常处理应有一致的状态码和响应形状,不能把所有异常都变成 200。
异步、缓存、事件、定时与失效排查
@Async 要经相应代理,执行器容量与异常路径需明确;Future 返回的异常和 void 异步异常处理不同。缓存命中可能跳过实际方法,key、租户、TTL、失效和并发回填都需设计,不由注解提供数据库一致性。
事务事件的阶段必须明确;提交后回调不自动处于仍可提交写入的原事务里。每实例定时器通常各自运行,扩容后任务会重复,集群唯一执行需独立机制。
事务失效依次查:容器对象 → 代理与真实调用 → 管理器/数据源 → 线程 → 方法/异常规则 → 数据库最终状态。启动慢依次分扫描、Bean 创建、初始化、外部依赖;懒加载可能把成本推给首请求。Actuator 的 beans/conditions/configprops 是诊断线索,开启时要控制权限和敏感数据,端点正常不等于业务正确。
常见问题排查
| 现象 | 检查顺序 | 证据与下一步 |
|---|---|---|
| Bean 找不到或候选冲突 | 看异常类型 → 查扫描范围与定义 → 查 profile/条件 → 查 qualifier | 找不到和多个候选是不同问题;不要用循环扫描扩大范围代替确认注册责任。 |
| 循环依赖启动失败 | 还原依赖图 → 区分构造器与属性注入 → 核对 Boot 配置与代理 | 三级缓存不支持所有循环;优先拆职责,不将允许循环作为通用修复。 |
| @Transactional 不生效 | 确认受管对象 → 查代理类型与调用路径 → 查管理器与资源 → 查异常 | 自调用、new 对象、异步和错误数据源分别判断;用数据库最终状态验收。 |
| 内层失败后外层提交失败 | 查传播与 rollback-only → 查捕获位置 → 查实际资源共享 | 捕获异常不等于清除回滚标志;UnexpectedRollbackException 要还原完整事务边界。 |
| 配置值与预期不同 | 查运行环境 → 查属性来源及优先级 → 查绑定与校验 | 确认实际值,避免只读某份 YAML 就断言生效;敏感属性不公开暴露。 |
| 自动配置缺失 | 查依赖版本 → 查条件报告 → 查排除项与自定义 Bean | 负匹配条件解释为什么未装配;不要在没确认条件前重复添加 starter。 |
| 启动变慢 | 区分扫描、实例创建、初始化、远端访问 → 对照启动事件 | 延迟初始化可能把成本移到首请求;需验证就绪和首请求延迟。 |
| 异步任务无事务或丢上下文 | 确认调用经过代理 → 查执行器 → 查异常处理与上下文安装 | Async 不自动复制原线程事务;Future 与 void 异常路径不同。 |
高频问题:操作与结果判断
以下以 Spring Framework 6、Spring Boot 3 的命令式事务与 Servlet 应用为范围;响应式事务使用上下文传播,不能直接套线程绑定规则。
事务不回滚:按调用边界和异常传播查
依次确认:对象由容器管理 → 调用经过事务代理 → 选中了正确事务管理器 → 异常从代理方法抛出 → 回滚规则匹配。对象自己 new、同对象内部调用、捕获异常后正常返回,都是常见断点。
下面是跨 Bean 调用片段,省略仓储定义;默认代理模式下,调用方应通过注入的 OrderService 调用。
java
@Service
public class OrderService {
private final OrderRepository repository;
public OrderService(OrderRepository repository) {
this.repository = repository;
}
@Transactional(rollbackFor = Exception.class)
public void place(Order order) throws Exception {
repository.insert(order);
validateAfterInsert(order); // 失败必须按契约抛出
}
}rollbackFor=Exception.class 表示此例希望检查异常也回滚,不是所有业务默认都应这样。验收用失败用例查询数据库,避免测试方法自身的事务掩盖服务事务边界。外部消息和远程操作不因数据库事务回滚而自动撤销。
UnexpectedRollbackException:内层失败已经标记回滚
典型路径:外层 REQUIRED → 内层 REQUIRED 参与同一事务 → 内层异常使事务被标记 rollback-only → 外层捕获异常并尝试正常提交。外层 catch 不会清除共享事务的回滚标记。
如果业务整体必须成功,传播失败并回滚;如果审计应独立保存,可在另一个 Bean 的 REQUIRES_NEW 方法中写入,但它会独立提交且需要额外连接容量。NESTED 通常借助保存点,支持情况由事务管理器和驱动决定,不能拿它替代所有独立事务。
异步调用:返回成功不代表任务成功
@Async 也需要代理调用,内部调用不会自动异步。方法返回 CompletableFuture 时,调用方必须观察异常完成;void 异步方法不能把异常直接返给已返回的调用方,应配置异常处理和业务失败记录。
调用线程的命令式事务不会自动传播到异步线程。需要写库时,在异步执行路径中建立明确事务;需要“事务提交后才通知”时,用 AFTER_COMMIT 事件或 Outbox。AFTER_COMMIT 监听期间需要新持久化事务的写入应显式建立新事务,不能指望已结束的事务再次提交。
验收同时检查任务受理、最终完成和失败告警;MDC/用户身份等上下文要有受控传播,不依赖线程复用碰巧留下的值。
配置和 Bean 为什么没生效
启动时可使用 --debug 查看条件评估报告。目标自动配置 unmatched:读具体条件,核对 classpath、已有 Bean、属性值和应用类型;目标配置 matched 但行为不对:检查实际注入 Bean 和配置绑定后的值。
配置值应追到来源:命令行、环境变量、活动 profile 和配置文件可能覆盖预期值。Actuator 的 conditions、configprops、env 可辅助,但应只在受控访问和脱敏条件下使用,不能为排障公开全部配置。最终验收断言实际 Bean 类型和绑定属性,而不只检查文件里写了什么。
优雅关闭:让入口、请求和任务使用同一预算
Spring Boot 3.2 配置片段:
yaml
server:
shutdown: graceful
spring:
lifecycle:
timeout-per-shutdown-phase: 30s这控制受支持 Web 服务器的关闭及生命周期阶段等待;30s 是每阶段预算,不能当作整个进程最多退出 30s。自建线程池、消息消费者和后台任务还要自己停止受理并有界排空。
先让入口停止分配新请求,TERM 后等待在途请求,再处理后台任务和资源。Kubernetes 宽限期必须覆盖 preStop、实际关闭阶段与余量;超过期限仍会被强制终止。用长请求、异步任务和 SIGTERM 演练,检查完成/取消记录,而不是只看进程退出。配置含义见 Boot 3.2.12 graceful shutdown。
工具与参数
以下先确认 Framework、Boot、JDK 和事务管理器版本。Actuator 端点需要相关依赖、显式启用与访问控制;不要把诊断端点公开到互联网。下表列出常用诊断入口。
| 工具或入口 | 查什么 | 条件与边界 |
|---|---|---|
Boot --debug 条件报告 | 自动配置正负匹配 | 是 Boot 启动参数,不是 JVM 参数;日志增量需有预算 |
Actuator conditions | 条件匹配原因 | 只在端点可用并授权时读取,不能证明业务请求正确 |
Actuator beans | 注册对象、依赖与作用域 | Bean 存在不证明调用经过代理;内容包含内部结构 |
Actuator configprops / env | 已绑定属性与来源 | 脱敏及暴露规则依版本;不要为查一个值开放全部端点 |
Actuator health | 健康检查结果 | 存活、就绪和外部依赖需分别设计,健康不等于每条业务路径成功 |
Actuator threaddump 或 jcmd | 请求线程与等待 | 获取快照有成本,关联实际请求时间与执行器 |
spring.profiles.active | 激活的配置环境 | 多环境及外部覆盖共同影响结果,名称不能代替配置来源核对 |
@Transactional rollbackFor / propagation / timeout | 回滚、资源组合和预算 | 超时支持与方法边界依管理器,不替代远端或连接获取超时 |
@Order | 处理器或切面顺序 | 进入顺序和返回顺序不同,必须用具体组合验证。 |
易错点与记忆提示
- 定义不是实例,实例不是代理,注解不是生效证明。
- 事务先查调用路,再查资源,再查异常:不要只查注解拼写。
- 本地事务不包远端:事件、消息与外部服务需要独立一致性方案。
- 默认规则有版本和管理器边界:不要把 NESTED 等同 REQUIRES_NEW。
- 诊断看实际运行配置:仓库配置、环境配置和最终绑定值有区别。
- 缓存不是事务一致性机制:失效、回填和多实例竞争需设计。
参考入口
Spring 声明式事务注解说明默认代理模式的自调用边界。目标版本的 Boot 端点与配置以其参考手册为准。
原理与完整示例
需要原因、源码或完整实验时再阅读:
- 04 - Spring 如何完成依赖注入
- 07 - 三级缓存与循环依赖
- 13 - Spring 事务为什么没有回滚:一份从代理到数据库的排查手册
- 12 - 事务传播行为:REQUIRED、REQUIRES_NEW 与 NESTED 的真实边界
- 22 - Spring 配置属性解析与绑定:值从哪里来,为什么没有生效
- 17 - Spring Boot 自动配置为什么生效:导入机制与条件装配
- 19 - Spring 启动慢、Bean 创建慢:如何定位容器初始化瓶颈
- 27 - Spring
@Async:异步执行、异常与上下文边界 - A - Spring 机制测试与源码验证
- 24 - Spring 切面顺序与组合语义:事务、重试与缓存谁包住谁
- 28 - Spring Cache:代理、Key 与一致性边界
- 02 - 一个 @Component 如何变成 BeanDefinition
- 01 - 从 refresh() 读懂 Spring:Bean 定义、后处理器与单例初始化
- 05 - Bean 生命周期与扩展点顺序
- 06 - BeanPostProcessor:Spring 的实例加工流水线
- 08 - FactoryBean、BeanFactory 与 ObjectProvider
- 10 - 同类调用为什么绕过 AOP:事务、异步与缓存失效的共同根因
- 11 - @Transactional 的开启、提交与回滚:Spring 声明式事务执行链
- 16 - 返回值如何变成 JSON:响应写出与统一异常处理
- 29 - Spring 定时任务:调度语义、重叠执行与集群边界