使用 Spring Boot 引入 XXL-JOB 入门实战介绍

Blog Author

2025-07-10

使用 Spring Boot 引入 XXL-JOB 入门实战介绍

一、XXL-JOB 简介

XXL-JOB 是一个分布式任务调度平台，其核心设计目标是开发迅速、学习简单、轻量级、易扩展。现已开放源代码并接入多家公司线上产品线，开箱即用。

二、开发环境准备

JDK：1.8 及以上
Maven：3.0 及以上
数据库：MySQL 5.7 及以上

三、项目下载与编译

源码安装:

从 GitHub、Gitee 或 GitCode 下载 XXL-JOB 源码，解压后按照 Maven 格式将源码导入 IDE，使用 Maven 进行编译。源码结构如下：

xxl-job-admin：调度中心
xxl-job-core：公共依赖
xxl-job-executor-samples：执行器 Sample 示例，我们将使用 xxl-job-executor-sample-springboot 作为参考。

docker安装xxl-job

bash 复制代码

docker run -e PARAMS="--spring.datasource.url=jdbc:mysql://你的mysql地址:3306/xxl_job?useUnicode=true&characterEncoding=UTF-8&autoReconnect=true&serverTimezone=Asia/Shanghai --spring.datasource.username=账户 --spring.datasource.password=密码" -p 8079:8080 -v /Users/wangpenglong/dockerMounts/xxlJob/applogs:/data/applogs --name xxl-job-admin  -d xuxueli/xxl-job-admin:2.4.2

如需自定义 mysql 等配置，可通过 "-e PARAMS" 指定，参数格式 PARAMS="--key=value --key2=value2" ；
配置项参考文件：/xxl-job/xxl-job-admin/src/main/resources/application.properties
如需自定义 JVM内存参数等配置，可通过 "-e JAVA_OPTS" 指定，参数格式 JAVA_OPTS="-Xmx512m" ；

登陆:http://localhost:8079/xxl-job-admin/toLogin

复制代码

账户密码默认
admin
123456

四、数据库初始化

执行 xxl-job/doc/db/tables_xxl_job.sql 脚本，创建 XXL-JOB 所需的数据库表。

五、配置调度中心（xxl-job-admin）

1. 配置数据库连接

打开 xxl-job-admin/src/main/resources/application.properties 文件，配置数据库连接信息：

properties 复制代码

spring.datasource.url=jdbc:mysql://127.0.0.1:3306/xxl_job?useUnicode=true&characterEncoding=UTF-8&autoReconnect=true&serverTimezone=Asia/Shanghai
spring.datasource.username=root
spring.datasource.password=root

2. 启动调度中心

在 IDE 中启动 xxl-job-admin 项目，访问 http://localhost:8080/xxl-job-admin，使用默认账号 admin 和密码 123456 登录。

六、在 Spring Boot 项目中引入 XXL-JOB

1. 添加 Maven 依赖

在 pom.xml 中添加 xxl-job-core 依赖：

xml 复制代码

<dependency>
    <groupId>com.xuxueli</groupId>
    <artifactId>xxl-job-core</artifactId>
    <version>${project.parent.version}</version>
</dependency>

2. 配置执行器信息

在 src/main/resources 目录下创建 application.properties 文件，配置执行器信息：

properties 复制代码

# web port
server.port=8082

### xxl-job admin address list, such as "http://address" or "http://address01,http://address02"
xxl.job.admin.addresses=http://127.0.0.1:8080/xxl-job-admin
### xxl-job, access token
xxl.job.admin.accessToken=default_token
### xxl-job timeout by second, default 3s
xxl.job.admin.timeout=3

### xxl-job executor appname
xxl.job.executor.appname=xxl-job-executor-sample
### xxl-job executor registry-address: default use address to registry , otherwise use ip:port if address is null
xxl.job.executor.address=
### xxl-job executor server-info
xxl.job.executor.ip=
xxl.job.executor.port=9997
### xxl-job executor log-path
xxl.job.executor.logpath=/data/applogs/xxl-job/jobhandler
### xxl-job executor log-retention-days
xxl.job.executor.logretentiondays=30

3. 配置 XXL-JOB 执行器

创建 XxlJobConfig 类，配置 XXL-JOB 执行器：

java 复制代码

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 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.ip}")
    private String ip;

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

    @Value("${xxl.job.admin.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 xxlJobSpringExecutor = new XxlJobSpringExecutor();
        xxlJobSpringExecutor.setAdminAddresses(adminAddresses);
        xxlJobSpringExecutor.setAppname(appname);
        xxlJobSpringExecutor.setIp(ip);
        xxlJobSpringExecutor.setPort(port);
        xxlJobSpringExecutor.setAccessToken(accessToken);
        xxlJobSpringExecutor.setLogPath(logPath);
        xxlJobSpringExecutor.setLogRetentionDays(logRetentionDays);

        return xxlJobSpringExecutor;
    }
}

4. 创建任务处理器

创建一个任务处理器类，使用 @XxlJob 注解标记任务方法：

java 复制代码

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;

import java.util.concurrent.TimeUnit;

@Component
public class SampleXxlJob {
    private static Logger logger = LoggerFactory.getLogger(SampleXxlJob.class);

    /**
     * 简单任务示例（Bean 模式）
     */
    @XxlJob("demoJobHandler")
    public void demoJobHandler() throws Exception {
        XxlJobHelper.log("XXL-JOB, Hello World.");

        for (int i = 0; i < 5; i++) {
            XxlJobHelper.log("beat at:" + i);
            TimeUnit.SECONDS.sleep(2);
        }
        // 默认任务结果为成功
    }
}

5. 启动 Spring Boot 项目

在 IDE 中启动 Spring Boot 项目，执行器会自动向调度中心注册。

七、在调度中心创建任务

1. 创建执行器

登录调度中心，在 “执行器管理” 页面点击 “新增”，填写执行器信息，其中 “AppName” 要与执行器配置文件中的 xxl.job.executor.appname 一致。

2. 创建任务

在 “任务管理” 页面点击 “新建任务”，配置任务参数：

执行器：选择刚刚创建的执行器。
任务描述：填写任务描述信息。
路由策略：选择合适的路由策略，如 “第一个”。
Cron 表达式：填写任务执行的时间规则，如 0 0/1 * * * ? 表示每分钟执行一次。
JobHandler：填写任务处理器类中 @XxlJob 注解的 value 值，即 demoJobHandler。

3. 启动任务

在任务列表中点击该任务的 “启动” 按钮，任务将按照设定的 Cron 表达式定时执行。

八、查看任务日志

在任务列表中点击该任务的 “日志” 按钮，可查看任务的调度历史记录、调度详情信息、执行信息和执行参数。点击任务日志记录右侧的 “执行日志” 按钮，可进入日志控制台查看任务执行过程中的日志信息。

通过以上步骤，你可以在 Spring Boot 项目中成功引入 XXL-JOB 并创建和执行任务。

定时任务微服务

按下 Cmd/Ctrl + Enter 发送

暂无评论，来发表第一条评论吧！