SpringBoot整合XXL-JOBv2.5.0搭建分布式任务调度平台的完整指南

XXL-JOB 是一个轻量级分布式任务调度平台，核心设计是调度中心（Admin） 与执行器（Executor） 分离：调度中心负责任务的管理和触发，执行器负责接收调度请求并执行业务代码。下面从零开始，一步步说明如何使用 v2.5.0。

一、部署调度中心（Admin）

1.1 获取源码

从官方仓库下载源码：

# GitHubgit clone https://github.com/xuxueli/xxl-job.git# 或 Gitee（国内更快）git clone https://gitee.com/xuxueli0323/xxl-job.git

项目结构说明：

1. xxl-job-admin：调度中心（需要部署）
2. xxl-job-core：公共核心依赖（执行器引入）
3. xxl-job-executor-samples：执行器示例代码
4. doc/db/tables_xxl_job.sql：数据库初始化脚本

1.2 初始化数据库

执行 doc/db/tables_xxl_job.sql 脚本，会生成 8 张表：

1.3 修改配置文件

编辑 xxl-job-admin/src/main/resources/application.properties，必须修改以下配置：

# 1. 数据库连接（必须修改）spring.datasource.url=jdbc:mysql://your-host:3306/xxl_job?useUnicode=true&characterEncoding=UTF-8&autoReconnect=true&serverTimezone=Asia/Shanghai&useSSL=falsespring.datasource.username=your-usernamespring.datasource.password=your-passwordspring.datasource.driver-class-name=com.mysql.cj.jdbc.Driver# 2. AccessToken（生产环境必须修改为复杂随机字符串）xxl.job.accessToken=your-production-token# 3. 可选：日志保留天数xxl.job.logretentiondays=30# 4. 可选：线程池大小xxl.job.triggerpool.fast.max=200xxl.job.triggerpool.slow.max=100

1.4 启动调度中心

直接运行 XxlJobAdminApplication 类的 main 方法。

访问 http://localhost:8080/xxl-job-admin，默认用户名/密码：admin/123456。

登录后，可以看到以下功能模块：

1. 运行报表：调度中心首页，整体运行情况
2. 任务管理：配置任务的地方（最常用）
3. 调度日志：所有任务调度记录
4. 执行器管理：管理注册上来的执行器
5. 用户管理：多账号管理

二、搭建执行器（Executor）

2.1 引入依赖

在业务项目的 pom.xml 中添加：

<dependency>    <groupId>com.xuxueli</groupId>    <artifactId>xxl-job-core</artifactId>    <version>2.5.0</version></dependency>

2.2 配置执行器

在 application.yml 或 application.properties 中配置：

# 调度中心地址（集群用逗号分隔多个）xxl.job.admin.addresses=http://localhost:8080/xxl-job-admin# 执行器名称（唯一标识）xxl.job.executor.appname=xxl-job-executor-demo# 执行器端口（默认9999，生产建议修改）xxl.job.executor.port=9999# AccessToken（必须与调度中心一致）xxl.job.accessToken=your-production-token# 日志路径xxl.job.executor.logpath=/data/applogs/xxl-job/jobhandler# 日志保留天数xxl.job.executor.logretentiondays=30

2.3 初始化执行器 Bean

创建配置类，初始化 XxlJobSpringExecutor：

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;@Configurationpublic class XxlJobConfig {    private Logger logger = LoggerFactory.getLogger(XxlJobConfig.class);    @Value("${xxl.job.admin.addresses}")    private String adminAddresses;    @Value("${xxl.job.executor.appname}")    private String appname;    @Value("${xxl.job.executor.port}")    private int port;    @Value("${xxl.job.accessToken}")    private String accessToken;    @Value("${xxl.job.executor.logpath}")    private String logPath;    @Value("${xxl.job.executor.logretentiondays}")    private int logRetentionDays;    @Bean    public XxlJobSpringExecutor xxlJobExecutor() {        logger.info(">>>>>>>>>>> xxl-job config init.");        XxlJobSpringExecutor executor = new XxlJobSpringExecutor();        executor.setAdminAddresses(adminAddresses);        executor.setAppname(appname);        executor.setPort(port);        executor.setAccessToken(accessToken);        executor.setLogPath(logPath);        executor.setLogRetentionDays(logRetentionDays);        return executor;    }}

2.4 启动执行器

启动业务应用后，执行器会自动向调度中心注册。登录调度中心后台，在执行器管理页面应该能看到注册上来的执行器信息。

三、编写任务代码（BEAN 模式）

生产环境强烈推荐使用 BEAN 模式，而不是 GLUE 模式。BEAN 模式的代码在业务项目中，可以进行版本控制和 Code Review，更加安全可控。

3.1 简单任务示例

import com.xxl.job.core.context.XxlJobHelper;import com.xxl.job.core.handler.annotation.XxlJob;import org.slf4j.Logger;import org.slf4j.LoggerFactory;import org.springframework.stereotype.Component;@Componentpublic class SampleXxlJob {    private static Logger logger = LoggerFactory.getLogger(SampleXxlJob.class);    /**     * 简单任务示例     * 注解中的 "demoJobHandler" 是任务标识，在调度中心配置时需要用到     */    @XxlJob("demoJobHandler")    public void demoJobHandler() throws Exception {        XxlJobHelper.log("XXL-JOB, Hello World.");        // 获取任务参数（在调度中心配置时填写）        String jobParam = XxlJobHelper.getJobParam();        XxlJobHelper.log("任务参数: {}", jobParam);        for (int i = 0; i < 5; i++) {            XxlJobHelper.log("beat at: {}", i);            Thread.sleep(2000);        }        // 默认返回 SUCCESS    }}

3.2 分片广播任务示例

当执行器集群部署时，使用分片广播路由策略可以让每个节点处理一部分数据，提高处理效率。

import com.xxl.job.core.context.XxlJobHelper;import com.xxl.job.core.handler.annotation.XxlJob;import org.springframework.stereotype.Component;@Componentpublic class ShardingJob {    @XxlJob("shardingJobHandler")    public void shardingJobHandler() throws Exception {        // 获取分片参数        int shardIndex = XxlJobHelper.getShardIndex();   // 当前分片序号（从0开始）        int shardTotal = XxlJobHelper.getShardTotal();   // 总分片数        XxlJobHelper.log("分片参数：当前分片序号 = {}, 总分片数 = {}", shardIndex, shardTotal);        // 业务逻辑：根据分片参数查询数据        // 例如：从数据库查询 order_id % shardTotal == shardIndex 的数据        // 每个节点只处理自己分片的数据，避免重复处理        for (int i = 0; i < shardTotal; i++) {            if (i == shardIndex) {                XxlJobHelper.log("第 {} 片，命中分片开始处理", i);                // 执行具体业务逻辑...            } else {                XxlJobHelper.log("第 {} 片，忽略", i);            }        }    }}

分片广播适用场景：海量数据处理、日志分析、订单批量处理等需要并行提升效率的场景。

四、在调度中心配置任务

登录调度中心后台，进入任务管理页面，点击新增。

4.1 填写任务信息

Cron 表达式常用示例：

1. 0 0 0 * * ?：每天0点触发
2. 0 30 10 * * ?：每天10点30分触发
3. 0 0/5 * * * ?：每5分钟触发
4. 0 0/10 * * * ?：每10分钟触发

4.2 配置执行参数

4.3 路由策略说明

执行器集群部署时，需要选择路由策略决定任务由哪个节点执行：

五、测试与查看日志

5.1 手动触发任务

在任务管理页面，点击任务的操作列，选择执行一次。在弹出的对话框可以填写执行参数，也可以指定某台 IP 执行（方便 Debug）。

5.2 查看执行日志

执行完成后，点击查看日志可以查看调度记录和任务执行日志。日志会显示：

1. 调度时间、调度结果
2. 执行器地址、执行结果
3. 代码中通过 XxlJobHelper.log() 输出的业务日志

六、生产环境检查清单