Java 后端 / 系统课时

配置异步线程池

配置异步线程池

本课将把 @Async 从“能异步执行”升级为可治理的企业级线程池:明确线程与队列边界,传递日志上下文,统一处理未捕获异常,并通过接口与日志验证任务确实运行在独立线程中。

学习目标

  • 使用自定义 ThreadPoolTaskExecutor 控制核心线程、最大线程、队列和关闭行为。
  • 使用 TaskDecorator 传递并清理 MDC 上下文。
  • 区分拒绝、异步异常和代理失效三类常见问题。

先确定线程池边界

@EnableAsync 负责开启异步方法代理,@Async 负责把方法调用提交给执行器。真正决定系统是否稳定的不是注解,而是执行器的容量边界。

参数 作用 配置原则
corePoolSize 常驻工作线程数 从稳定并发量开始,结合压测调整
maxPoolSize 队列已满后允许扩展的上限 必须受数据库、下游接口等容量约束
queueCapacity 等待执行的任务数 使用有界队列,避免流量高峰耗尽内存
拒绝策略 线程与队列都满时的行为 核心业务通常选择快速失败并记录指标

I/O 等待型任务可以配置较多线程,CPU 密集型任务应接近可用处理器数量。不要照搬固定倍数,应同时观察任务耗时、队列长度、拒绝次数和下游饱和度。

异步调用、线程池队列与上下文传递关系图

完整配置与调用示例

下面示例可直接放入已有的 Spring Boot 3 Web 项目。它注册名为 businessExecutor 的线程池,通过 TaskDecorator 在提交任务时复制 MDC,并用 AsyncUncaughtExceptionHandler 接住 void 异步方法抛出的异常。

java
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"));
    }
}

预期结果

text
应用可以正常启动,并注册 POST /demo/async;调用接口后,两项任务由 business-<ID> 线程执行。

启动应用并调用接口:

bash
./mvnw spring-boot:run
curl -s -X POST http://localhost:8080/demo/async

预期输出

text
{"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 中清理。安全上下文或事务上下文应使用对应框架能力,不能假设会自动继承。

上线前验收

上线前至少检查以下结果:

  • 压测时队列长度保持可控,拒绝次数能够被监控和告警。
  • 应用停止时等待中的任务按预期完成或被明确取消。
  • 成功、失败和拒绝三条路径都带有任务标识与追踪标识。
  • 异步任务不会依赖已经结束的请求事务或不可复用的请求对象。
按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

配置异步线程池

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

登录哪都通