SpringBoot定时任务：@Scheduled注解与Cron表达式

最新推荐文章于 2025-06-18 17:17:26 发布

原创最新推荐文章于 2025-06-18 17:17:26 发布 · 2.9k 阅读

21 ·

CC 4.0 BY-SA版权

文章标签：

#spring boot #java #后端

Java 同时被 2 个专栏收录

162 篇文章

订阅专栏

Spring 全家桶

120 篇文章

订阅专栏

在这里插入图片描述

文章目录

引言

定时任务是企业级应用中的关键组件，用于执行周期性操作，如数据清理、报表生成、系统监控等。SpringBoot提供了强大而灵活的定时任务支持，使开发者能够以声明式方式轻松实现复杂的调度需求。本文深入探讨SpringBoot中@Scheduled注解的使用方法、Cron表达式的编写技巧以及定时任务的配置与管理，帮助开发者构建可靠高效的任务调度系统。

一、SpringBoot定时任务基础

SpringBoot的定时任务功能建立在Spring Framework的任务调度框架之上，通过@EnableScheduling注解和@Scheduled注解提供了简洁的任务调度能力。与传统的Quartz等调度框架相比，SpringBoot的调度机制更加轻量化，与Spring生态无缝集成，适合大多数应用场景的任务调度需求。开启定时任务只需在配置类上添加@EnableScheduling注解，即可激活SpringBoot的调度功能。

/**
 * 定时任务示例应用
 */
@SpringBootApplication
@EnableScheduling  // 启用SpringBoot的定时任务支持
public class ScheduledTaskDemoApplication {
    
    private static final Logger logger = LoggerFactory.getLogger(ScheduledTaskDemoApplication.class);
    
    public static void main(String[] args) {
        SpringApplication.run(ScheduledTaskDemoApplication.class, args);
        logger.info("定时任务应用已启动");
    }
    
    /**
     * 自定义任务调度器配置
     */
    @Bean
    public TaskScheduler taskScheduler() {
        ThreadPoolTaskScheduler scheduler = new ThreadPoolTaskScheduler();
        scheduler.setPoolSize(5);  // 设置线程池大小
        scheduler.setThreadNamePrefix("Task-");  // 线程名称前缀
        scheduler.setAwaitTerminationSeconds(60);  // 等待终止的秒数
        scheduler.setWaitForTasksToCompleteOnShutdown(true);  // 等待任务完成后再关闭线程池
        scheduler.setErrorHandler(throwable -> 
            logger.error("定时任务执行异常", throwable));  // 设置异常处理器
        return scheduler;
    }
}

二、@Scheduled注解详解

@Scheduled注解是SpringBoot中实现定时任务的核心，它可以标记一个方法按照特定时间计划执行。被@Scheduled注解的方法必须是void返回类型且不接受任何参数。这种设计使得定时任务的声明简洁明了，开发者可以专注于任务逻辑而非调度细节。@Scheduled支持多种时间表达方式，包括固定延迟、固定速率和基于Cron表达式的复杂调度模式。

/**
 * 系统维护任务服务
 */
@Service
public class SystemMaintenanceService {
    
    private static final Logger logger = LoggerFactory.getLogger(SystemMaintenanceService.class);
    
    /**
     * 使用固定延迟的定时任务
     * 任务执行完成后等待5秒再次执行
     */
    @Scheduled(fixedDelay = 5000)  // 5000毫秒 = 5秒
    public void performHealthCheck() {
        logger.info("执行系统健康检查 - {}", new Date());
        try {
            // 模拟健康检查逻辑
            long checkStartTime = System.currentTimeMillis();
            Thread.sleep(2000);  // 模拟任务执行时间
            long duration = System.currentTimeMillis() - checkStartTime;
            
            logger.info("健康检查完成，耗时: {}ms", duration);
        } catch (InterruptedException e) {
            Thread.currentThread().interrupt();
            logger.error("健康检查被中断", e);
        } catch (Exception e) {
            logger.error("健康检查执行异常", e);
        }
    }
    
    /**
     * 使用固定速率的定时任务
     * 从任务开始时计时，每10秒执行一次
     */
    @Scheduled(fixedRate = 10000)  // 10000毫秒 = 10秒
    public void generateSystemMetrics() {
        logger.info("开始生成系统指标报告 - {}", new Date());
        try {
            // 模拟指标收集逻辑
            Thread.sleep(3000);  // 模拟任务执行时间
            
            logger.info("系统指标报告生成完成");
        } catch (InterruptedException e) {
            Thread.currentThread().interrupt();
            logger.error("指标生成被中断", e);
        } catch (Exception e) {
            logger.error("指标生成执行异常", e);
        }
    }
    
    /**
     * 使用初始延迟的定时任务
     * 应用启动后等待60秒再执行第一次任务，之后每30秒执行一次
     */
    @Scheduled(initialDelay = 60000, fixedRate = 30000)
    public void checkDiskSpace() {
        logger.info("开始检查磁盘空间 - {}", new Date());
        try {
            // 模拟磁盘空间检查逻辑
            
            logger.info("磁盘空间检查完成");
        } catch (Exception e) {
            logger.error("磁盘空间检查执行异常", e);
        }
    }
}

2.1 使用Cron表达式的定时任务

Cron表达式提供了最灵活的定时任务调度方式，可以实现复杂的时间模式，如"每周一至周五的上午9点执行"、"每月最后一天的午夜执行"等。SpringBoot完全支持标准的Cron表达式，使开发者能够精确控制任务的执行时间。Cron表达式由六个字段组成，分别表示秒、分、时、日、月、周，按照固定模式组合即可实现各种复杂的调度需求。

/**
 * 数据维护任务服务
 */
@Service
public class DataMaintenanceService {
    
    private static final Logger logger = LoggerFactory.getLogger(DataMaintenanceService.class);
    
    /**
     * 每天凌晨2点执行的数据清理任务
     * Cron: 秒 分 时 日 月 周
     */
    @Scheduled(cron = "0 0 2 * * ?")
    public void cleanupOutdatedData() {
        logger.info("开始清理过期数据 - {}", new Date());
        try {
            // 模拟数据清理逻辑
            long startTime = System.currentTimeMillis();
            
            // 执行清理操作...
            Thread.sleep(5000);  // 模拟操作耗时
            
            long duration = System.currentTimeMillis() - startTime;
            logger.info("数据清理完成，共耗时: {}ms", duration);
        } catch (Exception e) {
            logger.error("数据清理任务执行失败", e);
        }
    }
    
    /**
     * 每周日凌晨3点执行的数据归档任务
     */
    @Scheduled(cron = "0 0 3 ? * SUN")
    public void archiveWeeklyData() {
        logger.info("开始执行周数据归档 - {}", new Date());
        try {
            // 模拟数据归档逻辑
            
            logger.info("周数据归档完成");
        } catch (Exception e) {
            logger.error("数据归档任务执行失败", e);
        }
    }
    
    /**
     * 每月最后一天执行的月度报表生成任务
     * L表示月的最后一天
     */
    @Scheduled(cron = "0 0 1 L * ?")
    public void generateMonthlyReport() {
        logger.info("开始生成月度报表 - {}", new Date());
        try {
            // 模拟报表生成逻辑
            
            logger.info("月度报表生成完成");
        } catch (Exception e) {
            logger.error("月度报表生成任务执行失败", e);
        }
    }
    
    /**
     * 工作日（周一至周五）上午9点执行的任务
     */
    @Scheduled(cron = "0 0 9 ? * MON-FRI")
    public void workdayMorningTask() {
        logger.info("执行工作日早间任务 - {}", new Date());
        try {
            // 任务逻辑...
            
            logger.info("工作日早间任务完成");
        } catch (Exception e) {
            logger.error("工作日任务执行失败", e);
        }
    }
}

三、Cron表达式详解

Cron表达式是一种表示时间调度的字符串，由六个或七个字段组成，每个字段代表时间的不同部分。掌握Cron表达式的语法对于实现精确的定时任务调度至关重要。Cron表达式的字段从左到右依次是：秒（0-59）、分（0-59）、时（0-23）、日（1-31）、月（1-12或JAN-DEC）、周（0-7或SUN-SAT，0和7都表示周日）、年（可选）。每个字段可以使用特殊字符表达复杂的时间模式，如星号（*）表示每个时间单位，问号（?）表示不指定值，逗号（,）表示列举，连字符（-）表示范围等。

/**
 * Cron表达式工具类，提供常用Cron表达式示例和验证功能
 */
public class CronExpressionUtil {
    
    /**
     * 验证Cron表达式是否有效
     * @param cronExpression Cron表达式
     * @return 是否有效
     */
    public static boolean isValidExpression(String cronExpression) {
        try {
            CronSequenceGenerator generator = new CronSequenceGenerator(cronExpression);
            generator.next(new Date());  // 尝试生成下一个执行时间
            return true;
        } catch (IllegalArgumentException e) {
            return false;
        }
    }
    
    /**
     * 获取Cron表达式的下一个执行时间
     * @param cronExpression Cron表达式
     * @param currentTime 当前时间
     * @return 下一个执行时间
     */
    public static Date getNextExecutionTime(String cronExpression, Date currentTime) {
        CronSequenceGenerator generator = new CronSequenceGenerator(cronExpression);
        return generator.next(currentTime);
    }
    
    /**
     * 获取Cron表达式的多个执行时间点
     * @param cronExpression Cron表达式
     * @param startTime 开始时间
     * @param count 要获取的时间点数量
     * @return 执行时间点列表
     */
    public static List<Date> getExecutionTimeList(String cronExpression, Date startTime, int count) {
        List<Date> executionTimes = new ArrayList<>();
        CronSequenceGenerator generator = new CronSequenceGenerator(cronExpression);
        
        Date nextTime = startTime;
        for (int i = 0; i < count; i++) {
            nextTime = generator.next(nextTime);
            executionTimes.add(nextTime);
        }
        
        return executionTimes;
    }
    
    /**
     * 常用Cron表达式示例
     */
    public static class CommonExpressions {
        // 每秒执行一次
        public static final String EVERY_SECOND = "* * * * * ?";
        
        // 每分钟执行一次（在0秒时）
        public static final String EVERY_MINUTE = "0 * * * * ?";
        
        // 每小时执行一次（在0分0秒时）
        public static final String EVERY_HOUR = "0 0 * * * ?";
        
        // 每天午夜执行一次
        public static final String EVERY_DAY_MIDNIGHT = "0 0 0 * * ?";
        
        // 每天上午8点执行一次
        public static final String EVERY_DAY_8AM = "0 0 8 * * ?";
        
        // 每周一上午10点15分执行
        public static final String EVERY_MONDAY_10_15AM = "0 15 10 ? * MON";
        
        // 每月1日和15日上午9点执行
        public static final String FIRST_AND_FIFTEENTH_9AM = "0 0 9 1,15 * ?";
        
        // 每月最后一天执行
        public static final String LAST_DAY_OF_MONTH = "0 0 0 L * ?";
        
        // 每季度第一个月第一天执行
        public static final String FIRST_DAY_OF_QUARTER = "0 0 0 1 1,4,7,10 ?";
        
        // 工作日（周一至周五）上午9点执行
        public static final String WEEKDAY_9AM = "0 0 9 ? * MON-FRI";
    }
}

四、定时任务配置与管理

正确配置和管理定时任务对于构建可靠的调度系统至关重要。SpringBoot提供了灵活的配置选项，允许开发者通过属性文件或代码方式定制任务调度器的行为。常见的配置包括线程池大小、线程名称前缀、异常处理策略等。对于生产环境，通常需要适当增加线程池大小以处理并发任务，并实现完善的异常处理和监控机制。

/**
 * 定时任务配置类
 */
@Configuration
@EnableScheduling
public class SchedulingConfig implements SchedulingConfigurer {
    
    private static final Logger logger = LoggerFactory.getLogger(SchedulingConfig.class);
    
    @Value("${scheduling.pool-size:5}")
    private int poolSize;
    
    /**
     * 配置任务调度器
     */
    @Override
    public void configureTasks(ScheduledTaskRegistrar taskRegistrar) {
        ThreadPoolTaskScheduler scheduler = new ThreadPoolTaskScheduler();
        scheduler.setPoolSize(poolSize);
        scheduler.setThreadNamePrefix("CustomScheduler-");
        scheduler.setAwaitTerminationSeconds(60);
        scheduler.setWaitForTasksToCompleteOnShutdown(true);
        scheduler.setErrorHandler(throwable -> 
            logger.error("定时任务执行异常", throwable));
        scheduler.setRejectedExecutionHandler(new ThreadPoolExecutor.CallerRunsPolicy());
        scheduler.initialize();
        
        taskRegistrar.setTaskScheduler(scheduler);
        
        // 注册自定义动态定时任务
        taskRegistrar.addTriggerTask(
            () -> logger.info("执行动态配置的定时任务 - {}", new Date()),
            triggerContext -> {
                // 从数据库或配置中心获取Cron表达式
                String cronExpression = getCronExpressionFromDB();
                CronTrigger trigger = new CronTrigger(cronExpression);
                return trigger.nextExecutionTime(triggerContext);
            }
        );
    }
    
    /**
     * 模拟从数据库获取Cron表达式
     */
    private String getCronExpressionFromDB() {
        // 实际应用中，这里会查询数据库或配置中心
        return "0 */30 * * * ?";  // 示例：每30分钟执行一次
    }
}

4.1 定时任务的动态管理

在实际应用中，经常需要动态管理定时任务，如在运行时启用/禁用任务、修改执行计划等。SpringBoot本身不直接提供动态任务管理的能力，但可以通过结合数据库、配置中心等外部存储，以及SchedulingConfigurer接口和TriggerTask实现动态任务调度。这种方式使得定时任务的管理更加灵活，能够适应复杂的业务需求变化。

/**
 * 动态定时任务管理服务
 */
@Service
public class DynamicTaskService {
    
    private static final Logger logger = LoggerFactory.getLogger(DynamicTaskService.class);
    
    private final TaskRepository taskRepository;
    private final ThreadPoolTaskScheduler taskScheduler;
    private final Map<Long, ScheduledFuture<?>> scheduledTasks = new ConcurrentHashMap<>();
    
    /**
     * 构造函数，注入必要的依赖
     */
    public DynamicTaskService(TaskRepository taskRepository) {
        this.taskRepository = taskRepository;
        
        // 创建任务调度器
        this.taskScheduler = new ThreadPoolTaskScheduler();
        this.taskScheduler.setPoolSize(10);
        this.taskScheduler.setThreadNamePrefix("DynamicTask-");
        this.taskScheduler.setWaitForTasksToCompleteOnShutdown(true);
        this.taskScheduler.setAwaitTerminationSeconds(60);
        this.taskScheduler.initialize();
    }
    
    /**
     * 初始化任务，从数据库加载所有启用的任务
     */
    @PostConstruct
    public void initTasks() {
        logger.info("初始化动态定时任务");
        List<TaskDefinition> tasks = taskRepository.findByEnabled(true);
        tasks.forEach(this::scheduleTask);
    }
    
    /**
     * 调度任务
     * @param taskDefinition 任务定义
     */
    public void scheduleTask(TaskDefinition taskDefinition) {
        logger.info("调度任务: {}", taskDefinition.getTaskName());
        
        // 如果任务已存在，先取消原任务
        ScheduledFuture<?> scheduledFuture = scheduledTasks.get(taskDefinition.getId());
        if (scheduledFuture != null) {
            scheduledFuture.cancel(false);
        }
        
        // 创建定时任务
        Runnable taskRunner = () -> {
            try {
                logger.info("开始执行任务: {} - {}", taskDefinition.getTaskName(), new Date());
                // 执行实际的任务逻辑
                executeTask(taskDefinition);
                logger.info("任务执行完成: {}", taskDefinition.getTaskName());
            } catch (Exception e) {
                logger.error("任务执行异常: {}", taskDefinition.getTaskName(), e);
            }
        };
        
        // 使用Cron表达式调度任务
        ScheduledFuture<?> future = taskScheduler.schedule(
            taskRunner,
            new CronTrigger(taskDefinition.getCronExpression())
        );
        
        // 保存任务引用
        scheduledTasks.put(taskDefinition.getId(), future);
    }
    
    /**
     * 执行任务的具体逻辑
     * @param taskDefinition 任务定义
     */
    private void executeTask(TaskDefinition taskDefinition) throws Exception {
        // 根据任务类型执行不同的任务逻辑
        switch (taskDefinition.getTaskType()) {
            case "REPORT":
                generateReport(taskDefinition);
                break;
            case "CLEANUP":
                performCleanup(taskDefinition);
                break;
            case "NOTIFICATION":
                sendNotifications(taskDefinition);
                break;
            default:
                logger.warn("未知的任务类型: {}", taskDefinition.getTaskType());
                break;
        }
    }
    
    /**
     * 取消任务
     * @param taskId 任务ID
     */
    public void cancelTask(Long taskId) {
        logger.info("取消任务: {}", taskId);
        ScheduledFuture<?> scheduledFuture = scheduledTasks.get(taskId);
        if (scheduledFuture != null) {
            scheduledFuture.cancel(false);
            scheduledTasks.remove(taskId);
        }
    }
    
    /**
     * 更新任务
     * @param taskDefinition 更新后的任务定义
     */
    public void updateTask(TaskDefinition taskDefinition) {
        logger.info("更新任务: {}", taskDefinition.getTaskName());
        // 保存任务定义到数据库
        taskRepository.save(taskDefinition);
        
        // 如果任务已启用，重新调度
        if (taskDefinition.isEnabled()) {
            scheduleTask(taskDefinition);
        } else {
            cancelTask(taskDefinition.getId());
        }
    }
    
    // 模拟任务执行逻辑
    private void generateReport(TaskDefinition taskDefinition) {
        logger.info("生成报表: {}", taskDefinition.getTaskParams());
        // 实际的报表生成逻辑...
    }
    
    private void performCleanup(TaskDefinition taskDefinition) {
        logger.info("执行清理任务: {}", taskDefinition.getTaskParams());
        // 实际的清理逻辑...
    }
    
    private void sendNotifications(TaskDefinition taskDefinition) {
        logger.info("发送通知: {}", taskDefinition.getTaskParams());
        // 实际的通知发送逻辑...
    }
}

五、定时任务最佳实践

在生产环境中实施定时任务系统时，应遵循一些最佳实践，以确保系统的可靠性、可维护性和性能。定时任务应该是幂等的，即多次执行产生相同的结果；任务应该短小精悍，避免长时间运行；对于复杂任务，应考虑将其拆分为多个子任务或使用异步处理；任务应该具有良好的异常处理机制，防止一个任务的失败影响其他任务；定期审查任务的执行情况和性能，优化调度策略。

/**
 * 定时任务监控组件
 */
@Component
public class ScheduledTasksMonitor {
    
    private static final Logger logger = LoggerFactory.getLogger(ScheduledTasksMonitor.class);
    
    // 记录任务执行情况的计数器
    private final Map<String, AtomicLong> taskExecutionCounter = new ConcurrentHashMap<>();
    private final Map<String, AtomicLong> taskFailureCounter = new ConcurrentHashMap<>();
    private final Map<String, AtomicLong> taskExecutionTime = new ConcurrentHashMap<>();
    
    /**
     * 定时任务执行前的切面
     */
    @Before("@annotation(org.springframework.scheduling.annotation.Scheduled)")
    public void beforeTaskExecution(JoinPoint joinPoint) {
        String taskName = getTaskName(joinPoint);
        logger.debug("定时任务开始执行: {}", taskName);
        
        // 将任务开始时间存储在ThreadLocal中
        TaskExecutionContext.setStartTime(System.currentTimeMillis());
    }
    
    /**
     * 定时任务执行后的切面
     */
    @AfterReturning("@annotation(org.springframework.scheduling.annotation.Scheduled)")
    public void afterTaskExecution(JoinPoint joinPoint) {
        String taskName = getTaskName(joinPoint);
        long startTime = TaskExecutionContext.getStartTime();
        long executionTime = System.currentTimeMillis() - startTime;
        
        logger.debug("定时任务执行完成: {}, 耗时: {}ms", taskName, executionTime);
        
        // 更新计数器
        taskExecutionCounter.computeIfAbsent(taskName, k -> new AtomicLong()).incrementAndGet();
        taskExecutionTime.computeIfAbsent(taskName, k -> new AtomicLong()).addAndGet(executionTime);
        
        // 清理ThreadLocal
        TaskExecutionContext.clear();
    }
    
    /**
     * 定时任务异常处理的切面
     */
    @AfterThrowing(pointcut = "@annotation(org.springframework.scheduling.annotation.Scheduled)", throwing = "ex")
    public void taskExecutionException(JoinPoint joinPoint, Exception ex) {
        String taskName = getTaskName(joinPoint);
        logger.error("定时任务执行异常: {}", taskName, ex);
        
        // 更新失败计数器
        taskFailureCounter.computeIfAbsent(taskName, k -> new AtomicLong()).incrementAndGet();
        
        // 清理ThreadLocal
        TaskExecutionContext.clear();
    }
    
    /**
     * 获取任务统计信息
     */
    public Map<String, Map<String, Long>> getTaskStatistics() {
        Map<String, Map<String, Long>> statistics = new HashMap<>();
        
        for (String taskName : taskExecutionCounter.keySet()) {
            Map<String, Long> taskStats = new HashMap<>();
            taskStats.put("executionCount", taskExecutionCounter.get(taskName).get());
            taskStats.put("failureCount", 
                    taskFailureCounter.containsKey(taskName) ? taskFailureCounter.get(taskName).get() : 0);
            
            long totalTime = taskExecutionTime.get(taskName).get();
            long executionCount = taskExecutionCounter.get(taskName).get();
            long avgTime = executionCount > 0 ? totalTime / executionCount : 0;
            
            taskStats.put("totalExecutionTime", totalTime);
            taskStats.put("averageExecutionTime", avgTime);
            
            statistics.put(taskName, taskStats);
        }
        
        return statistics;
    }
    
    /**
     * 重置统计信息
     */
    public void resetStatistics() {
        taskExecutionCounter.clear();
        taskFailureCounter.clear();
        taskExecutionTime.clear();
    }
    
    /**
     * 获取任务名称
     */
    private String getTaskName(JoinPoint joinPoint) {
        return joinPoint.getSignature().getDeclaringTypeName() + "." + joinPoint.getSignature().getName();
    }
    
    /**
     * 任务执行上下文，用于存储线程相关信息
     */
    private static class TaskExecutionContext {
        private static final ThreadLocal<Long> startTimeThreadLocal = new ThreadLocal<>();
        
        public static void setStartTime(long startTime) {
            startTimeThreadLocal.set(startTime);
        }
        
        public static long getStartTime() {
            Long startTime = startTimeThreadLocal.get();
            return startTime != null ? startTime : 0;
        }
        
        public static void clear() {
            startTimeThreadLocal.remove();
        }
    }
}

总结

SpringBoot的定时任务框架提供了强大而灵活的调度能力，通过@Scheduled注解和Cron表达式，开发者可以轻松实现从简单到复杂的各种定时任务需求。合理配置线程池和任务调度器是构建高效可靠定时任务系统的基础，而动态任务管理机制则为系统提供了更大的灵活性。在实际应用中，应遵循定时任务的最佳实践，确保任务的幂等性、高效性和可靠性。通过本文介绍的技术和实践，开发者可以构建出稳定可靠的定时任务系统，满足企业级应用的各种调度需求，包括数据维护、报表生成、系统监控等场景，为用户提供更加优质的服务体验。