主题
定时任务与异步
一句话:业务只实现
JobHandler,Quartz 的JobHandlerInvoker负责取参数、写任务日志、失败重试;@TenantJob让一个任务按租户循环执行,@Async则靠 TTL 装饰器把登录态与租户带进线程池。
适用场景:新增一个定时任务;排查「任务没跑」「跑了两次」「日志只有半边」;写异步方法时上下文丢失。
不适用场景:一次性延迟任务(用 MQ 延迟消息或 stream);分布式任务的抢占(Quartz 的并发控制按 JobDetail,不是业务锁)。
1. 一条任务的三个角色
| 角色 | 类 | 作用 |
|---|---|---|
| 业务实现 | JobHandler#execute(String param)(#L8-L18) | 只写业务,返回字符串作为执行结果 |
| Quartz 壳 | JobHandlerInvoker(#L29) | 取 JobDataMap、写日志、调 handler、处理重试 |
| 调度管理 | SchedulerManager | add/update/pause/resume/trigger/delete,封装 Quartz API |
1.1 JobHandlerInvoker 做了什么
executeInternal(#L38-L66):
- 从
JobDataMap取JOB_ID、JOB_HANDLER_NAME、JOB_HANDLER_PARAM、refireCount、retryCount、retryInterval(#L40-L45); - 先落一条 RUNNING 日志:
jobLogFrameworkService.createJobLog(jobId, startTime, handlerName, param, refireCount + 1)(#L54),executeIndex就是第几次执行; executeInternal(name, param)通过applicationContext.getBean(jobHandlerName, JobHandler.class)拿到 Bean(#L70),所以 Bean 名必须等于任务配置里的 handlerName;finally里updateJobLogResultAsync回填结果(#L62);- 异常交给
handleException(#L93-L111)。
重试语义(#L93-L111):refireCount >= retryCount 时抛 JobExecutionException 结束;否则 sleep(retryInterval) 后 throw new JobExecutionException(exception, true)——第二个参数 true 表示立即重新触发,不是按原 cron 等下一轮。
@DisallowConcurrentExecution(#L26)保证同一个 JobDetail 不会并发执行;@PersistJobDataAfterExecution(#L27)让 refireCount 能跨重试保留。
1.2 JobLog 落库
JobLogServiceImpl:
createJobLog插入status=RUNNING的记录并返回 ID(#L29-L37);updateJobLogResultAsync带@Async(#L40),回填 endTime、duration、status、result(#L39-L51),失败只记日志不影响调度;- 日志清理
cleanJobLog(exceedDay, deleteLimit)(#L55-L68)按批删,deleteCount < deleteLimit就停,避免长事务。
因为 create 是同步、update 是异步,看到 RUNNING 不代表任务卡住,可能只是回填线程还没写完;判断卡住要看 startTime 与 monitorTimeout。
2. 注册与调度
JobServiceImpl#createJob(#L45-L69)的顺序值得记:
- 校验 cron(
#L48); - 按 handlerName 查重(
#L50-L52,同名任务只能有一个); validateJobHandlerExists:SpringUtil.getBean(handlerName),不是JobHandler抛类型错,找不到抛「Bean 不存在」(#L94-L104);- 先插 DB(
status=INIT),再schedulerManager.addJob(...)(#L63-L64),最后把状态改成NORMAL(#L66-L67)。
「先库后调度」的好处是失败可补偿:syncJob()(#L140-L158)会删掉所有 Quartz 任务再按库重建,STOP 状态的重建后补一次 pause。
SchedulerManager 用 handlerName 同时作为 JobKey 与 TriggerKey(#L13-L17),这就是「同名任务只能一个」的根因。addJob 里 JobBuilder.newJob(JobHandlerInvoker.class).withIdentity(jobHandlerName)(#L45-L48),业务类本身不注册进 Quartz。
状态约束:只有 NORMAL 的任务能改配置(#L78-L80 抛 JOB_UPDATE_ONLY_NORMAL_STATUS),因为暂停状态下改 Quartz 会让任务意外开始执行。
3. @TenantJob:一个任务跑遍所有租户
TenantJobAspect(#L34-L56):
java
tenantIds.parallelStream().forEach(tenantId ->
TenantUtils.execute(tenantId, () -> joinPoint.proceed()));- 并行流,每个租户独立上下文(
TenantUtils.execute内部强制setIgnore(false)并在结束后还原); - 每个租户的结果/异常分别收集(
#L49-L52),最后返回 JSON Map(#L56);某个租户失败不会中断其它租户; - 因此日志里的一条记录实际包含 N 个租户的执行结果。
硬性要求:业务必须幂等。因为重试是「整个 JobDetail 重跑」,已经成功的租户会再跑一遍(源码类注释明确写了这一点)。示例见 pmforge-module-system/.../job/DemoJob.java#L19-L25:方法上标 @TenantJob,内部直接 adminUserMapper.selectList(),靠租户拦截器自动隔离。
反向场景:全局任务(如清理所有租户的过期日志)不要加 @TenantJob,而应加 @TenantIgnore 跳过租户条件——JobLogCleanJob#L33 就是这样,配合常量 JOB_CLEAN_RETAIN_DAY=14(#L25)、DELETE_LIMIT=100(#L30)。
4. @Async 与线程池
PmforgeAsyncAutoConfiguration(#L15-L16)只做两件事:@EnableAsync + 给容器里已有的线程池装 TTL 装饰器(#L19-L43),把 ThreadPoolTaskExecutor 与 SimpleAsyncTaskExecutor 的 TaskDecorator 设为 TtlRunnable::get。
它不定义线程池,所以默认用的是 Spring Boot 的 applicationTaskExecutor(spring.task.execution.*),项目 yaml 里没有覆盖,即默认 8 个核心线程、无界队列。
由此带来的约定:
@Async方法要 public、不能同类自调用(Spring 代理限制);- 上下文(
LoginUser、TenantContextHolder)能传过去,是因为 TTL 装饰器 +TransmittableThreadLocalSecurityContextHolderStrategy(安全 starter 里SecurityContextHolder.setStrategyName); - 但事务不会传:异步方法里查不到调用方未提交的数据;需要「提交后再做」就用
TransactionSynchronizationManager或 MQ。
现成用法:ApiAccessLogCommonApi#L27、OperateLogCommonApi#L27、JobLogServiceImpl#L40。
5. 本地如何触发一次
管理后台:PUT /admin-api/infra/job/trigger?id=xxx,权限点 infra:job:trigger(JobController#L94-L97)。
底层链路:JobService#triggerJob(#L131-L138)校验任务存在 → SchedulerManager#triggerJob(#L121-L130)手动塞 JOB_ID/JOB_HANDLER_NAME/JOB_HANDLER_PARAM 后 scheduler.triggerJob(new JobKey(handlerName), data)。
注意手动触发不带 retryCount/retryInterval(#L125-L128),所以失败不会重试;cron 仍按原计划继续。
本地开发也可以直接调 Handler Bean,但会绕过任务日志,只适合验证业务逻辑。
⚠️ local 配置默认没有 Scheduler:application-local.yaml#L10 把 QuartzAutoConfiguration 放进了 spring.autoconfigure.exclude(注释「默认 local 环境,不开启 Quartz 的自动配置」)。因此在 local 下打开任务管理页点「执行」会得到 NOT_IMPLEMENTED;要么切到 dev profile,要么从 exclude 里去掉这一行。
6. 集群部署注意
application-dev.yaml 里的 Quartz 配置(#L70-L95)已经按集群来配了:job-store-type: jdbc(#L73)、LocalDataSourceJobStore(#L85)、isClustered: true(#L86)、clusterCheckinInterval: 15000(#L87)、wait-for-jobs-to-complete-on-shutdown: true(#L74)、threadCount: 25(#L91)、initialize-schema: NEVER(#L95,表结构要手工初始化)。
在此之上还要注意:
- 并发控制靠
@DisallowConcurrentExecution,它约束的是同一个 JobDetail,前提是各节点连同一个 Quartz 库;如果换成内存 JobStore,每个节点会各跑一份。 TenantJobAspect用parallelStream,在容器里默认走 ForkJoinPool.commonPool;租户很多时会把公共池打满,影响同一 JVM 的其它并行流。需要限流就给任务加自己的线程池,或在 handler 内串行。- 任务日志的 create 是同步的,集群下每个节点都会写自己的记录,
executeIndex=1不代表「全局第一次」。 syncJob()会短时间删除并重建全部 Trigger,集群滚动发布时不要频繁调用。- 长任务要考虑
monitorTimeout(默认 0,见JobServiceImpl#L209-L213),否则「卡住」只能靠人工看日志。
7. 排错清单
| 症状 | 先看 | 判断依据 |
|---|---|---|
| 任务建了但不跑 | JobServiceImpl#L63-L67 | DB 状态是否 NORMAL;Quartz 是否 pause;cron 是否合法 |
| local 点「执行」报 501 | application-local.yaml#L10 | local 默认排除了 Quartz 自动配置,没有 Scheduler |
| 启动报 handler 不存在 | #L94-L104 | Bean 名与任务配置的 handlerName 不一致,或没加 @Component |
| 任务跑了两次 | @DisallowConcurrentExecution、JobStore | 集群各节点独立 JobStore;或手动 trigger 与 cron 撞车 |
| 日志一直 RUNNING | JobLogServiceImpl#L39-L51 | 异步回填失败(只记日志);或任务真的卡住 |
| 重试次数不对 | JobHandlerInvoker#L93-L111 | refireCount 从 JobDataMap 来;手动触发不带重试参数 |
| 某租户数据串了 | TenantJobAspect#L44-L52 | handler 内自己开了线程且没走 TenantUtils;或误加 @TenantIgnore |
| 部分租户成功、部分失败 | TenantJobAspect#L49-L52 | 每个租户结果独立,重跑会全部重来 → 必须幂等 |
| 异步方法里租户为空 | PmforgeAsyncAutoConfiguration#L19-L43 | 线程池不是 Spring 管理的,装饰器没生效 |
| 异步方法查不到刚写的数据 | 事务边界 | 主事务未提交,异步线程读不到 |