scheduled-jobs（预定的工作）

定时任务开发指南

通用模板。如果项目有专属技能（如 leniu-java-task），优先使用。

设计原则

1. 幂等性：任务重复执行不会产生副作用。考虑任务被重试、多次调度的情况。
2. 可观测：任务执行结果必须可追踪（日志、监控、告警）。
3. 故障隔离：单个任务失败不应影响其他任务的调度。
4. 超时控制：设置合理的执行超时时间，避免任务无限阻塞。

方案对比

选型决策树

需要分布式调度？
├── 否 → @Scheduled（简单定时）
└── 是 → 需要可视化管理？
        ├── 否 → Quartz + 数据库（中等规模）
        └── 是 → XXL-Job / SnailJob / PowerJob（生产推荐）

实现模式

方案一：@Scheduled（Spring 内置）

@Component
@EnableScheduling
public class SimpleScheduledTasks {

    // 固定频率：每30秒执行一次
    @Scheduled(fixedRate = 30000)
    public void heartbeat() {
        log.info("心跳检测");
    }

    // 固定延迟：上次执行完成后等10秒再执行
    @Scheduled(fixedDelay = 10000)
    public void cleanTempFiles() {
        log.info("清理临时文件");
    }

    // Cron 表达式：每天凌晨2点执行
    @Scheduled(cron = "0 0 2 * * ?")
    public void dailyReport() {
        log.info("生成日报");
    }

    // 使用配置文件中的 Cron
    @Scheduled(cron = "${task.cleanup.cron:0 0 3 * * ?}")
    public void configuredTask() {
        log.info("可配置的定时任务");
    }
}

注意事项：

• 默认单线程执行，需配置线程池避免任务阻塞
• 多实例部署时每个实例都会执行，需分布式锁控制

@Configuration
public class SchedulingConfig implements SchedulingConfigurer {
    @Override
    public void configureTasks(ScheduledTaskRegistrar registrar) {
        registrar.setScheduler(Executors.newScheduledThreadPool(5));
    }
}

方案二：Quartz

// 1. 定义 Job
public class OrderCleanupJob implements Job {
    @Override
    public void execute(JobExecutionContext context) throws JobExecutionException {
        JobDataMap dataMap = context.getMergedJobDataMap();
        int days = dataMap.getInt("retentionDays");
        // 业务逻辑...
    }
}

// 2. 配置调度
@Configuration
public class QuartzConfig {

    @Bean
    public JobDetail orderCleanupJobDetail() {
        return JobBuilder.newJob(OrderCleanupJob.class)
            .withIdentity("orderCleanup", "maintenance")
            .usingJobData("retentionDays", 30)
            .storeDurably()
            .build();
    }

    @Bean
    public Trigger orderCleanupTrigger() {
        return TriggerBuilder.newTrigger()
            .forJob(orderCleanupJobDetail())
            .withIdentity("orderCleanupTrigger", "maintenance")
            .withSchedule(CronScheduleBuilder.cronSchedule("0 0 2 * * ?"))
            .build();
    }
}

方案三：分布式任务调度平台（XXL-Job 等）

// 通用模式：注解标记任务处理器
@Component
public class OrderCleanupJobHandler {

    @Autowired
    private OrderService orderService;

    // 具体注解取决于所选平台
    // XXL-Job: @XxlJob("orderCleanupHandler")
    // SnailJob: @JobExecutor(name = "orderCleanupJob")
    public void execute(String params) {
        log.info("开始清理过期订单");
        try {
            int days = StringUtils.isBlank(params) ? 30 : Integer.parseInt(params);
            int count = orderService.cleanupExpiredOrders(days);
            log.info("清理完成，删除 {} 条", count);
        } catch (Exception e) {
            log.error("清理失败: {}", e.getMessage());
            throw e;  // 抛出异常触发平台重试
        }
    }
}

执行模式

最佳实践

标准任务模板

@Component
public class [你的任务类] {

    private static final Logger log = LoggerFactory.getLogger([你的任务类].class);

    @Autowired
    private [你的业务Service] bizService;

    public void execute(String params) {
        long startTime = System.currentTimeMillis();
        log.info("[任务开始] 参数: {}", params);

        try {
            // 1. 解析参数
            int days = parseParams(params);

            // 2. 幂等检查
            if (bizService.isAlreadyProcessed(today())) {
                log.info("[任务跳过] 今日已执行");
                return;
            }

            // 3. 执行业务逻辑
            int count = bizService.process(days);

            // 4. 记录结果
            long cost = System.currentTimeMillis() - startTime;
            log.info("[任务完成] 处理 {} 条，耗时 {} ms", count, cost);

        } catch (Exception e) {
            log.error("[任务失败] {}", e.getMessage(), e);
            throw e;  // 抛出异常触发重试
        }
    }
}

重试策略对比

Cron 表达式速查

常见错误

// 1. @Scheduled 任务中抛出异常但不处理
@Scheduled(fixedRate = 60000)
public void task() {
    service.process();  // 异常后任务停止调度！
}
// 应捕获异常
@Scheduled(fixedRate = 60000)
public void task() {
    try {
        service.process();
    } catch (Exception e) {
        log.error("任务执行失败", e);
    }
}

// 2. @Scheduled 默认单线程，长任务阻塞其他任务
// 应配置线程池（见上文 SchedulingConfig）

// 3. 多实例部署未做互斥
// @Scheduled 每个实例都执行 -> 数据重复处理
// 应使用分布式锁（Redis / 数据库）或分布式调度平台

// 4. 任务非幂等
public void syncData() {
    insertAll(fetchData());  // 重复执行会插入重复数据
}
// 应先检查是否已处理

// 5. 任务内开启大事务
@Transactional
public void processAllOrders() {
    // 处理百万条数据在一个事务中 -> 内存溢出、锁超时
}
// 应分批处理，每批独立事务