外观
20 - Spring 线上问题排查手册:Bean、代理、事务与请求链路
适用版本:Spring Framework 6.x、Spring Boot 3.x。线上诊断必须遵守权限、审计和数据脱敏要求。
本文是专题故障分诊入口,不替代各机制文章。建议先阅读01 - 从 refresh() 读懂 Spring和A - Spring 机制测试与源码验证。
摘要
接口报错、注解不生效、数据库结果与预期不一致,可能发生在不同环节。排查时先确认哪次请求、哪个实例出现了问题,再沿调用链寻找最后一个成功阶段和第一个失败阶段。本文先说明容器、代理、事务和请求处理之间的关系,再给出各层需要收集的证据。
1. 通用原则:先保留现场,再缩小层次
开始操作前记录:
- 发生时间、实例、版本和发布批次;
- 请求 ID、用户影响和错误比例;
- 完整异常链与关键指标;
- 最近代码、配置、依赖和环境变更。
高风险诊断命令先在单实例、低流量或复现环境验证。
同时记录“没有发生什么”,但先确认观测覆盖了目标实例和时间窗口。例如,网关有请求记录而应用无访问日志,应先检查转发目标、日志采集与记录位置;只有进一步确认请求没有进入 Controller(处理请求的控制器),才能排除其内部异常。缺少日志本身不能证明代码没有执行。
事务日志中的 rollback(回滚)完成,也要与目标请求、数据库连接和事务关联。确认目标写入属于该事务后,才有依据排除“该事务没有回滚”的假设。能排除假设的证据与报错同样重要,但结论不能超出证据覆盖的范围。
2. 故障分层
先区分两条链路。启动时,Spring 容器读取对象定义、创建 Bean 并注入依赖;Bean 是容器管理的对象,注入是为对象提供所需的依赖。启用基于代理的 AOP(面向切面编程)时,调用者可能拿到包装目标对象的代理,事务等逻辑由代理在方法调用前后执行。
请求到来后,Spring MVC(Web 请求处理框架)选择处理方法、解析参数并调用业务对象;业务方法返回后,还可能需要把结果转换成 JSON 并写入 HTTP 响应。因此,Bean 创建成功、业务执行成功、数据库提交成功、客户端收到响应,是不同的完成点。
下面是请求故障的排查顺序,不表示每次请求都会重新创建 Bean,也不表示所有方法都必须经过事务代理。启动失败时应直接从容器创建链查起。
图表将在阅读到此处时加载…
接入层
检查负载均衡、网关、DNS(域名解析)、TLS(连接加密协议)、实例端口和访问日志。先确认网关实际选择了哪个实例,避免用另一个实例的日志解释当前请求。
如果请求根本没有到达实例,先转到网络 20 - 分层网络排障方法或网络 15 - 反向代理与网关错误,不要在 Controller 上增加日志碰运气。
MVC 层
HandlerMapping 负责把请求映射到处理器(Handler),在常见的注解式 Controller 中,处理器对应控制器方法。检查请求路径、HTTP 方法(如 GET、POST)和 Content-Type(请求内容类型)是否符合映射条件,再检查参数解析、拦截器和异常处理。请求到达应用,并不意味着已经进入业务方法。
具体链路见14 - DispatcherServlet 调度全流程、15 - Controller 参数解析与数据绑定和16 - 返回值、JSON 与统一异常处理。
容器层
BeanDefinition 是描述 Bean 如何创建和配置的元数据,不能等同于已创建的对象。Profile 用于按环境选择配置,Condition 用于决定配置是否满足生效条件,Qualifier 用于在多个候选 Bean 中进一步限定注入对象。
先区分“定义不存在”和“定义存在但创建失败”。前者查看组件扫描、Import 配置导入和条件判断;后者沿依赖链定位构造器、注入、初始化或后处理器。后处理器会参与 Bean 的加工,例如创建代理;最外层的“依赖注入失败”异常可能只是下层创建失败的结果。
AOP 层
代理是调用者与目标对象之间的包装对象。Advisor 将增强逻辑与匹配规则组合起来,Pointcut(切点)决定哪些调用可以应用增强。自调用是目标对象内部通过 this 调用自身方法,在通常的代理模式下不会重新进入代理。
代理存在不等于目标方法被增强。需要同时证明调用者持有代理、Advisor 已安装、Pointcut 匹配、方法可被当前代理策略拦截,且调用没有在目标对象内部绕过代理。
事务与资源层
事务管理器协调所管理资源的事务开始、提交和回滚;连接池则复用数据库连接。检查所用事务管理器、连接池、SQL、锁等待、异常传播和提交结果,先确认目标写入是否真的参与了预期事务。
数据库阻塞和死锁应继续查看数据库 19 - SELECT 与锁和数据库 20 - 死锁定位与修复。本地数据库事务无法覆盖消息和 HTTP,跨系统一致性见分布式 29 - Outbox 与 CDC。
3. Bean 问题证据
围绕目标 Bean 名称和所在的 ApplicationContext(应用上下文),在受控环境中选择证据来源:
- Actuator 是 Boot 的监控与管理功能:
beans查看 Bean 信息,conditions查看条件装配报告,mappings查看请求映射;端点是否可用取决于配置与访问权限。 - 应用启动 DEBUG 日志:定位配置判断和 Bean 创建失败的上下文。
- 使用
ApplicationContext#getBeanDefinitionNames()的诊断工具:查看当前上下文中的定义名称,再沿目标定义追查创建结果。 - Arthas 是 Java 运行时诊断工具:
sc查看已加载类,jad查看反编译代码,watch观测方法调用。类已加载不能单独证明 Bean 已注册或注入正确。
生产端点必须鉴权,Arthas 表达式与观测次数必须受限,避免性能影响和敏感数据泄露。
4. 代理问题证据
下面是日志片段,需要已有的 log、非空的待检查对象 bean,以及 org.springframework.aop.support.AopUtils 导入。bean 应取自调用方实际持有的对象,否则检查结果可能与故障调用无关。
java
log.info("beanClass={}, aopProxy={}",
bean.getClass().getName(), AopUtils.isAopProxy(bean));预期输出包含对象的运行时类名和 aopProxy 布尔值。即使后者为 true,也只能说明该对象是 Spring AOP 代理,不能证明某次调用进入了指定增强。继续确认:
- 调用方持有的是不是该代理;
- 方法是否为
public,以及是否满足所用代理策略和增强机制的方法限制;非public方法的支持范围要按具体机制与版本判断,不能一概而论; - 是否发生同类调用;
- Advisor 是否匹配并按预期排序。
5. 事务问题证据
SQL 日志通常只能说明某条语句被记录,不能单独证明它属于哪个事务、最终是否提交。要把同一请求的事务生命周期与资源证据关联起来:
- 事务创建、参与、挂起、提交或回滚日志;
- 连接池
active(已借出的连接)和pending(等待获取连接的请求)等指标,具体名称与口径以连接池实现为准; - 数据库会话、锁等待和慢查询;
- 异常是否越过代理边界;
- 多数据源与事务管理器对应关系。
在基于代理的声明式事务中,事务增强需要观察方法的返回或异常才能按规则处理事务。如果业务代码捕获异常后正常返回,增强看到的结果就与“异常逃出方法”不同;但是否回滚还要结合回滚规则和事务状态判断。多数据源场景中,还要确认执行 SQL 的连接属于当前事务管理器所管理的资源。
6. 请求链问题证据
Trace ID 是关联一次调用链中各段记录的追踪标识。让它贯穿网关、应用和下游,并记录有限的结构化字段:路由、状态码、耗时、异常类型、下游结果。不要默认记录完整 Body(请求体)、Cookie 或 Authorization(认证头)。追踪标识用于关联执行记录,是否可作为业务去重依据需要另外设计。
若 Controller 已返回但客户端失败,应继续检查序列化(把返回对象转换为 JSON 等传输内容)、响应提交、网关超时和连接中断。方法返回只是应用内部的完成点;数据库事务提交与 HTTP 响应发送也不是同一个原子操作,后者失败不能据此推断前者已经回滚。
7. 典型决策表
| 现象 | 第一检查点 | 深入方向 |
|---|---|---|
| 启动失败 | 最内层有效异常及其上下文 | refresh() 容器刷新流程中的对应阶段 |
| Bean 找不到 | BeanDefinition 是否存在 | 扫描、Import、Condition |
| 基于代理的注解增强不生效 | 是否经过代理 | 自调用、方法限制、Advisor |
| 事务未回滚 | 异常是否逃出代理 | 规则、管理器、资源参与 |
| 接口 404 | mappings 是否存在 | 网关前缀、Servlet、条件匹配 |
| 接口 500 | 失败发生阶段 | 参数、业务、序列化、异常解析 |
| 启动缓慢 | 最慢步骤/线程栈 | I/O、超时、扫描、类加载 |
8. 完整案例:接口超时但数据库已经写入
现象:客户端调用创建订单接口超时并自动重试,数据库出现两条订单记录;应用 CPU 正常。
按层取证:
- 网关日志显示第一次请求已转发到实例,并在响应超时后返回 504;
- 应用访问日志显示 Controller 已执行完成;
- 事务日志显示数据库 COMMIT 成功;
- 响应日志显示 JSON 序列化或响应写出阶段阻塞;
- 第二次请求使用了新的随机请求号,数据库唯一约束无法去重。
这些证据应按同一请求和时间线对应起来,而不能只比较相近的日志时间。可以据此判断:
- 不是请求未到实例;
- 不是事务回滚失效;
- 响应阶段存在阻塞,应优先定位该阶段;数据库执行是否也消耗了过多时间,仍需 SQL 和提交耗时证据,不能仅凭 COMMIT 成功排除;
- 不能通过扩大事务范围撤销已经提交的第一次请求。
根因链是:
text
数据库提交成功
→ HTTP 响应未在网关预算内完成
→ 客户端重试
→ 服务端缺少稳定幂等键
→ 重复创建订单幂等是指同一业务操作重复提交时,不产生额外的业务效果。稳定幂等键应在同一操作的重试之间保持一致;每次重试都生成新的随机请求号,按该号码建立的唯一约束就无法识别两次请求属于同一操作。
修复应分别落在三个边界:缩短或修复响应阶段、统一网关与应用超时预算、按业务请求号实现幂等。超时预算是各环节允许等待的时间,调整时需要考虑业务执行和响应发送的总耗时,不能仅延长其中一层就认为问题解决。幂等设计见分布式 13 - 幂等性与重复请求。
回归验证不能只检查第二次请求返回成功,还应断言两次相同幂等键调用最终只有一条业务记录,并模拟第一次响应丢失。
9. 容易踩的坑
- 线上直接打开全包 TRACE 日志,造成 I/O 压力和日志洪峰。
- 使用无条件 Arthas
watch打印大对象或敏感参数。 - 看到代理类名就认定 AOP 一定执行,忽略 Advisor 匹配。
- 只看应用日志,不看连接池、数据库和网关指标。
- 未保留现场就重启,丢失线程、连接和锁等待证据。
- 一次修改多个层次,问题消失后无法判断真正原因。
- 将日志中的时间相关性直接当成因果关系,没有构造反例或对照组。
- 只恢复接口可用,没有补充能提前发现同类问题的指标和回归测试。
10. 一套可复用的排查顺序
- 确认影响范围并止损。
- 锁定实例、版本、请求与时间窗口。
- 判断故障位于启动链还是请求链。
- 请求故障按接入、MVC、业务 Bean、代理、事务与资源、响应逐层验证;启动故障沿定义处理、依赖创建和初始化链验证。
- 每一步收集能证伪假设的证据。
- 修复后补充监控、测试和回归用例。
每轮只推进一个可验证假设,并记录:
text
假设 → 所需证据 → 实际结果 → 是否排除 → 下一步止损操作和根因修复必须分开记录。重启、扩容或关闭功能可以恢复服务,但不能单独证明根因。
11. 总结
Spring 排障的核心不是记住更多注解,而是把现象放回容器、代理、事务和请求处理的真实调用链。
- 先分层定位,再深入源码,避免从一个异常猜整个系统。
- Bean 存在、代理存在、调用经过代理是三个不同事实。
- 修复后补充测试、指标和诊断能力,使同类故障再次发生时能够更快定位。