XXL-JOB定时任务基本使用

大米☋

已于 2025-06-09 13:02:17 修改

阅读量1.9k

点赞数 12

CC 4.0 BY-SA版权

分类专栏：后端文章标签： springboot xxl-job

于 2025-05-17 18:58:19 首次发布

本文链接：https://blog.csdn.net/qq_57404736/article/details/148032159

后端专栏收录该内容

53 篇文章

订阅专栏

前言

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

特性
简单：支持通过Web页面对任务进行CRUD操作，操作简单，一分钟上手；
动态：支持动态修改任务状态、启动/停止任务，以及终止运行中任务，即时生效；
调度中心HA（中心式）：调度采用中心式设计，“调度中心”自研调度组件并支持集群部署，可保证调度中心HA；
执行器HA（分布式）：任务分布式执行，任务"执行器"支持集群部署，可保证任务执行HA；
注册中心: 执行器会周期性自动注册任务, 调度中心将会自动发现注册的任务并触发执行。同时，也支持手动录入执行器地址；
弹性扩容缩容：一旦有新执行器机器上线或者下线，下次调度时将会重新分配任务；
触发策略：提供丰富的任务触发策略，包括：Cron触发、固定间隔触发、固定延时触发、API（事件）触发、人工触发、父子任务触发；
调度过期策略：调度中心错过调度时间的补偿处理策略，包括：忽略、立即补偿触发一次等；
阻塞处理策略：调度过于密集执行器来不及处理时的处理策略，策略包括：单机串行（默认）、丢弃后续调度、覆盖之前调度；
任务超时控制：支持自定义任务超时时间，任务运行超时将会主动中断任务；
任务失败重试：支持自定义任务失败重试次数，当任务失败时将会按照预设的失败重试次数主动进行重试；其中分片任务支持分片粒度的失败重试；
任务失败告警；默认提供邮件方式失败告警，同时预留扩展接口，可方便的扩展短信、钉钉等告警方式；
路由策略：执行器集群部署时提供丰富的路由策略，包括：第一个、最后一个、轮询、随机、一致性HASH、最不经常使用、最近最久未使用、故障转移、忙碌转移等；
分片广播任务：执行器集群部署时，任务路由策略选择"分片广播"情况下，一次任务调度将会广播触发集群中所有执行器执行一次任务，可根据分片参数开发分片任务；
动态分片：分片广播任务以执行器为维度进行分片，支持动态扩容执行器集群从而动态增加分片数量，协同进行业务处理；在进行大数据量业务操作时可显著提升任务处理能力和速度。
故障转移：任务路由策略选择"故障转移"情况下，如果执行器集群中某一台机器故障，将会自动Failover切换到一台正常的执行器发送调度请求。
任务进度监控：支持实时监控任务进度；
Rolling实时日志：支持在线查看调度结果，并且支持以Rolling方式实时查看执行器输出的完整的执行日志；
史版本回溯。
脚本任务：支持以GLUE模式开发和运行脚本任务，包括Shell、Python、NodeJS、PHP、PowerShell等类型脚本;
命令行任务：原生提供通用命令行任务Handler（Bean任务，“CommandJobHandler”）；业务方只需要提供命令行即可；
任务依赖：支持配置子任务依赖，当父任务执行结束且执行成功后将会主动触发一次子任务的执行, 多个子任务用逗号分隔；
一致性：“调度中心”通过DB锁保证集群分布式调度的一致性, 一次任务调度只会触发一次执行；
自定义任务参数：支持在线配置调度任务入参，即时生效；
调度线程池：调度系统多线程触发调度运行，确保调度精确执行，不被堵塞；
数据加密：调度中心和执行器之间的通讯进行数据加密，提升调度信息安全性；
邮件报警：任务失败时支持邮件报警，支持配置多邮件地址群发报警邮件；
推送maven中央仓库: 将会把最新稳定版推送到maven中央仓库, 方便用户接入和使用;
运行报表：支持实时查看运行数据，如任务数量、调度次数、执行器数量等；以及调度报表，如调度日期分布图，调度成功分布图等；
全异步：任务调度流程全异步化设计实现，如异步调度、异步运行、异步回调等，有效对密集调度进行流量削峰，理论上支持任意时长任务的运行；
跨语言/OpenAPI：调度中心与执行器提供语言无关的 OpenApi（RESTful 格式），第三方任意语言可据此对接调度中心或者实现执行器，实现多语言支持。除此之外，还提供了 “多任务模式”和“httpJobHandler”等其他跨语言方案；
国际化：调度中心支持国际化设置，提供中文、英文两种可选语言，默认为中文；
容器化：提供官方docker镜像，并实时更新推送dockerhub，进一步实现产品开箱即用；
线程池隔离：调度线程池进行隔离拆分，慢任务自动降级进入"Slow"线程池，避免耗尽调度线程，提高系统稳定性；
用户管理：支持在线管理系统用户，存在管理员、普通用户两种角色；
权限控制：执行器维度进行权限控制，管理员拥有全量权限，普通用户需要分配执行器权限后才允许相关操作；
AI任务：原生提供AI执行器，并内置多个AI任务Handler，与spring-ai、ollama、dify等集成打通，支持快速开发AI类任务。

环境搭建

拉取源码：xxl-job: 一个分布式任务调度平台，其核心设计目标是开发迅速、学习简单、轻量级、易扩展。现已开放源代码并接入多家公司线上产品线，开箱即用。
本地创建一个空的SpringBoot项目用于测试
环境版本：
JDK：>17
xxl-job：≥3.1.0
spring-boot：3.4.5

使用

1、xxljob服务目录

代码拉下来并且使用IDE打开后，左侧目录用处如下

doc目录：里面存放了数据库脚本以及文档
xxl-job-admin：xxljob的服务端，启动后访问ip+服务端口+服务context-path属性即可打开xxljob前端页面
xxl-job-core：核心包，客户端项目的Maven依赖包
xxl-job-executor-samples：测试模块，里面三个服务是三种项目的测试方式，我们下面参考第二种即可

2、启动xxljob服务

打开doc->db->tables_xxl_job.sql文件，在本地数据库中执行，创建基本的库和表

打开xxl-job-admin服务的application.properties配置文件

可以自行修改端口或使用默认的8080
找到spring.datasource.xxx配置，修改你本地数据库的地址、账号和密码
如需邮件报警功能，修改spring.mail.xxx配置即可

最后启动xxl-job-admin服务即可

3、配置测试服务

以下配置可以参考源码提供的xxl-job-executor-sample-springboot服务，共有如下步骤：

引入依赖
application.properties添加配置文件
手动配置Bean
编写xxljob任务类

3.1、引入`xxl-job-core`依赖

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

3.2、配置文件添加配置

server:
  port: 8888

spring:
  application:
    name: my-spring-boot

xxl:
  job:
    admin:
      ### xxl-job服务端地址
      addresses: http://127.0.0.1:8080/xxl-job-admin
      ### xxl-job, access token，对应到xxl-job-admin的配置文件中的xxl.job.accessToken配置
      accessToken: default_token
      ### 该参数用于设置 XXL-JOB 管理中心（Admin）与执行器（Executor）之间通信的超时时间。如果未配置，默认为 3 秒。
      timeout: 3
    executor:
      ### 一般都会使用项目名，页面上执行器的AppName要和这个值一致
      appname: ${spring.application.name}
      ### 当前服务部署的地址，多个地址用逗号分隔，如果为空则默认使用ip:port
      address:
      ### 客户端所在服务器的ip，如果不填则 服务端自动获取
      ip:
      # 客户端端口，随项目一起启动，不能和当前项目端口冲突
      port: 9999
      ### xxljob日志文件地址
      logpath: /data/applogs/xxl-job/jobhandler
      ### 日志文件存储时长
      logretentiondays: 30

3.3、添加Bean对象

package com.tcc.config;

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;

/**
 * xxl-job config
 *
 * @author xuxueli 2017-04-28
 */
@Configuration
public class XxlJobConfig {
    private Logger logger = LoggerFactory.getLogger(XxlJobConfig.class);

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

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

    @Value("${xxl.job.admin.timeout}")
    private int timeout;

    @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() {
        logger.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.setAccessToken(accessToken);
        xxlJobSpringExecutor.setTimeout(timeout);
        xxlJobSpringExecutor.setLogPath(logPath);
        xxlJobSpringExecutor.setLogRetentionDays(logRetentionDays);

        return xxlJobSpringExecutor;
    }
}

3.4、创建Job类，编写定时任务方法

package com.tcc.job;

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.context.annotation.Configuration;

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

    @XxlJob("testJob")
    public void testJob() {
        // 通过 XxlJobHelper.getJobParam 获取定时任务的传参
        String jobParam = XxlJobHelper.getJobParam();
        log.info("定时任务：testJob，执行成功，参数为：{}", jobParam);
    }
}

3.6、启动测试服务

在这里插入图片描述

4、页面配置

上面我们两个服务(一个xxljob服务端、一个测试服务)都启动完成了，接下来该页面配置了

浏览器访问http://localhost:8080/xxl-job-admin端口和地址要和服务端的配置文件对应的上

默认账号admin，默认密码123456

登录成功后先点击左侧执行器管理，添加执行器

添加完成后，我们等待几分钟，刷新页面，即可发现检测到机器地址了

注册完后，我们再点击任务管理 ，上面选中我们刚刚新加的执行器，右侧新增任务

输入表单信息

保存后在数据右侧下拉中选择执行一次

最后返回服务查看日志即可

5、配置属性详细说明

基础配置：
执行器：任务的绑定的执行器，任务触发调度时将会自动发现注册成功的执行器, 实现任务自动发现功能; 另一方面也可以方便的进行任务分组。每个任务必须绑定一个执行器, 可在 “执行器管理” 进行设置;
任务描述：任务的描述信息，便于任务管理；
负责人：任务的负责人；
报警邮件：任务调度失败时邮件通知的邮箱地址，支持配置多邮箱地址，配置多个邮箱地址时用逗号分隔；

触发配置：
调度类型：
无：该类型不会主动触发调度；
CRON：该类型将会通过CRON，触发任务调度；
固定速度：该类型将会以固定速度，触发任务调度；按照固定的间隔时间，周期性触发；
固定延迟：该类型将会以固定延迟，触发任务调度；按照固定的延迟时间，从上次调度结束后开始计算延迟时间，到达延迟时间后触发下次调度；
CRON：触发任务执行的Cron表达式；
固定速度：固定速度的时间间隔，单位为秒；
固定延迟：固定延迟的时间间隔，单位为秒；

任务配置：
运行模式：
BEAN模式：任务以JobHandler方式维护在执行器端；需要结合 “JobHandler” 属性匹配执行器中任务；
GLUE模式(Java)：任务以源码方式维护在调度中心；该模式的任务实际上是一段继承自IJobHandler的Java类代码并 “groovy” 源码方式维护，它在执行器项目中运行，可使用@Resource/@Autowire注入执行器里中的其他服务；
GLUE模式(Shell)：任务以源码方式维护在调度中心；该模式的任务实际上是一段 “shell” 脚本；
GLUE模式(Python)：任务以源码方式维护在调度中心；该模式的任务实际上是一段 “python” 脚本；
GLUE模式(PHP)：任务以源码方式维护在调度中心；该模式的任务实际上是一段 “php” 脚本；
GLUE模式(NodeJS)：任务以源码方式维护在调度中心；该模式的任务实际上是一段 “nodejs” 脚本；
GLUE模式(PowerShell)：任务以源码方式维护在调度中心；该模式的任务实际上是一段 “PowerShell” 脚本；
JobHandler：运行模式为 “BEAN模式” 时生效，对应执行器中新开发的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队列并以串行方式运行；
丢弃后续调度：调度请求进入单机执行器后，发现执行器存在运行的调度任务，本次请求将会被丢弃并标记为失败；
覆盖之前调度：调度请求进入单机执行器后，发现执行器存在运行的调度任务，将会终止运行中的调度任务并清空队列，然后运行本地调度任务；
任务超时时间：支持自定义任务超时时间，任务运行超时将会主动中断任务；
失败重试次数；支持自定义任务失败重试次数，当任务失败时将会按照预设的失败重试次数主动进行重试；

分片使用

我们现在生产环境一般是分布式部署方式，即最少分两台服务器部署同一个服务，保证服务高可用
如果有一个定时任务需要处理的数据量很大，那么我们就要采用分片式方式执行。即每个服务器分担一点要处理的数据，不要把压力都放在同一个服务器上
下面我们基于上面启动的服务稍作修改后演示

1、启动相同服务

由于我图方便，都放在一台电脑上演示。只要服务名一样即可，端口可以不一样。并且也要修改xxljob客户端的端口

2、添加测试方法

依旧在原来添加的测试方法类中添加方法

@XxlJob("testJob2")
public void testJob2() {
    int shardIndex = XxlJobHelper.getShardIndex();
    int shardTotal = XxlJobHelper.getShardTotal();
    log.info("定时任务：testjob2，执行成功，当前分片索引：{}, 总共可以分：{}片", shardIndex, shardTotal);
}

3、启动新服务

注意，上面改代码了，先重启服务，后执行下面操作。

在上方选择Edit Configurations

选中第一个服务，点击拷贝

选择左侧拷贝后的服务，然后右侧点击Modify options->add VM options

在Vm options输入框中输入-Dserver.port=8889，不要和原来服务的端口冲突

最后点击下面的OK，不要点击run

修改完服务端口后，我们还要修改xxljob的客户端端口

打开application.yml配置文件，修改xxl.job.executor.port端口号为9998，不要和原来启动的服务冲突即可

然后在右上角选中新启动配置，启动即可

4、页面添加定时任务

依旧是之前的操作，但是路由策略选择：分片广播

保存后，新添加的行数据右侧下拉中选择执行一次

最后返回代码，查看两个服务控制台即可

总结

使用步骤：

提前准备
拉取代码

服务端：
在数据库中执行doc->db->tables_xxl_job.sql文件
修改xxl-job-admin服务的配置文件中数据库、文件(如果需要)的配置，然后启动

客户端：
引入xxl-job.core依赖
配置文件中添加xxl-job服务端以及客户端配置
手动注入Bean对象：xxlJobExecutor
编写定时任务方法，并添加注解@XxlJob("jobName")

Web页面：
添加执行器，AppName要和客户端配置的appname一致
任务管理中添加定时任务配置
新增的数据右侧下拉中选择启动，即可根据配置的定时条件执行任务
如果任务有报错，可以在左侧调度日志菜单查看报错

上面只演示了常用的调度的方式，其余定时任务的高级配置属性可以自行尝试