提交报表的接口改成了异步:收到请求就返回 {"job_id":1} 和 202,具体生成交给后台。日志看起来很正常:job 1 started on thread task-1,大约 800 毫秒后出现 job 1 finished。定时清理任务也在跑,每轮打印 scheduled sweep: 1 jobs,线程名是 scheduling-1。

问题出在发布的时候。服务重启,前一天晚上提交、队列里还没轮到的任务全部消失,提交方只在内存里记着 job id,重启后连状态都查不到。更麻烦的是没人发现,直到第二天业务方问「报表怎么没出」。这不是代码写漏了异常处理,而是「把任务放在进程内存里」这个选择本身没有持久化能力。

另一个隐患藏在日志的线程名里。task- 是框架默认执行器的命名前缀。在没有自定义执行器时,Spring 原生会退回 SimpleAsyncTaskExecutor,每提交一次就新建一个线程;Spring Boot 3 会自动配一个 ThreadPoolTaskExecutor,但它的默认队列无界、最大线程数几乎不设上限,同样不能直接上生产。任务少时看不出问题,突发几百个任务就会把线程数和内存一起推高。

@Async 做了什么,默认执行器有什么问题

@Async 的作用是把方法调用从当前线程挪到另一个线程执行,调用方立即返回。它依赖 Spring 的代理:调用必须经过代理,方法才会被提交给执行器。所以同类方法自调用会失效,和上一篇事务自调用是同一个原因;启动类或配置类上还要有 @EnableAsync,否则注解只是个标记。

没有自定义执行器时,Spring 原生默认用 SimpleAsyncTaskExecutor,它的实现非常朴素:来一个任务就新建一个线程,跑完就结束,不复用。名字里的 task 前缀就是这么来的。优点是没有队列、没有拒绝策略、不会因为排队把内存撑爆;缺点是完全失去了线程复用的意义,任务一多,创建线程的开销和存活线程数都不可控。

Spring Boot 会自动配一个默认线程池,情况稍好但不等于安全:核心线程 8 个,队列容量无界,最大线程数接近不设限。无界队列意味着任务先排队,永远不会触发扩容,积压多了直接吃内存;发布时也看不到拒绝信号,只会越来越慢。所以「Boot 有默认池」不能成为不配执行器的理由。

判断自己用的是哪一种,最直接的办法是看日志里的线程名。名字按 task-1、task-2 一直递增,说明每次都在新建;名字只在 task-1 到 task-8 之间循环,说明用了默认线程池,但队列仍然是无界的。自定义线程池后,名字会固定在一个前缀加编号的小范围内,比如 job-1 到 job-4。

下面是最小可运行的写法。控制器只负责生成 id 和返回 202,业务方法标 @Async,用 Thread.sleep 模拟耗时:

package com.example.demo.job;

import java.util.Map;
import java.util.concurrent.atomic.AtomicLong;
import org.springframework.http.ResponseEntity;
import org.springframework.scheduling.annotation.Async;
import org.springframework.stereotype.Service;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.RestController;

@RestController
public class JobController {
    private final AtomicLong seq = new AtomicLong();
    private final ReportJob job;

    public JobController(ReportJob job) {
        this.job = job;
    }

    @PostMapping("/api/jobs/report")
    public ResponseEntity<Map<String, Object>> submit() {
        long id = seq.incrementAndGet();
        job.run(id);
        return ResponseEntity.status(202).body(Map.of("job_id", id));
    }
}

@Service
class ReportJob {
    @Async
    public void run(long id) {
        System.out.println("job " + id + " started on thread "
                + Thread.currentThread().getName());
        try {
            Thread.sleep(800);
        } catch (InterruptedException e) {
            Thread.currentThread().interrupt();
        }
        System.out.println("job " + id + " finished");
    }
}

启动后提交一次,实际返回是 202 和 {"job_id":1},日志就是开头那两行。注意 202 表示「已接受、尚未完成」,不是「已完成」;客户端不应该在收到 202 后立刻查询结果,而要轮询或等回调。把 202 写成 200,语义就错了。

curl -s -X POST 127.0.0.1:8081/api/jobs/report
{"job_id":1}

这个最小版本依赖只有 web 和 actuator,打包后直接跑 jar,不需要额外的任务框架:

<dependencies>
  <dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-web</artifactId>
  </dependency>
  <dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-actuator</artifactId>
  </dependency>
</dependencies>

mvn -q -DskipTests package
java -jar target/demo-0.0.1.jar

这个最小版本还有两个缺陷:默认执行器无上限,以及返回 void 时异常不会传到调用方。任务里抛了异常,日志可能只有一行堆栈,接口侧完全无感。要让失败可见,要么返回 Future 并在调用方处理,要么配置 AsyncUncaughtExceptionHandler,把异常记进结构化日志和告警。

自己配线程池:核心、上限、队列、拒绝

生产上必须显式配一个执行器。四个参数的含义可以用银行窗口来理解:核心线程数是常开的窗口,最大线程数是忙时最多开多少,队列是等候区,拒绝策略是等候区也满了之后怎么办。任务先占核心窗口,满了排队,队列满了才扩到最大线程数,再满就触发拒绝策略。

下面这个配置给异步任务单独一个池子,不和定时任务共用。核心 4、最大 8、队列 100、线程名前缀 job-,拒绝策略用 CallerRunsPolicy,意思是池子满时让提交任务的线程自己执行,形成天然的降速:

package com.example.demo.config;

import java.util.concurrent.ThreadPoolExecutor;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.scheduling.annotation.EnableAsync;
import org.springframework.scheduling.annotation.EnableScheduling;
import org.springframework.scheduling.concurrent.ThreadPoolTaskExecutor;

@Configuration
@EnableAsync
@EnableScheduling
public class AsyncConfig {

    @Bean("jobs")
    public ThreadPoolTaskExecutor jobs() {
        ThreadPoolTaskExecutor ex = new ThreadPoolTaskExecutor();
        ex.setCorePoolSize(4);
        ex.setMaxPoolSize(8);
        ex.setQueueCapacity(100);
        ex.setThreadNamePrefix("job-");
        ex.setRejectedExecutionHandler(new ThreadPoolExecutor.CallerRunsPolicy());
        ex.initialize();
        return ex;
    }
}

然后在 @Async 上写 bean 名字:@Async("jobs")。不写名字时,Spring 会去找唯一的 TaskExecutor 或名为 taskExecutor 的 bean;项目里一旦有多个执行器,不写名字就可能报「期望一个但找到多个」,或者悄悄用了不是你预期的那个。

目录上把任务和配置分开,避免任务类被当成控制器扫描或反过来。下面这个分层足够小项目用:

controller:提交任务,返回 202 和 job id
job:异步任务与定时任务的具体逻辑
config:执行器、调度器、线程池参数
repository:任务状态表的读写

参数怎么定要看任务类型。任务主要等 IO(调接口、读写文件、等数据库),线程可以多一些,常见起点是核心数乘 2;任务主要吃 CPU(计算、压缩、加解密),线程接近核心数就行,再多只会互相抢 CPU。队列容量不要设成无界,无界队列会让内存一直涨,最后 OOM;也不要设成 1,等于没有缓冲,突发流量全部触发拒绝。

拒绝策略有四种,各有明确的后果。直接抛异常适合「必须让调用方知道没接住」的场景;丢弃最老适合实时性要求高的数据;丢弃新任务适合可丢的日志类任务;让调用线程自己跑适合想自动降速、但不能丢任务的场景。选哪种不是风格问题,要先回答「这个任务丢了会造成什么」。

@Scheduled:默认只有一个调度线程

@Scheduled 按固定间隔或 cron 表达式触发方法。它默认用单线程的调度器,所有定时任务在这一个线程上排队执行。一个任务跑十分钟,后面所有任务都推迟十分钟,日志里能看到的线程名始终是 scheduling-1。这不是「任务没触发」,而是「触发了但在排队」。

下面这个清理任务每五秒跑一次,打印当前待处理任务数。本机日志里是 scheduled sweep: 1 jobs,线程名 scheduling-1:

package com.example.demo.job;

import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import org.springframework.scheduling.annotation.Scheduled;
import org.springframework.stereotype.Component;

@Component
public class SweepJob {
    private static final Logger log = LoggerFactory.getLogger(SweepJob.class);
    private final JobRepository jobs;

    public SweepJob(JobRepository jobs) {
        this.jobs = jobs;
    }

    @Scheduled(fixedDelay = 5000)
    public void sweep() {
        int pending = jobs.countPending();
        log.info("scheduled sweep: {} jobs", pending);
    }
}

要让它跑起来,配置类上必须有 @EnableScheduling,和异步的 @EnableAsync 一起加。少这个注解,方法上的 @Scheduled 不会报错,也不会执行,属于「静默失效」,只能通过日志一直不出现来发现。

JobRepository 就是一个用 JdbcTemplate 查任务表的类,写法见第三篇。把待处理数量查出来而不是写死,日志才能在任务堆积时给出真实信号。

要并发执行多个定时任务,配置调度器的线程数。Spring Boot 提供了 spring.task.scheduling.pool.size,设成 2 或 4 就够大多数场景。也可以自己定义一个 ThreadPoolTaskScheduler bean,把线程名前缀改成 sched-,这样日志里能一眼区分是哪个调度器。

fixedDelay 和 fixedRate 的区别必须分清。前者是「上一次结束后再等 N 毫秒」,任务耗时不会累积;后者是「按固定频率触发」,如果任务耗时超过间隔,下一次会被推迟甚至堆积。清理、扫描这类任务用前者,指标采集这类要求均匀间隔的用后者,但必须保证任务耗时小于间隔。

cron 表达式还要注意时区。默认用 JVM 的时区,容器里通常是 UTC,你在本地写「每天凌晨两点」,线上可能变成北京时间上午十点。要么显式指定 zone,要么把容器时区统一,别靠默认值猜。这个坑在第六篇部署里会再提一次。

定时任务默认在单实例上跑。部署两台机器后,同一个任务会在两台各跑一次,如果它做的是「给用户发提醒」,用户就会收到两条。多实例下要么加分布式锁,要么把任务拆成独立进程,这一点在第六篇讲部署时还会提到。

重启丢任务:内存队列的天生缺陷

把任务放进 ThreadPoolTaskExecutor 的队列,队列在 JVM 堆里。进程正常退出,队列里的任务不会自动落盘;进程被杀,更是直接消失。提交方如果只拿到一个自增 id,重启后连「这个 id 对应什么」都查不到,于是任务既没执行,也无法重试。

小规模可以先用「任务表」补:提交时先往数据库插一条 pending 记录,再用异步线程执行,成功后改成 done,失败改成 failed 并记录重试次数。启动时扫一遍 pending 和超时的 running,重新入队。代价是多两次数据库写入,好处是状态可查、重启可恢复。

任务表方案只适合单实例或简单多实例。多实例下「谁扫、扫到谁、怎么防止重复执行」会变得复杂,需要抢占标记、租约、心跳。到这一步,继续在应用里造轮子就不划算了,该换成消息队列。

消息队列(message queue)是一个独立于应用的中间件,生产者把任务写进去,消费者从里面取。它的核心价值是持久化、解耦和削峰:应用重启不影响队列里的消息,消费者可以横向加机器,突发流量先堆在队列里慢慢消化。常见选择是 RabbitMQ 和 Redis Stream,前者功能完整,后者胜在已经有 Redis 时不用再运维一套。

换消息队列的触发条件很具体,满足任意两条就该考虑:任务不能丢,重启后必须还能跑;需要跨多个实例分担;失败要自动重试并记录次数;有明显的流量峰值,需要削峰;任务要延迟执行或定时执行。只满足「想解耦」一条,不值得多运维一个中间件。

从任务表迁到消息队列,常用的过渡是「本地事务加发件箱」:业务数据和任务记录在同一个事务里写进数据库,再由一个独立的投递进程把记录搬到队列。这样即使消息发送失败,记录还在,可以重试;缺点是投递有延迟,需要接受最终一致,而不是「提交后立刻进队列」。

RabbitMQ 和 Redis Stream 的方案未在本机实测。本文实测的是 @Async 默认执行器、任务线程名、@Scheduled 的日志和 202 返回。消息队列的代码结构按各自官方客户端写法给出,落地前需要单独验证。

优雅停机:让任务跑完再退出

默认情况下,进程收到停止信号会尽快退出,正在执行的任务被中断,队列里的任务直接丢弃。Spring Boot 提供了优雅停机:server.shutdown=graceful,配合 spring.lifecycle.timeout-per-shutdown-phase 设置等待时间。开启后,容器先停止接新请求,再等正在处理的任务结束,超时才强制退出。

server:
  shutdown: graceful
spring:
  lifecycle:
    timeout-per-shutdown-phase: 30s

优雅停机对 Web 请求有效,对 @Async 任务的覆盖取决于执行器是否被正确关闭。Spring 会调用执行器的 shutdown,等待队列里的任务跑完,但等待时间受上面那个超时约束。任务如果跑了五分钟,超时三十秒后照样被杀,所以长任务要自己处理中断:捕获 InterruptedException,保存进度,下次启动继续。

还有一个容易忽略的点:@Async 方法里如果再起线程、再提交任务,或者用了第三方客户端的线程池,优雅停机管不到它们。停机时要自己关闭这些资源,否则进程退了,后台线程还在写文件,可能留下半个文件。

停机顺序也影响结果。先摘流量,再等 Web 请求结束,最后等后台任务;如果顺序反过来,新的请求还会进来,永远等不完。Kubernetes 的 preStop 和 readiness 探针就是用来控制这个顺序的,具体配置在下一篇展开。

任务出问题时先看什么

下面这张表按现象查。前四行覆盖「没执行、执行慢、重复执行、重启丢失」,后四行覆盖线程池和上下文问题。看日志时先找线程名,它能告诉你任务到底跑在哪个池子里。

现象真实原因第一步查什么
@Async 方法实际同步执行同类自调用,或没加 @EnableAsync看调用是否跨 bean、启动类注解
线程名 task-1、task-2 一路递增用了默认执行器,每次新建线程看是否配置了 TaskExecutor bean
多个定时任务互相等待调度器默认只有一个线程看日志线程名是否都是 scheduling-1
重启后任务消失队列在内存,没有持久化看任务状态表和启动时的补偿逻辑
@Async 返回 void,失败无感知异常没有处理器,被吞掉配 AsyncUncaughtExceptionHandler
突发流量后接口整体变慢队列无界或拒绝策略阻塞调用线程看队列容量、拒绝策略和线程数
停机时任务被强杀任务耗时超过停机等待时间看 timeout-per-shutdown-phase
异步线程拿不到登录用户ThreadLocal 不跨线程传递看安全上下文和 MDC 是否手动传递
异步方法里的写操作没回滚异步执行不在原事务里看事务边界与提交时机

前三行经常同时出现。一个项目既没配执行器,又在同类里自调用,日志里线程名一直是 http-nio-8081-exec-1,那就根本没异步。先确认「有没有真的换线程」,再谈线程池参数,顺序不能反。

边界与代价

线程池不是越大越好。线程的代价包括栈内存、上下文切换和 GC 扫描,几百个线程听起来不多,实际会让延迟抖动明显。按任务类型定:IO 密集用核心数乘 2 起步,CPU 密集用核心数加 1 起步,然后压测看队列和拒绝次数,不要凭感觉翻倍。

队列容量是内存风险。每个排队任务都持有参数、闭包和上下文,队列 10 万、每个任务一兆,就是一百兆堆内存。无界队列更危险,它不会拒绝,只会把内存吃光,最后整个进程 OOM。给队列设上限,并想清楚满了之后丢谁,这是必须提前做的决定。

异步还会切断上下文。请求线程里的用户信息、trace id、事务、MDC 日志字段,都不会自动带到任务线程。安全上下文要手动取出来再传进去,trace id 要显式塞进任务参数,事务要在任务内部重新开。忘了传,日志里就只剩一个孤零零的 job id,出了问题无法关联到原始请求。

任务表方案也有边界。表会越来越大,需要定期归档;扫描频率高会加数据库压力;多实例抢占要处理锁和重复执行。它适合任务量每天几千到几万、团队不想引入中间件的阶段。到每天百万级、或者任务本身要跨系统协作,消息队列的运维成本反而更低。

应用内异步与任务表

不用新中间件,代码量小,状态直接查数据库。适合单实例、任务量不大、能接受重启后短暂延迟的场景。代价是扩展性有限,多实例要自己做抢占。

消息队列

持久化、削峰、重试、多消费者都是现成的,应用重启不影响任务。适合任务不能丢、流量有峰值、要多实例分担的场景。代价是多一套中间件要运维和监控。

最后是观测。异步任务最大的风险不是慢,而是「悄悄没跑」。至少要有三个指标:提交数、成功数、失败数,以及队列积压和任务耗时。没有这些,任务丢了只能等业务方来问。日志里 job id 要全程带上,从提交到完成能串起来。

当天能自己验证的练习

  1. 不配执行器,连续提交十个任务,观察日志里线程名从 task-1 递增,记录最大编号。
  2. 加上 @Async("jobs") 和核心 4 的配置,再提交十个任务,确认线程名只在 job-1 到 job-4 之间循环。
  3. 把 sweep() 改成 sleep 10 秒,再加一个每 2 秒触发的任务,观察两者是否在 scheduling-1 上排队。
  4. 提交一个 sleep 30 秒的任务后立刻停服务,把 timeout-per-shutdown-phase 设成 5 秒,确认任务被打断且日志留下中断记录。
  5. 写一个会抛异常的 @Async void 方法,确认调用方无感,再配 AsyncUncaughtExceptionHandler 看异常是否被记录。

小结

三句话收束:@Async 必须配自己的线程池,默认执行器每次新建线程;@Scheduled 默认单线程,任务会互相排队;内存队列重启就丢,任务不能丢时要么落任务表,要么上消息队列。

下一篇讲上线。任务跑在进程里,进程最终要部署到服务器或容器里,配置怎么外置、日志怎么滚动、健康检查怎么设计、Tomcat 线程数怎么定,都会直接影响这些后台任务能不能稳定跑完。那篇从「健康检查通过但数据库已经挂了」讲起。