SpringBoot 整合 XXL-JOB 分布式定时任务实战

一、前言

很多中小型项目一开始使用Quartz或者Spring自带的@Scheduled做定时任务，简单省事，但随着服务集群部署，问题就暴露出来：

1. 多实例同时执行同一个任务，造成重复执行、数据重复入库；
2. 没有统一后台，任务日志、执行状态很难排查；
3. 不支持分片广播，大批量数据同步效率低；
4. 任务失败缺少统一告警机制。

XXL-JOB 由任务调度中心（admin）和执行器（executor）两部分组成，调度中心统一管理任务，执行器负责真正执行业务逻辑，通过注册中心通信，很好解决分布式定时任务痛点。

二、环境准备

• JDK 1.8+
• SpringBoot 2.x
• MySQL 5.7+
• XXL-JOB 2.4.0（稳定版本）

首先初始化XXL-JOB的数据库脚本，脚本在官方源码包里doc/db/tables_xxl_job.sql，导入MySQL。
然后启动xxl-job-admin调度中心，默认账号密码：admin / 123456。

三、SpringBoot项目引入依赖

<!-- xxl-job 执行器依赖 -->
<dependency>
    <groupId>com.xuxueli</groupId>
    <artifactId>xxl-job-core</artifactId>
    <version>2.4.0</version>
</dependency>

四、配置文件 application.yml

xxl:
  job:
    admin:
      # 调度中心地址，多个用逗号分隔
      addresses: [http://127.0.0.1:8080/xxl-job-admin](http://127.0.0.1:8080/xxl-job-admin)
    executor:
      # 执行器名称，后台新增任务时选择
      appname: springboot-xxljob-demo
      # 执行器注册地址，优先自动注册
      address:
      ip:
      port: 9999
      # 执行器日志文件存储路径
      logpath: /data/xxl-job/logs
      # 日志保留天数，-1=不清理
      logretentiondays: 30
    accessToken:

五、XXL-JOB配置类

import com.xxl.job.core.executor.impl.XxlJobSpringExecutor;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import org.springframework.beans.factory.annotation.Value;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;

@Configuration
public class XxlJobConfig {
    private Logger log = LoggerFactory.getLogger(XxlJobConfig.class);

    @Value("${xxl.job.admin.addresses}")
    private String adminAddresses;

    @Value("${xxl.job.executor.appname}")
    private String appName;

    @Value("${xxl.job.executor.address}")
    private String address;

    @Value("${xxl.job.executor.ip}")
    private String ip;

    @Value("${xxl.job.executor.port}")
    private int port;

    @Value("${xxl.job.executor.logpath}")
    private String logPath;

    @Value("${xxl.job.executor.logretentiondays}")
    private int logRetentionDays;

    @Bean
    public XxlJobSpringExecutor xxlJobExecutor() {
        log.info(">>>>>>>>>>> xxl-job config init.");
        XxlJobSpringExecutor xxlJobSpringExecutor = new XxlJobSpringExecutor();
        xxlJobSpringExecutor.setAdminAddresses(adminAddresses);
        xxlJobSpringExecutor.setAppname(appName);
        xxlJobSpringExecutor.setAddress(address);
        xxlJobSpringExecutor.setIp(ip);
        xxlJobSpringExecutor.setPort(port);
        xxlJobSpringExecutor.setLogPath(logPath);
        xxlJobSpringExecutor.setLogRetentionDays(logRetentionDays);
        return xxlJobSpringExecutor;
    }
}

六、开发任务Handler（两种模式）

方式1：Bean模式（推荐，Spring托管）

import com.xxl.job.core.handler.annotation.XxlJob;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import org.springframework.stereotype.Component;

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

    /**
     * 简单定时任务：每日数据统计
     */
    @XxlJob("dailyDataStatJob")
    public void dailyDataStatJob() throws Exception {
        log.info("【每日数据统计任务开始】");
        // 业务逻辑：统计昨日订单、流量、报表入库
        // service.dailyStat();
        log.info("【每日数据统计任务结束】");
    }

    /**
     * 分片广播任务，适合大批量数据同步
     */
    @XxlJob("shardDataSyncJob")
    public void shardDataSyncJob() throws Exception {
        // 获取分片参数
        int shardIndex = com.xxl.job.core.context.XxlJobHelper.getShardIndex();
        int shardTotal = com.xxl.job.core.context.XxlJobHelper.getShardTotal();
        log.info("分片任务，当前分片：{}/{}", shardIndex, shardTotal);
        // 根据shardIndex取模，不同实例处理不同批次数据
    }
}

七、后台配置任务

1. 打开 xxl-job-admin 后台，新增【执行器】，AppName和配置里保持一致；
2. 新增任务，JobHandler填写dailyDataStatJob；
3. 调度策略选择Cron表达式，例如0 0 1 * * ? 每天凌晨1点执行；
4. 路由策略：
   • 轮询：依次分配给在线执行器
   • 分片广播：全部执行器同时执行（适合分片任务）
   • 随机、一致性HASH等；
5. 保存后启动任务，可在后台查看执行日志、终止任务、手动触发。

八、生产环境重要避坑

1. 任务幂等：分布式任务一定要做幂等，优先用业务唯一标识+数据库唯一索引，防止重复执行造成脏数据；
2. 任务超时：设置合理超时时间，业务长时间阻塞会占用线程；
3. 日志清理：线上一定要配置日志保留天数，避免磁盘打满；
4. 调度中心高可用：admin可以集群部署，共用同一个MySQL；
5. 告警配置：后台支持邮件、钉钉、企业微信告警，任务失败及时通知开发；
6. 禁止长耗时任务：超大批量数据不要在一个Handler里循环，拆成分片或者异步+分页。

九、XXL-JOB 和 Quartz 对比

十、总结

XXL-JOB 是国内非常流行的分布式调度框架，学习成本低、运维友好，绝大多数业务系统的定时任务场景都可以覆盖。它把调度和执行解耦，调度中心只负责发指令，执行器执行业务，天然适合微服务集群场景。
本文演示了基础接入、普通任务、分片任务，后续还可以扩展：动态创建任务、子任务、任务依赖等高级玩法。