xxl-job使用

概述

XXL-JOB是一个分布式任务调度平台，其核心设计目标是开发迅速、学习简单、轻量级、易扩展。 现已开放源代码并接入多家公司线上产品线，开箱即用。官方地址为：https://www.xuxueli.com/xxl-job/ 。

特性：

  • 1、简单：支持通过Web页面对任务进行CRUD操作，操作简单，一分钟上手；

  • 2、动态：支持动态修改任务状态、启动/停止任务，以及终止运行中任务，即时生效；

  • 3、调度中心HA（中心式）：调度采用中心式设计，“调度中心”自研调度组件并支持集群部署，可保证调度中心HA；

  • 4、执行器HA（分布式）：任务分布式执行，任务”执行器”支持集群部署，可保证任务执行HA；

  • 5、注册中心: 执行器会周期性自动注册任务, 调度中心将会自动发现注册的任务并触发执行。同时，也支持手动录入执行器地址；

  • 6、弹性扩容缩容：一旦有新执行器机器上线或者下线，下次调度时将会重新分配任务；

  • 7、触发策略：提供丰富的任务触发策略，包括：Cron触发、固定间隔触发、固定延时触发、API（事件）触发、人工触发、父子任务触发；

  • 8、调度过期策略：调度中心错过调度时间的补偿处理策略，包括：忽略、立即补偿触发一次等；

  • 9、阻塞处理策略：调度过于密集执行器来不及处理时的处理策略，策略包括：单机串行（默认）、丢弃后续调度、覆盖之前调度；

  • 10、任务超时控制：支持自定义任务超时时间，任务运行超时将会主动中断任务；

  • 11、任务失败重试：支持自定义任务失败重试次数，当任务失败时将会按照预设的失败重试次数主动进行重试；其中分片任务支持分片粒度的失败重试；

  • 12、任务失败告警；默认提供邮件方式失败告警，同时预留扩展接口，可方便的扩展短信、钉钉等告警方式；

  • 13、路由策略：执行器集群部署时提供丰富的路由策略，包括：第一个、最后一个、轮询、随机、一致性HASH、最不经常使用、最近最久未使用、故障转移、忙碌转移等；

  • 14、分片广播任务：执行器集群部署时，任务路由策略选择”分片广播”情况下，一次任务调度将会广播触发集群中所有执行器执行一次任务，可根据分片参数开发分片任务；

  • 15、动态分片：分片广播任务以执行器为维度进行分片，支持动态扩容执行器集群从而动态增加分片数量，协同进行业务处理；在进行大数据量业务操作时可显著提升任务处理能力和速度。

  • 16、故障转移：任务路由策略选择”故障转移”情况下，如果执行器集群中某一台机器故障，将会自动Failover切换到一台正常的执行器发送调度请求。

  • 17、任务进度监控：支持实时监控任务进度；

  • 18、Rolling实时日志：支持在线查看调度结果，并且支持以Rolling方式实时查看执行器输出的完整的执行日志；

  • 19、GLUE：提供Web IDE，支持在线开发任务逻辑代码，动态发布，实时编译生效，省略部署上线的过程。支持30个版本的历史版本回溯。

  • 20、脚本任务：支持以GLUE模式开发和运行脚本任务，包括Shell、Python、NodeJS、PHP、PowerShell等类型脚本;

  • 21、命令行任务：原生提供通用命令行任务Handler（Bean任务，”CommandJobHandler”）；业务方只需要提供命令行即可；

  • 22、任务依赖：支持配置子任务依赖，当父任务执行结束且执行成功后将会主动触发一次子任务的执行, 多个子任务用逗号分隔；

  • 23、一致性：“调度中心”通过DB锁保证集群分布式调度的一致性, 一次任务调度只会触发一次执行；

  • 24、自定义任务参数：支持在线配置调度任务入参，即时生效；

  • 25、调度线程池：调度系统多线程触发调度运行，确保调度精确执行，不被堵塞；

  • 26、数据加密：调度中心和执行器之间的通讯进行数据加密，提升调度信息安全性；

  • 27、邮件报警：任务失败时支持邮件报警，支持配置多邮件地址群发报警邮件；

  • 28、推送maven中央仓库: 将会把最新稳定版推送到maven中央仓库, 方便用户接入和使用;

  • 29、运行报表：支持实时查看运行数据，如任务数量、调度次数、执行器数量等；以及调度报表，如调度日期分布图，调度成功分布图等；

  • 30、全异步：任务调度流程全异步化设计实现，如异步调度、异步运行、异步回调等，有效对密集调度进行流量削峰，理论上支持任意时长任务的运行；

  • 31、跨语言：调度中心与执行器提供语言无关的 RESTful API 服务，第三方任意语言可据此对接调度中心或者实现执行器。除此之外，还提供了 “多任务模式”和“httpJobHandler”等其他跨语言方案；

  • 32、国际化：调度中心支持国际化设置，提供中文、英文两种可选语言，默认为中文；

  • 33、容器化：提供官方docker镜像，并实时更新推送dockerhub，进一步实现产品开箱即用；

  • 34、线程池隔离：调度线程池进行隔离拆分，慢任务自动降级进入”Slow”线程池，避免耗尽调度线程，提高系统稳定性；

  • 35、用户管理：支持在线管理系统用户，存在管理员、普通用户两种角色；

  • 36、权限控制：执行器维度进行权限控制，管理员拥有全量权限，普通用户需要分配执行器权限后才允许相关操作；

下载源码：

访问地址：https://github.com/xuxueli/xxl-job/releases ，下载 XXL-JOB 最新稳定版源码。

源码下载完成后，解压，进入根目录：

  • /doc : 存放相关文档，以及数据库初始化脚本；

  • /xxl-job-admin : Admin 管理后台模块；

  • /xxl-job-core : 平台核心层模块；

  • /xxl-job-executor-samples : 相关使用示例代码；

初始化数据库

使用 IDEA 打开 XXL-JOB 项目，找到 /doc/db/ 文件夹下的 tables_xxl_job.sql 脚本，复制全部 SQL:

修改配置

数据库初始化完毕后，编辑 /xxl-job-admin 模块中的 application.properties 配置文件，修改如下两处：

① ：默认的端口号可能与当前项目服务端口有冲突，自行修改端口；

② : 修改数据库连接、用户名、密码；

启动 XXL-JOB

运行 XxlJobAdminApplication 启动类，若控制台提示信息如下，说明项目运行成功：

管理后台

XXL-JOB 运行成功后，浏览器访问地址：http://localhost:7777/xxl-job-admin/ ， 即可进入到管理后台中，如下图所示，至此本地的 XXL-JOB 就搭建完成了：

Spring Boot 3.x 整合 XXL-JOB

添加执行器

打开 XXL-JOB 管理后台，进入执行器管理菜单中， 默认已经添加了一个执行器，直接点击编辑：
TIP: 执行器的意思就是 —— 定时任务的执行者，即数据对齐服务。

① ：设置执行器唯一标识，这里我修改为了 xxl-job-executor-xiaohashu；
② ：执行器名称；
③ ： 注册方式勾选自动注册，则无需手动填写执行器机器地址；

添加依赖

准备将数据对齐服务注册到 XXL-JOB 中。编辑最外层的 pom.xml 文件，声明 xxl-job 依赖以及版本号，注意，建议和实际搭建 XXL-JOB 的版本保持一致

1
2
3
4
5
6
<!-- XXL-JOB 分布式定时任务调度 -->
       <dependency>
           <groupId>com.xuxueli</groupId>
           <artifactId>xxl-job-core</artifactId>
           <xxl-job.version>2.4.1</xxl-job.version>
       </dependency>

添加配置

依赖添加完毕后，编辑 application-dev.yml 配置文件，添加如下配置：

1
2
3
4
5
6
7
8
9
xxl:
  job:
    adminAddresses: http://127.0.0.1:7777/xxl-job-admin # xxl-job 调度中心部署根地址，如调度中心集群部署存在多个地址则用逗号分隔
    accessToken: default_token # 需要和 xxl-job 上创建的 token 保持一致
    appName: xxx # 需要和 xxl-job 上创建的执行器名称保持一致
    ip: # 执行器 ip, 为空表示自动获取 ip
    port: 10001 # 执行器端口号
    logPath: /data/applogs/xxl-job/jobhandler # 执行器日志存放路径
    logRetentionDays: 30 # 日志保留时间（单位：天）

以上各项配置作用如下：

adminAddresses : 调度中心部署根地址 [选填]：如调度中心集群部署存在多个地址则用逗号分隔。执行器将会使用该地址进行”执行器心跳注册”和”任务结果回调”；为空则关闭自动注册；
accessToken : 执行器通讯TOKEN [选填]：非空时启用；
appName : 执行器 AppName [选填]：执行器心跳注册分组依据；为空则关闭自动注册;
ip : 执行器IP [选填]：默认为空表示自动获取IP，多网卡时可手动设置指定IP，该IP不会绑定Host仅作为通讯实用；地址信息用于 “执行器注册” 和 “调度中心请求并触发任务”；
port : 执行器端口号 [选填]：小于等于0则自动获取；单机部署多个执行器时，注意要配置不同执行器端口；
logPath : 执行器运行日志文件存储磁盘路径 [选填] ：需要对该路径拥有读写权限；为空则使用默认路径；
logRetentionDays : 执行器日志文件保存天数 [选填] ： 过期日志自动清理, 限制值大于等于3时生效; 否则, 如-1, 关闭自动清理功能；

创建 /config 包，并创建下图标注的两个配置类：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
import lombok.Data;
import org.springframework.boot.context.properties.ConfigurationProperties;
import org.springframework.stereotype.Component;

/**
 * @description: xxl-job 配置读取
 **/
@ConfigurationProperties(prefix = XxlJobProperties.PREFIX)
@Component
@Data
public class XxlJobProperties {

    public static final String PREFIX = "xxl.job";

    private String adminAddresses;

    private String accessToken;

    private String appName;

    private String ip;

    private int port;

    private String logPath;

    private int logRetentionDays = 30;
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36

import com.xxl.job.core.executor.impl.XxlJobSpringExecutor;
import jakarta.annotation.Resource;
import lombok.extern.slf4j.Slf4j;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;

/**
 * @description: xxl-job 配置类
 **/
@Configuration
@Slf4j
public class XxlJobConfig {

    @Resource
    private XxlJobProperties xxlJobProperties;

    /**
     * 初始化执行器
     * @return
     */
    @Bean
    public XxlJobSpringExecutor xxlJobExecutor() {
        log.info(">>>>>>>>>>> xxl-job config init.");
        XxlJobSpringExecutor xxlJobSpringExecutor = new XxlJobSpringExecutor();
        xxlJobSpringExecutor.setAdminAddresses(xxlJobProperties.getAdminAddresses());
        xxlJobSpringExecutor.setAppname(xxlJobProperties.getAppName());
        xxlJobSpringExecutor.setIp(xxlJobProperties.getIp());
        xxlJobSpringExecutor.setPort(xxlJobProperties.getPort());
        xxlJobSpringExecutor.setAccessToken(xxlJobProperties.getAccessToken());
        xxlJobSpringExecutor.setLogPath(xxlJobProperties.getLogPath());
        xxlJobSpringExecutor.setLogRetentionDays(xxlJobProperties.getLogRetentionDays());
        return xxlJobSpringExecutor;
    }

}

配置完成后，重启服务，若控制台提示 xxl-job remoting server start success 信息，说明执行器注册到 XXL-JOB 成功：

进入到 XXL-JOB 管理后台中，在执行器管理菜单中，可以看到当前在线的执行器数量，点击查看，还可以看到执行器的 IP 地址与端口号：

创建定时任务
执行器已经注册成功了，接下来，准备创建定时任务。打开管理后台中任务管理菜单，可以看到默认创建了一个任务，编辑它：

相关配置项作用如下：

  • 基础配置：

    • 执行器：选择前面刚刚创建的小哈书执行器；

    • 任务描述：填写任务的职责描述，方便后续维护，我这里描述修改为了创建日增量表任务；

    • 负责人：任务的负责人；

    • 报警邮件：任务调度失败时邮件通知的邮箱地址，支持配置多邮箱地址，配置多个邮箱地址时用逗号分隔；

  • 调度配置：

    • 调度类型：

      • 无：该类型不会主动触发调度；

      • CRON：该类型将会通过CRON，触发任务调度；

      • 固定速度：该类型将会以固定速度，触发任务调度；按照固定的间隔时间，周期性触发；

    • CRON：触发任务执行的Cron表达式，我这里测试填写的是 0/5 * * * * ? , 即每 5s 执行一次任务；

    • 固定速度：固定速度的时间间隔，单位为秒；

    • 固定延迟：固定延迟的时间间隔，单位为秒；

  • 任务配置：

    • 运行模式：任务以 JobHandler 方式维护在执行器端；需要结合 “JobHandler” 属性匹配执行器中任务；

    • JobHandler ：对应执行器中开发的任务类方法上 @XxlJob 注解自定义的 value 值；

  • 高级配置：

    • 路由策略：当执行器集群部署时，提供丰富的路由策略，包括；

    • FIRST（第一个）：固定选择第一个机器；

    • LAST（最后一个）：固定选择最后一个机器；

    • ROUND（轮询）：；

    • RANDOM（随机）：随机选择在线的机器；

    • CONSISTENT_HASH（一致性HASH）：每个任务按照Hash算法固定选择某一台机器，且所有任务均匀散列在不同机器上。

    • LEAST_FREQUENTLY_USED（最不经常使用）：使用频率最低的机器优先被选举；

    • LEAST_RECENTLY_USED（最近最久未使用）：最久未使用的机器优先被选举；

    • FAILOVER（故障转移）：按照顺序依次进行心跳检测，第一个心跳检测成功的机器选定为目标执行器并发起调度；

    • BUSYOVER（忙碌转移）：按照顺序依次进行空闲检测，第一个空闲检测成功的机器选定为目标执行器并发起调度；

    • SHARDING_BROADCAST(分片广播)：广播触发对应集群中所有机器执行一次任务，同时系统自动传递分片参数；可根据分片参数开发分片任务；

    • 子任务：每个任务都拥有一个唯一的任务ID(任务ID可以从任务列表获取)，当本任务执行结束并且执行成功时，将会触发子任务ID所对应的任务的一次主动调度。

    • 调度过期策略：

      • 忽略：调度过期后，忽略过期的任务，从当前时间开始重新计算下次触发时间；

      • 立即执行一次：调度过期后，立即执行一次，并从当前时间开始重新计算下次触发时间；

    • 阻塞处理策略：调度过于密集执行器来不及处理时的处理策略；

      • 单机串行（默认）：调度请求进入单机执行器后，调度请求进入FIFO队列并以串行方式运行；

      • 丢弃后续调度：调度请求进入单机执行器后，发现执行器存在运行的调度任务，本次请求将会被丢弃并标记为失败；

      • 覆盖之前调度：调度请求进入单机执行器后，发现执行器存在运行的调度任务，将会终止运行中的调度任务并清空队列，然后运行本地调度任务；

    • 任务超时时间：支持自定义任务超时时间，任务运行超时将会主动中断任务；

    • 失败重试次数：支持自定义任务失败重试次数，当任务失败时将会按照预设的失败重试次数主动进行重试；

定时任务配置完成后，点击保存按钮。回到服务中，创建 /job 包，用于统一存放置定时任务，并创建 CreateTableXxlJob 自动创建表任务类：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20

import com.xxl.job.core.context.XxlJobHelper;
import com.xxl.job.core.handler.annotation.XxlJob;
import org.springframework.stereotype.Component;


@Component
public class CreateTableXxlJob {

    /**
     * 1、简单任务示例（Bean模式）
     */
    @XxlJob("createTableJobHandler")
    public void createTableJobHandler() throws Exception {
        XxlJobHelper.log("## 开始初始化明日增量数据表...");

        // TODO
    }

}

开发步骤如下：

  • 1、任务开发：在 Spring Bean 实例中，开发 Job 方法；

  • 2、注解配置：为 Job 方法添加注解 “@XxlJob(value=”自定义 jobhandler 名称”, init = “JobHandler 初始化方法”, destroy = “JobHandler 销毁方法”)”，注解 value 值对应的是调度中心新建任务的 JobHandler 属性的值。

  • 3、执行日志：需要通过 “XxlJobHelper.log” 打印执行日志，才能在管理后台中查询到日志信息；

  • 4、任务结果：默认任务结果为 “成功” 状态，不需要主动设置；如有诉求，比如设置任务结果为失败，可以通过 “XxlJobHelper.handleFail/handleSuccess” 自主设置任务结果；

定时任务创建完成后，重启服务。

运行定时任务

回到 XXL-JOB 管理后台中，准备运行定时任务：

① ： 执行一次，即手动立即触发一次定时任务；
② ：启动定时任务，按 Cron 表达式规则来运行定时任务；

查看日志

定时任务运行成功后，可以看到状态为 RUNNING 状态，表示任务正在运行中，点击查询日志，即可查看任务运行的具体日志：

开发
#开发
xxl-job使用
http://bloomivy.github.io/2025/02/01/xxl-job使用/
作者
Bloom
发布于
2025年2月1日
许可协议