Spring定时任务这块我用Scheduled做了大概三四年从最早的简单定时跑批到后来对接动态cron、多实例部署防重踩过的坑基本能凑一桌。标题就一个Spring定时任务 Scheduled使用看着简单但真正用好了其实有不少门道。这篇就按我实际项目的使用路径把注解的常规用法、参数语义、执行原理、动态配置还有那些文档里不会明说的坑一次捋清楚。1. 从一段最简代码说起Scheduled到底解决了什么问题1.1 五分钟就能跑起来的定时任务先摆一段最基础的用法。你在Spring Boot工程里随便写一个类方法上标个Scheduled再把类交给Spring容器管理任务就能跑起来Component public class StockSyncJob { private static final Logger log LoggerFactory.getLogger(StockSyncJob.class); // 每5秒执行一次 Scheduled(fixedRate 5000) public void syncStock() { log.info(同步库存任务开始时间{}, LocalDateTime.now()); // 这里写实际的业务逻辑比如调用外部仓储接口、更新本地表 } }只要主启动类上有EnableSchedulingSpring Boot项目中其实是自动装配但手动加上更明确这个任务到点就会执行。很多团队第一次引入定时任务就是用这种方式零配置、无侵入直接把原本在业务代码里用Timer或者while(true)sleep写在最里层的那个脏活干净利落地摘了出来。1.2 它和Timer、Quartz的关系有人会问JDK自带的Timer不也能做定时吗为什么非得用Spring的我个人的理解是Timer的问题在于单线程串行执行一个任务卡住其他任务全部排队等待这在复杂业务里基本是不可接受的。Quartz功能全但重配置繁琐小项目引入它有点杀鸡用牛刀。Spring的Scheduled恰好落在中间轻量、声明式、跟Spring生态无缝集成绝大多数业务场景的定期做点什么的需求它都覆盖得了。还有一个容易被忽略的点Scheduled本身不依赖Web容器哪怕你是个纯后端的消费者服务、批处理服务只要Spring容器在跑定时任务就能执行。这对微服务架构下做每个服务各自的数据归档、缓存刷新、对账补偿这类逻辑特别合适。2. 三种触发方式别等到上线才发现用错了Scheduled最常见的有三种参数fixedRate、fixedDelay、cron。很多人只记住了都能定时执行但它们的语义完全不同选错了在特定场景下会造成任务堆积或者执行时间不符合预期。2.1 fixedRate固定频率重试型的任务别用它fixedRate表示固定速率执行单位毫秒。它的语义是从任务开始执行那一刻算起每间隔指定时间就触发下一次执行。注意这里的关键是开始时间间隔不是结束到下次开始。举例来说Scheduled(fixedRate 5000) public void doSomething() { // 假设这个方法耗时3秒 }上面的配置每5秒执行一次但因为方法本身耗时3秒实际执行时间线大致是0s开始3s结束第5s开始第8s结束第10s开始……也就是说两次执行的开始时间间隔是5秒。如果任务耗时超过了间隔时间呢比如方法耗时8秒配置fixedRate5000那么执行会变成0s开始8s结束紧接着第10s开始。注意这里没有跳过一说Spring的默认调度器会尽量补上错过的执行但这取决于线程池配置后面讲线程池会细说。fixedRate适合的场景是你关心的是单位时间内的执行次数比如定时拉取行情快照、定时刷新热点数据缓存。不适合的场景是任务本身不稳定、可能阻塞或长时间运行。一旦任务卡住fixedRate会导致任务积压处理起来很头痛。2.2 fixedDelay固定延迟跑批任务的标配fixedDelay表示固定延迟单位毫秒。语义完全反过来上一次任务执行结束之后再过指定时间才开始下一次执行。Scheduled(fixedDelay 5000) public void doSomething() { // 这段逻辑执行了8秒 }它的执行线是0s开始8s结束休息5s第13s开始第21s结束第26s开始。也就是说不管任务本身跑多久两次执行之间至少间隔5秒。这个语义天然适合数据同步、账单生成、报表汇总、邮件推送这类必须等上一次彻底结束才能跑下一次的任务。它天然避免了任务重叠执行的问题。我自己的习惯是默认优先用fixedDelay除非有明确的频率要求才换fixedRate。2.3 cron表达式灵活的日历级调度cron表达式提供了最灵活的配置方式精确到秒级支持指定星期、月份、复杂组合。Spring的cron是6段格式秒 分 时 日 月 周跟Unix系统cron5段不一样别搞混了。常见表达式参考表达式含义0 0 2 * * ?每天凌晨2点执行0 0/30 9-18 * * ?每天9点到18点之间每30分钟执行一次0 0 12 * * MON-FRI每周一到周五中午12点执行0 15 10 ? * MON#1每月第一个周一上午10:15执行0 0 0 1 1 ?每年1月1日0点执行Spring cron里用?表示不指定值*表示每。日和周是互斥的两者不能同时指定具体值这就是为什么经常能看到0 0 2 * * ?这种写法——日用了*周就必须用?。cron适合业务上有明确的几点几分要求的场景。但要注意用cron的时候一旦服务器时间不准、或者应用容器所在时区不对任务执行时间就会出现偏差这个坑放到后面细说。2.4 三种方式的选型判断逻辑用一个表格把思路收拢一下方便你在设计阶段做判断参数语义核心适用场景风险点fixedRate固定开始间隔高频缓存刷新、心跳任务重叠可能积压fixedDelay固定结束间隔批处理、同步、补偿频率不稳定周期执行时长延迟cron日历级精确调度业务明确时间点时区、宕机恢复、表达式写错选型逻辑其实就一句话这个任务允不允许重叠执行允许多少次是否依赖固定的业务时间点搞清楚了选型就不会错。3. 线程池配置大多数定时任务故障的根源3.1 默认单线程所有任务排队等待虽然Scheduled的注解用起来简单但它的默认执行器其实是个单线程的ScheduledExecutorService。这意味着一旦你在一个应用里写了两个定时任务默认情况下它们是串行执行的一个任务阻塞了另一个任务就得等它结束才能跑。我遇到过一个非常典型的故障两个任务一个是每天凌晨的资源清理一个是每隔几分钟的心跳上报。正常情况下没冲突但某天资源清理任务因外部接口超时卡住了20分钟结果心跳上报也停了20分钟最后监控系统判定服务异常直接误报工单。排查到最后根因就是默认单线程四个字。3.2 自定义线程池的两种方式方案一实现SchedulingConfigurer接口自定义TaskScheduler。Configuration public class SchedulingConfig implements SchedulingConfigurer { Override public void configureTasks(ScheduledTaskRegistrar taskRegistrar) { taskRegistrar.setScheduler(taskScheduler()); } Bean(destroyMethod shutdown) public Executor taskScheduler() { ThreadPoolTaskScheduler scheduler new ThreadPoolTaskScheduler(); scheduler.setPoolSize(10); scheduler.setThreadNamePrefix(schedule-task-); scheduler.setWaitForTasksToCompleteOnShutdown(true); scheduler.setAwaitTerminationSeconds(60); scheduler.setRejectedExecutionHandler(new ThreadPoolExecutor.CallerRunsPolicy()); scheduler.initialize(); return scheduler; } }方案二直接配置ThreadPoolTaskScheduler为Spring BeanSpring Boot会自动用它作为默认调度器。Bean public TaskScheduler taskScheduler() { ThreadPoolTaskScheduler scheduler new ThreadPoolTaskScheduler(); scheduler.setPoolSize(5); scheduler.setThreadNamePrefix(spring-task-); return scheduler; }两种方式区别不大我更推荐方案二简单直观。setWaitForTasksToCompleteOnShutdown(true)这个配置值得留意应用关闭时它会给正在执行的任务一个缓冲时间避免任务执行到一半被强行干掉导致数据不完整。setAwaitTerminationSeconds(60)设置最多等60秒。3.3 线程池大小怎么定线程池大小没有标准答案核心考虑因素是你有多少个定时任务其中有多少个可能长时间阻塞我的经验公式任务数 5池大小设5~10就够任务数较多但大部分是快任务秒级内结束池大小设任务数的50%~100%存在慢任务分钟级单独隔离线程池避免慢任务占用公共调度线程CallerRunsPolicy这个拒绝策略特别适合定时任务。默认的AbortPolicy在线程池满的时候会抛异常直接导致任务丢失CallerRunsPolicy则会让提交任务的线程调度线程自己执行这个任务虽然可能会造成短暂阻塞但至少任务没丢。对批处理性质的定时任务来说任务不丢才是底线。4. 动态定时任务配置不写死在注解里Scheduled注解里的cron值是编译期常量改一次调度周期就得改代码、重新部署。在实际业务里很多场景要求运行期动态调整比如运营后台手动设置每5分钟拉一次和每30分钟拉一次或者灰度阶段对某个任务动态启停。4.1 基于SchedulingConfigurer的动态cron实现一个比较通用的做法是实现SchedulingConfigurer接口在configureTasks里注册一个Runnable并从配置中心动态读取cron表达式Component public class DynamicScheduleTask implements SchedulingConfigurer { Override public void configureTasks(ScheduledTaskRegistrar taskRegistrar) { taskRegistrar.addTriggerTask( // 实际执行的任务逻辑 () - System.out.println(执行动态任务 LocalDateTime.now()), // 触发器每次执行前动态获取cron triggerContext - { // 从配置中心、数据库或接口动态获取cron String cron getCronFromConfig(); if (StringUtils.isEmpty(cron)) { // 返回null表示不调度 return null; } CronTrigger trigger new CronTrigger(cron); return trigger.nextExecutionTime(triggerContext); } ); } private String getCronFromConfig() { // 这里可以从数据库、Apollo、Nacos等配置中心读取 // 为了演示简单写死一个示例 return 0 */5 * * * ?; } }关键点在于Trigger接口的nextExecutionTime会在每次任务执行前被调用。所以只要getCronFromConfig()每次从配置中心拿到最新的cron下一次调度就会用新周期。这个方案我用了很久稳。4.2 基于线程池的动态任务启动与暂停另一个场景是动态启停单个任务。ScheduledTaskRegistrar登记的任务可以在外部持有一个ScheduledTask引用然后通过cancel()来取消Component public class ManualControlTask { private ScheduledTask scheduledTask; Autowired private ThreadPoolTaskScheduler taskScheduler; public void start() { scheduledTask new ScheduledTask( taskScheduler.schedule(this::executeTask, new CronTrigger(0 0/10 * * * ?)) ); } public void stop() { if (scheduledTask ! null) { scheduledTask.cancel(); } } private void executeTask() { System.out.println(手动控制的定时任务执行 LocalDateTime.now()); } }这里我封装了一个ScheduledTask对象实际底层是ReschedulingRunnable。cancel()执行后当前任务会被取消。需要注意如果任务正在执行中取消不会中断当前执行只会阻止后续执行。4.3 为什么优先用Trigger而不是重新new ScheduledTask很多人刚接触动态任务时会想着把Scheduled方法改成通过代码手动taskScheduler.schedule()来调度这完全可以但你得自己管理任务的注册和取消。用Trigger接口则更优雅Spring框架会在每次执行前自动查询新的触发时间你不需要操心任务生命周期的维护。这个方案的唯一代价是cron是从外部读的如果配置中心短暂不可用任务调度可能会受影响。所以我的建议是在getCronFromConfig()里加一层本地缓存兜底配置中心读不到就用上一次成功的值而不是直接返回null导致任务停摆。5. 实战中的高发踩坑点与排查技巧5.1 时区问题凌晨2点的任务为什么下午2点跑Scheduled(cron0 0 2 * * ?)默认使用服务器默认时区。如果你的服务器时区是UTC很多云服务器默认如此凌晨2点执行就变成了北京时间下午2点执行。这是个非常隐蔽的坑线上环境特别容易踩。解决方式在cron注解里指定时区。Scheduled(cron 0 0 2 * * ?, zone Asia/Shanghai) public void dailyReport() { // ... }如果使用了动态cron则在CronTrigger构造时指定时区CronTrigger trigger new CronTrigger(cron, TimeZone.getTimeZone(Asia/Shanghai));我建议统一在配置中心设置服务器时区不再依赖默认值。5.2 事务失效定时任务里的Transactional容易踩空Scheduled方法上直接加Transactional时事务是生效的但有一个前提方法的执行和事务的提交要在同一个线程里。如果你在定时任务里内部调用了另一个方法自调用事务注解会失效因为Transactional本质上是代理机制同一个类内部的this.method()调用不会经过代理对象。示意图式说明A类的task()方法标了TransactionalA类的另一个方法taskInternal()也标了Transactional。task()直接调用this.taskInternal()后者的事务不会生效。解决办法把事务方法拆到单独的Bean里面通过注入的代理对象调用或使用TransactionTemplate编程式事务Service public class OrderJobService { Autowired private TransactionTemplate transactionTemplate; public void processOrder() { transactionTemplate.execute(status - { // 事务内的操作 return null; }); } }在定时任务这种没有外部请求上下文的场景里编程式事务反而是最直观、最可控的方案。5.3 任务重叠fixedRate长耗时导致的并发问题前面提过fixedRate在任务耗时超时时可能造成任务重叠。Spring默认的ScheduledExecutorService不会主动阻止同一个任务的并发执行。也就是说一个任务还没跑完下一次触发又进来了两个线程同时执行同一段逻辑如果这段逻辑有数据库读写、状态更新就可能出现数据不一致。预防手段尽可能使用fixedDelay替代fixedRate从语义上避免重叠如果需要更保险用分布式锁或者单机锁包住任务核心逻辑使用ScheduledSchedulerLock这类库来控制执行权简单的单机锁写法Scheduled(fixedDelay 5000) public void runJob() { // 尝试获取锁拿不到就跳过 if (!tryLock()) { return; } try { // 实际业务逻辑 } finally { releaseLock(); } }5.4 集群部署同一个任务被多实例重复执行一旦应用做了多实例部署所有实例上的Scheduled都会同时触发同一份任务逻辑会被执行N次。对幂等的读操作无所谓但对写操作、推送操作可能就是事故。推荐的解决方案有引入分布式调度平台如ElasticJob、XXL-JOB由调度平台控制单次执行使用分布式锁Redis、Zookeeper保证同一时间只有一个实例执行数据库层面加行锁或者唯一键约束做防重最轻量的做法是Redis分布式锁。核心思路任务执行前尝试向Redis写入一个带过期时间的key只有写入成功的实例才继续执行。Scheduled(fixedDelay 10000) public void execute() { // 使用Redis客户端6秒内只有1个实例能拿到锁 Boolean lock redisTemplate.opsForValue().setIfAbsent(job:stockSync:lock, 1, Duration.ofSeconds(6)); if (Boolean.FALSE.equals(lock)) { return; } try { // 业务执行 } finally { redisTemplate.delete(job:stockSync:lock); } }锁的过期时间要大于任务的最大执行时长否则会出现锁提前释放、两个实例同时执行的情况。多实例场景下这是必须考虑的设计点。5.5 任务执行异常的静默吞掉问题Scheduled方法如果抛出异常默认情况下异常会记录在调度线程的日志里但不会影响下一次执行。也就是说Spring不会因为上次执行失败就停掉这个任务这是好事。但问题在于如果你在任务方法里try-catch把异常吞掉且不加日志这个任务就变成永远在失败但没人知道。我的习惯不吞异常让异常抛出统一被全局异常处理器或日志框架记录或者在catch块里打完整的错误日志包含任务名、参数、异常堆栈建议增加执行状态记录比如在数据库记录每次执行的时间、状态、耗时方便排查给一个建议的日志记录框架Scheduled(fixedDelay 60000) public void report() { long start System.currentTimeMillis(); try { // 执行逻辑 log.info(任务执行成功耗时{}ms, System.currentTimeMillis() - start); } catch (Exception e) { log.error(任务执行失败耗时{}ms, 错误{}, System.currentTimeMillis() - start, e.getMessage(), e); } }5.6 任务执行时间不准延迟与补偿Scheduled不是绝对精准的调度器它基于JVM的调度线程当系统负载高、发生GC停顿、线程池队列满时任务执行时间可能延迟数秒甚至更久。如果业务对时间精度要求极高比如秒级抢购、准点推送Scheduled不是最合适的工具。这种情况下可以考虑引入时间轮调度、或者直接上分布式调度平台。但对大多数业务场景来说秒级或分钟级的延迟是可以接受的。此外Spring对错过的任务有个默认策略。如果应用在任务执行期间挂了重启后会根据配置决定是否补跑之前的任务。默认情况下周期性任务在应用重启后不会补偿执行除非配置了任务持久化这点在需要账不能少的财务类任务里要特别注意——必要时设计一个启动时的数据补偿逻辑。6. 工程落地一个小而全的定时任务项目结构参考按我的经验一个规范的定时任务模块应该包含这几块任务定义、调度配置、执行状态记录、错误隔离。6.1 模块划分com.example.project.job ├── config │ └── SchedulerConfig.java // 线程池配置 ├── job │ ├── StockSyncJob.java // 实际任务逻辑 │ └── OrderTimeoutJob.java ├── record │ ├── JobExecutionLog.java // 任务执行日志实体 │ └── JobExecutionLogRepository.java └── support ├── JobLockService.java // 分布式锁 └── DynamicCronTask.java // 动态任务任务逻辑与调度配置分离这个基本原则能让后续维护省很多心。6.2 任务执行日志表设计一个简单的任务执行记录表字段包括任务名称、执行开始时间、执行结束时间、执行状态成功/失败、异常信息、执行机器IP。这样任何一次异常都能快速定位到是哪个实例、哪次执行出了什么问题。CREATE TABLE job_execution_log ( id BIGINT AUTO_INCREMENT PRIMARY KEY, job_name VARCHAR(128) NOT NULL, start_time DATETIME NOT NULL, end_time DATETIME, status VARCHAR(16) NOT NULL, error_msg TEXT, host_ip VARCHAR(32), create_time DATETIME DEFAULT CURRENT_TIMESTAMP ) ENGINEInnoDB DEFAULT CHARSETutf8mb4;6.3 启动时的补偿任务如果任务很重要建议在应用启动时检查上次执行记录如果发现上次执行失败或未执行触发一次补偿。这样即使应用在凌晨2点任务执行前宕机了重启后也能自动补上。Component public class StartupCompensationJob implements ApplicationRunner { Override public void run(ApplicationArguments args) { // 检查上次任务执行记录如果失败则重新执行 // 这种方式比单纯依赖调度器的补偿机制更可控 } }6.4 与配置中心对接的完整示例把所有外部可变的调度参数放配置中心而不是写死在注解里。比如Scheduled(cron ${job.daily-report.cron:0 0 2 * * ?}, zone ${job.daily-report.zone:Asia/Shanghai}) public void dailyReport() { // ... }通过占位符的方式让运维在配置中心直接修改cron表达式的值不用动代码、不用重新发布。这是项目上线后最实用的优化之一比动态Trigger实现简单得多覆盖了大部分不想重新发版改调度周期的需求。7. 一个实际项目的排障实录最后分享一个我亲手处理过的案例帮助你把前面的知识点串起来。某服务的定时任务突然不执行了原有任务是每天早上8点生成前一天的销售报表。现象应用还活着接口正常返回但报表数据连续两天没有更新。排查步骤第一步先看任务日志。日志系统里完全没有这个任务的任何记录连启动时的任务开始执行都没有。说明任务从未被触发。从日志现象可以推断问题出在spring-context调度那层而不是业务代码。第二步检查线程池状态。用jstack抓线程栈发现调度线程池的线程全部阻塞在数据库连接获取上。进一步检查原来是前一天上线的新任务里有一个Transactional方法执行了一个慢SQL把数据库连接池打满了。这个慢任务占据连接不释放后续所有任务在获取数据库连接时全部阻塞调度线程满员其他定时任务根本无法启动。第三步解决。把那个慢SQL优化掉同时把所有定时任务的线程池配置做了治理慢任务单独放一个线程池快任务默认线程池互不影响快任务池和慢任务池都用独立的数据库连接池配置避免互相拖垮。第四步预防。给所有定时任务加执行超时熔断单次执行超过设定阈值就主动中断并记录告警。从此这类一个任务拖垮全部任务的问题基本不再出现。这个案例的关键教训是定时任务的故障往往不是任务本身写错了而是任务和公共资源之间的耦合。线程池、数据库连接池、外部接口任何一个被某个慢任务占死所有任务都会陪葬。8. 我最后想啰嗦的三件事第一Scheduled很简单但不代表可以随便用。每次新增一个定时任务前先过一遍线程池够不够任务会不会重叠多实例部署会不会重复执行任务异常有没有监控这五个问题有一个没过关都要警惕。第二日志和监控比任务本身重要。定时任务跑不跑、跑成没跑成、跑了多久这些信息如果没有记录出故障时你连排查的入口都没有。哪怕只加一条log.info和一次状态表写入都会让排查效率翻倍。第三动态化是个趋势。如果团队规模不大先用占位符配置加配置中心就够如果任务数量到了几十上百建议直接换分布式调度平台。Scheduled是起点但不一定是终点选型时给自己留点演进空间。