Java 后端 / 知识点

Spring Boot 开发速查手册

手册条目

检查异步开关、代理调用和线程池拒绝情况。

排查异步任务未执行

用于定位标注了 @Async 的方法没有进入异步线程、调用后无日志,或高峰期偶发未执行。先用最小探针确认异步基础设施,再依次检查代理调用、执行器绑定、拒绝策略和异常处理。

最小验证

下面是片段示例,需放在同一个 Spring Boot 项目、同一组件扫描范围内。控制器和异步服务分属不同 Bean,避免自调用绕过代理。

java
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> 替换为实际端口:

bash
curl -s -X POST "http://127.0.0.1:<PORT>/internal/async-probe"

预期结果:接口返回的调用线程与任务日志线程名称不同,<ID>、<TIME> 为动态值。

text
{"taskId":"<ID>","callerThread":"http-nio-<PORT>-exec-1"}
<TIME> INFO ... async taskId=<ID>, thread=async-biz-1

若日志仍在 http-nio-* 线程,优先检查调用是否经过 Spring 代理;若任务线程已切换但没有业务日志,再检查拒绝和执行阶段异常。

定位顺序

  1. 确认配置类已被扫描,并存在 @EnableAsync。只有 @Async 而未启用异步处理时,方法不会获得异步拦截。
  2. 确认异步类是 Spring Bean,且由另一个 Bean 注入后调用。this.run()、同类方法互调、构造阶段直接调用都可能绕过默认代理。
  3. 异步方法优先保持 public,不要依赖 private、final 方法被默认代理拦截;类也不要通过手工 new 实例化。
  4. 检查 @Async("bizExecutor") 与执行器 Bean 名完全一致。多个执行器并存时显式指定,避免绑定错误。
  5. 搜索 TaskRejectedException、RejectedExecutionException 和业务异常。任务可能尚未执行就被拒绝,也可能已入线程后立即失败。

线程池与异常

线程池在活动线程达到 maxPoolSize 且队列已满时会触发拒绝。AbortPolicy 会显式失败,便于告警和补偿;DiscardPolicy 会静默丢弃任务,不适合支付、通知、对账等不能丢失的业务。

CallerRunsPolicy 会让提交线程执行任务,虽然能够形成反压,但可能把耗时工作转移到 HTTP、消息消费或调度线程。更稳妥的方案是有界队列、显式拒绝、指标告警,并保证任务可幂等、可重试。

void 异步方法抛出的异常不会直接返回给调用方,应通过日志或 AsyncUncaughtExceptionHandler 处理。需要感知结果时返回 CompletableFuture<T> 并在调用端注册 whenComplete;不要立即 join(),否则会把异步调用重新变成阻塞等待。

排障清单

  • 启动日志中没有异步配置类或执行器 Bean:检查包扫描、Profile 和条件注解。
  • 方法执行但线程名未变化:检查同类自调用、手工实例化以及代理可拦截的方法声明。
  • 高峰期偶发不执行:检查线程数、队列长度、拒绝异常和下游耗时。
  • 只有失败任务没有日志:检查 void 方法异常处理,并在任务入口记录任务 ID。
  • 异步任务依赖未提交的数据:异步线程不应假定原事务已经提交,可改为提交后发布事件,或让任务按 ID 重新查询已提交数据。

风险与恢复

默认 @EnableAsync 使用代理模式,只拦截经过 Spring 代理的外部调用。确需拦截同类调用时可以采用 AspectJ 模式,但会增加织入成本;生产项目通常优先拆分 Bean,调用路径更直观,也更容易排障。

目录与阅读设置

记录一个想法

Spring Boot 开发速查手册

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通