Java 后端 / 系统课时
配置异步线程池
配置异步线程池
本课将把 @Async 从“能异步执行”升级为可治理的企业级线程池:明确线程与队列边界,传递日志上下文,统一处理未捕获异常,并通过接口与日志验证任务确实运行在独立线程中。
学习目标
- 使用自定义
ThreadPoolTaskExecutor控制核心线程、最大线程、队列和关闭行为。 - 使用
TaskDecorator传递并清理 MDC 上下文。 - 区分拒绝、异步异常和代理失效三类常见问题。
先确定线程池边界
@EnableAsync 负责开启异步方法代理,@Async 负责把方法调用提交给执行器。真正决定系统是否稳定的不是注解,而是执行器的容量边界。
| 参数 | 作用 | 配置原则 |
|---|---|---|
corePoolSize |
常驻工作线程数 | 从稳定并发量开始,结合压测调整 |
maxPoolSize |
队列已满后允许扩展的上限 | 必须受数据库、下游接口等容量约束 |
queueCapacity |
等待执行的任务数 | 使用有界队列,避免流量高峰耗尽内存 |
| 拒绝策略 | 线程与队列都满时的行为 | 核心业务通常选择快速失败并记录指标 |
I/O 等待型任务可以配置较多线程,CPU 密集型任务应接近可用处理器数量。不要照搬固定倍数,应同时观察任务耗时、队列长度、拒绝次数和下游饱和度。

完整配置与调用示例
下面示例可直接放入已有的 Spring Boot 3 Web 项目。它注册名为 businessExecutor 的线程池,通过 TaskDecorator 在提交任务时复制 MDC,并用 AsyncUncaughtExceptionHandler 接住 void 异步方法抛出的异常。
package com.example.asyncdemo;
import java.util.Map;
import java.util.concurrent.Executor;
import java.util.concurrent.ThreadPoolExecutor;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import org.slf4j.MDC;
import org.springframework.aop.interceptor.AsyncUncaughtExceptionHandler;
import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import org.springframework.context.annotation.Bean;
import org.springframework.core.task.TaskDecorator;
import org.springframework.scheduling.annotation.Async;
import org.springframework.scheduling.annotation.AsyncConfigurer;
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;
@SpringBootApplication
@EnableAsync
public class AsyncPoolApplication implements AsyncConfigurer {
private static final Logger log =
LoggerFactory.getLogger(AsyncPoolApplication.class);
public static void main(String[] args) {
SpringApplication.run(AsyncPoolApplication.class, args);
}
@Bean(name = "businessExecutor")
public ThreadPoolTaskExecutor businessExecutor() {
ThreadPoolTaskExecutor executor = new ThreadPoolTaskExecutor();
executor.setCorePoolSize(4);
executor.setMaxPoolSize(8);
executor.setQueueCapacity(200);
executor.setThreadNamePrefix("business-");
// 任务提交时复制上下文,执行结束后必须清理,避免线程复用造成串号。
executor.setTaskDecorator(mdcTaskDecorator());
executor.setRejectedExecutionHandler(
new ThreadPoolExecutor.AbortPolicy());
executor.setWaitForTasksToCompleteOnShutdown(true);
executor.setAwaitTerminationSeconds(30);
executor.initialize();
return executor;
}
@Bean
public TaskDecorator mdcTaskDecorator() {
return task -> {
Map<String, String> context = MDC.getCopyOfContextMap();
return () -> {
try {
if (context == null) {
MDC.clear();
} else {
MDC.setContextMap(context);
}
task.run();
} finally {
MDC.clear();
}
};
};
}
@Override
public Executor getAsyncExecutor() {
return businessExecutor();
}
@Override
public AsyncUncaughtExceptionHandler getAsyncUncaughtExceptionHandler() {
return (error, method, params) -> log.error(
"async method={} traceId={} failed",
method.getName(),
MDC.get("traceId"),
error);
}
}
@RestController
class AsyncDemoController {
private final ReportService reportService;
AsyncDemoController(ReportService reportService) {
this.reportService = reportService;
}
@PostMapping("/demo/async")
Map<String, Integer> submit() {
try {
MDC.put("traceId", "TRACE-OK");
reportService.generate("daily-report", false);
MDC.put("traceId", "TRACE-FAIL");
reportService.generate("invoice-export", true);
return Map.of("accepted", 2);
} finally {
MDC.clear();
}
}
}
@Service
class ReportService {
private static final Logger log =
LoggerFactory.getLogger(ReportService.class);
@Async("businessExecutor")
public void generate(String taskName, boolean fail) {
log.info("start task={} traceId={}",
taskName, MDC.get("traceId"));
if (fail) {
throw new IllegalStateException("simulated failure");
}
log.info("finish task={} traceId={}",
taskName, MDC.get("traceId"));
}
}预期结果
应用可以正常启动,并注册 POST /demo/async;调用接口后,两项任务由 business-<ID> 线程执行。启动应用并调用接口:
./mvnw spring-boot:run
curl -s -X POST http://localhost:8080/demo/async预期输出
{"accepted":2}
<TIME> INFO [business-<ID>] start task=daily-report traceId=TRACE-OK
<TIME> INFO [business-<ID>] finish task=daily-report traceId=TRACE-OK
<TIME> INFO [business-<ID>] start task=invoice-export traceId=TRACE-FAIL
<TIME> ERROR [business-<ID>] async method=generate traceId=TRACE-FAIL failed两项任务的日志先后顺序可能不同;时间、线程编号和异常堆栈以实际运行结果为准。接口先返回 accepted,表示任务已提交,不代表任务已经成功完成。
处理异常、拒绝与代理边界
void 返回值的异步方法无法把异常交还调用方,因此要通过 AsyncUncaughtExceptionHandler 记录日志、指标或告警。需要让调用方感知结果时,应返回 CompletableFuture<T>,并在调用方显式处理成功、失败与超时。
示例使用 AbortPolicy 快速拒绝超容量任务。生产接口还应捕获 TaskRejectedException,返回明确的繁忙响应或写入可靠队列;不要静默丢弃任务,也不要在没有容量评估时改成无限排队。
@Async 依赖 Spring 代理。类内部通过 this.generate() 自调用不会经过代理,private 方法也不会被增强。应把异步方法放在独立 Bean 中,由其他 Bean 调用。
MDC、租户编号和语言环境通常保存在 ThreadLocal 中,不会自动跨线程。TaskDecorator 适合复制这类轻量上下文,但必须在 finally 中清理。安全上下文或事务上下文应使用对应框架能力,不能假设会自动继承。
上线前验收
上线前至少检查以下结果:
- 压测时队列长度保持可控,拒绝次数能够被监控和告警。
- 应用停止时等待中的任务按预期完成或被明确取消。
- 成功、失败和拒绝三条路径都带有任务标识与追踪标识。
- 异步任务不会依赖已经结束的请求事务或不可复用的请求对象。