Java 后端 / 知识点
Spring Boot 开发速查手册
手册条目
检查异步开关、代理调用和线程池拒绝情况。
排查异步任务未执行
用于定位标注了 @Async 的方法没有进入异步线程、调用后无日志,或高峰期偶发未执行。先用最小探针确认异步基础设施,再依次检查代理调用、执行器绑定、拒绝策略和异常处理。
最小验证
下面是片段示例,需放在同一个 Spring Boot 项目、同一组件扫描范围内。控制器和异步服务分属不同 Bean,避免自调用绕过代理。
package com.example.demo;
import java.util.Map;
import java.util.UUID;
import java.util.concurrent.CompletableFuture;
import java.util.concurrent.ThreadPoolExecutor;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.scheduling.annotation.Async;
import org.springframework.scheduling.annotation.EnableAsync;
import org.springframework.scheduling.concurrent.ThreadPoolTaskExecutor;
import org.springframework.stereotype.Service;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.RestController;
@Configuration
@EnableAsync
class AsyncProbeConfig {
@Bean("bizExecutor")
ThreadPoolTaskExecutor bizExecutor() {
ThreadPoolTaskExecutor executor = new ThreadPoolTaskExecutor();
executor.setCorePoolSize(2);
executor.setMaxPoolSize(4);
executor.setQueueCapacity(20);
executor.setThreadNamePrefix("async-biz-");
// 队列和线程均耗尽时显式失败,避免静默丢任务。
executor.setRejectedExecutionHandler(new ThreadPoolExecutor.AbortPolicy());
return executor;
}
}
@Service
class AsyncProbeService {
private static final Logger log = LoggerFactory.getLogger(AsyncProbeService.class);
@Async("bizExecutor")
public CompletableFuture<Void> run(String taskId) {
log.info("async taskId={}, thread={}", taskId, Thread.currentThread().getName());
return CompletableFuture.completedFuture(null);
}
}
@RestController
class AsyncProbeController {
private final AsyncProbeService service;
AsyncProbeController(AsyncProbeService service) {
this.service = service;
}
@PostMapping("/internal/async-probe")
Map<String, String> run() {
String taskId = UUID.randomUUID().toString();
service.run(taskId);
return Map.of(
"taskId", taskId,
"callerThread", Thread.currentThread().getName());
}
}启动应用后执行,<PORT> 替换为实际端口:
curl -s -X POST "http://127.0.0.1:<PORT>/internal/async-probe"预期结果:接口返回的调用线程与任务日志线程名称不同,<ID>、<TIME> 为动态值。
{"taskId":"<ID>","callerThread":"http-nio-<PORT>-exec-1"}
<TIME> INFO ... async taskId=<ID>, thread=async-biz-1若日志仍在 http-nio-* 线程,优先检查调用是否经过 Spring 代理;若任务线程已切换但没有业务日志,再检查拒绝和执行阶段异常。
定位顺序
- 确认配置类已被扫描,并存在
@EnableAsync。只有@Async而未启用异步处理时,方法不会获得异步拦截。 - 确认异步类是 Spring Bean,且由另一个 Bean 注入后调用。
this.run()、同类方法互调、构造阶段直接调用都可能绕过默认代理。 - 异步方法优先保持
public,不要依赖private、final方法被默认代理拦截;类也不要通过手工new实例化。 - 检查
@Async("bizExecutor")与执行器 Bean 名完全一致。多个执行器并存时显式指定,避免绑定错误。 - 搜索
TaskRejectedException、RejectedExecutionException和业务异常。任务可能尚未执行就被拒绝,也可能已入线程后立即失败。
线程池与异常
线程池在活动线程达到 maxPoolSize 且队列已满时会触发拒绝。AbortPolicy 会显式失败,便于告警和补偿;DiscardPolicy 会静默丢弃任务,不适合支付、通知、对账等不能丢失的业务。
CallerRunsPolicy 会让提交线程执行任务,虽然能够形成反压,但可能把耗时工作转移到 HTTP、消息消费或调度线程。更稳妥的方案是有界队列、显式拒绝、指标告警,并保证任务可幂等、可重试。
void 异步方法抛出的异常不会直接返回给调用方,应通过日志或 AsyncUncaughtExceptionHandler 处理。需要感知结果时返回 CompletableFuture<T> 并在调用端注册 whenComplete;不要立即 join(),否则会把异步调用重新变成阻塞等待。
排障清单
- 启动日志中没有异步配置类或执行器 Bean:检查包扫描、Profile 和条件注解。
- 方法执行但线程名未变化:检查同类自调用、手工实例化以及代理可拦截的方法声明。
- 高峰期偶发不执行:检查线程数、队列长度、拒绝异常和下游耗时。
- 只有失败任务没有日志:检查
void方法异常处理,并在任务入口记录任务 ID。 - 异步任务依赖未提交的数据:异步线程不应假定原事务已经提交,可改为提交后发布事件,或让任务按 ID 重新查询已提交数据。
风险与恢复
默认 @EnableAsync 使用代理模式,只拦截经过 Spring 代理的外部调用。确需拦截同类调用时可以采用 AspectJ 模式,但会增加织入成本;生产项目通常优先拆分 Bean,调用路径更直观,也更容易排障。


