Xxl-Job 是一个分布式任务调度平台,其核心设计目标是开发迅速、学习简单、轻量级、易扩展。现已开放源代码并接入多家公司线上产品线,开箱即用。本篇博客主要介绍如何进行单机版部署和使用,并在博客最后提供源代码下载。
Gitee 地址:https://gitee.com/xuxueli0323/xxl-job
GitHub 地址:https://github.com/xuxueli/xxl-job
官网帮助文档地址:https://www.xuxueli.com/index.html
一、部署 xxl-job-admin 调度平台
访问 GitHub 地址 https://github.com/xuxueli/xxl-job/releases 下载最新版的源代码 zip 包:
本篇博客在编写时,最新版本的 xxl-job 版本是 2.4.0,下载完成后的 zip 包名称为 xxl-job-2.4.0.zip
之所以要下载源码包,主要是在其源码中,有 mysql 的初始化脚本,以及 springboot 代码样例。
有关 mysql 的安装部署,这里不再赘述,我的 CentOS7 虚拟机上已经部署了 mysql ,因此直接使用。
解压缩源码包 xxl-job-2.4.0.zip 后,在其 doc 目录下的 db 目录中,有个 tables_xxl_job.sql 脚本,内容如下:
#
# XXL-JOB v2.4.0
# Copyright (c) 2015-present, xuxueli.
CREATE database if NOT EXISTS `xxl_job` default character set utf8mb4 collate utf8mb4_unicode_ci;
use `xxl_job`;
SET NAMES utf8mb4;
CREATE TABLE `xxl_job_info` (
`id` int(11) NOT NULL AUTO_INCREMENT,
`job_group` int(11) NOT NULL COMMENT '执行器主键ID',
`job_desc` varchar(255) NOT NULL,
`add_time` datetime DEFAULT NULL,
`update_time` datetime DEFAULT NULL,
`author` varchar(64) DEFAULT NULL COMMENT '作者',
`alarm_email` varchar(255) DEFAULT NULL COMMENT '报警邮件',
`schedule_type` varchar(50) NOT NULL DEFAULT 'NONE' COMMENT '调度类型',
`schedule_conf` varchar(128) DEFAULT NULL COMMENT '调度配置,值含义取决于调度类型',
`misfire_strategy` varchar(50) NOT NULL DEFAULT 'DO_NOTHING' COMMENT '调度过期策略',
`executor_route_strategy` varchar(50) DEFAULT NULL COMMENT '执行器路由策略',
`executor_handler` varchar(255) DEFAULT NULL COMMENT '执行器任务handler',
`executor_param` varchar(512) DEFAULT NULL COMMENT '执行器任务参数',
`executor_block_strategy` varchar(50) DEFAULT NULL COMMENT '阻塞处理策略',
`executor_timeout` int(11) NOT NULL DEFAULT '0' COMMENT '任务执行超时时间,单位秒',
`executor_fail_retry_count` int(11) NOT NULL DEFAULT '0' COMMENT '失败重试次数',
`glue_type` varchar(50) NOT NULL COMMENT 'GLUE类型',
`glue_source` mediumtext COMMENT 'GLUE源代码',
`glue_remark` varchar(128) DEFAULT NULL COMMENT 'GLUE备注',
`glue_updatetime` datetime DEFAULT NULL COMMENT 'GLUE更新时间',
`child_jobid` varchar(255) DEFAULT NULL COMMENT '子任务ID,多个逗号分隔',
`trigger_status` tinyint(4) NOT NULL DEFAULT '0' COMMENT '调度状态:0-停止,1-运行',
`trigger_last_time` bigint(13) NOT NULL DEFAULT '0' COMMENT '上次调度时间',
`trigger_next_time` bigint(13) NOT NULL DEFAULT '0' COMMENT '下次调度时间',
PRIMARY KEY (`id`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;
CREATE TABLE `xxl_job_log` (
`id` bigint(20) NOT NULL AUTO_INCREMENT,
`job_group` int(11) NOT NULL COMMENT '执行器主键ID',
`job_id` int(11) NOT NULL COMMENT '任务,主键ID',
`executor_address` varchar(255) DEFAULT NULL COMMENT '执行器地址,本次执行的地址',
`executor_handler` varchar(255) DEFAULT NULL COMMENT '执行器任务handler',
`executor_param` varchar(512) DEFAULT NULL COMMENT '执行器任务参数',
`executor_sharding_param` varchar(20) DEFAULT NULL COMMENT '执行器任务分片参数,格式如 1/2',
`executor_fail_retry_count` int(11) NOT NULL DEFAULT '0' COMMENT '失败重试次数',
`trigger_time` datetime DEFAULT NULL COMMENT '调度-时间',
`trigger_code` int(11) NOT NULL COMMENT '调度-结果',
`trigger_msg` text COMMENT '调度-日志',
`handle_time` datetime DEFAULT NULL COMMENT '执行-时间',
`handle_code` int(11) NOT NULL COMMENT '执行-状态',
`handle_msg` text COMMENT '执行-日志',
`alarm_status` tinyint(4) NOT NULL DEFAULT '0' COMMENT '告警状态:0-默认、1-无需告警、2-告警成功、3-告警失败',
PRIMARY KEY (`id`),
KEY `I_trigger_time` (`trigger_time`),
KEY `I_handle_code` (`handle_code`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;
CREATE TABLE `xxl_job_log_report` (
`id` int(11) NOT NULL AUTO_INCREMENT,
`trigger_day` datetime DEFAULT NULL COMMENT '调度-时间',
`running_count` int(11) NOT NULL DEFAULT '0' COMMENT '运行中-日志数量',
`suc_count` int(11) NOT NULL DEFAULT '0' COMMENT '执行成功-日志数量',
`fail_count` int(11) NOT NULL DEFAULT '0' COMMENT '执行失败-日志数量',
`update_time` datetime DEFAULT NULL,
PRIMARY KEY (`id`),
UNIQUE KEY `i_trigger_day` (`trigger_day`) USING BTREE
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;
CREATE TABLE `xxl_job_logglue` (
`id` int(11) NOT NULL AUTO_INCREMENT,
`job_id` int(11) NOT NULL COMMENT '任务,主键ID',
`glue_type` varchar(50) DEFAULT NULL COMMENT 'GLUE类型',
`glue_source` mediumtext COMMENT 'GLUE源代码',
`glue_remark` varchar(128) NOT NULL COMMENT 'GLUE备注',
`add_time` datetime DEFAULT NULL,
`update_time` datetime DEFAULT NULL,
PRIMARY KEY (`id`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;
CREATE TABLE `xxl_job_registry` (
`id` int(11) NOT NULL AUTO_INCREMENT,
`registry_group` varchar(50) NOT NULL,
`registry_key` varchar(255) NOT NULL,
`registry_value` varchar(255) NOT NULL,
`update_time` datetime DEFAULT NULL,
PRIMARY KEY (`id`),
KEY `i_g_k_v` (`registry_group`,`registry_key`,`registry_value`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;
CREATE TABLE `xxl_job_group` (
`id` int(11) NOT NULL AUTO_INCREMENT,
`app_name` varchar(64) NOT NULL COMMENT '执行器AppName',
`title` varchar(12) NOT NULL COMMENT '执行器名称',
`address_type` tinyint(4) NOT NULL DEFAULT '0' COMMENT '执行器地址类型:0=自动注册、1=手动录入',
`address_list` text COMMENT '执行器地址列表,多地址逗号分隔',
`update_time` datetime DEFAULT NULL,
PRIMARY KEY (`id`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;
CREATE TABLE `xxl_job_user` (
`id` int(11) NOT NULL AUTO_INCREMENT,
`username` varchar(50) NOT NULL COMMENT '账号',
`password` varchar(50) NOT NULL COMMENT '密码',
`role` tinyint(4) NOT NULL COMMENT '角色:0-普通用户、1-管理员',
`permission` varchar(255) DEFAULT NULL COMMENT '权限:执行器ID列表,多个逗号分割',
PRIMARY KEY (`id`),
UNIQUE KEY `i_username` (`username`) USING BTREE
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;
CREATE TABLE `xxl_job_lock` (
`lock_name` varchar(50) NOT NULL COMMENT '锁名称',
PRIMARY KEY (`lock_name`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;
INSERT INTO `xxl_job_group`(`id`, `app_name`, `title`, `address_type`, `address_list`, `update_time`) VALUES (1, 'xxl-job-executor-sample', '示例执行器', 0, NULL, '2018-11-03 22:21:31' );
INSERT INTO `xxl_job_info`(`id`, `job_group`, `job_desc`, `add_time`, `update_time`, `author`, `alarm_email`, `schedule_type`, `schedule_conf`, `misfire_strategy`, `executor_route_strategy`, `executor_handler`, `executor_param`, `executor_block_strategy`, `executor_timeout`, `executor_fail_retry_count`, `glue_type`, `glue_source`, `glue_remark`, `glue_updatetime`, `child_jobid`) VALUES (1, 1, '测试任务1', '2018-11-03 22:21:31', '2018-11-03 22:21:31', 'XXL', '', 'CRON', '0 0 0 * * ? *', 'DO_NOTHING', 'FIRST', 'demoJobHandler', '', 'SERIAL_EXECUTION', 0, 0, 'BEAN', '', 'GLUE代码初始化', '2018-11-03 22:21:31', '');
INSERT INTO `xxl_job_user`(`id`, `username`, `password`, `role`, `permission`) VALUES (1, 'admin', 'e10adc3949ba59abbe56e057f20f883e', 1, NULL);
INSERT INTO `xxl_job_lock` ( `lock_name`) VALUES ( 'schedule_lock');
commit;
在 mysql 数据库中,运行以上脚本,创建了 xxl_job 数据库,并创建了 8 张表。
下面我们开始部署 xxl-job-admin,在虚拟机上创建目录 /app/xxljob 并在其内部文件夹和文件,具体结果如下:
编写 docker-compose.yml 文件内容如下:
version: "3.5"
services:
xxl-job-admin:
restart: always
image: xuxueli/xxl-job-admin:2.4.0
container_name: xxl-job-admin
volumes:
- /app/xxljob/logs:/data/applogs
ports:
# 端口映射
- "8989:8080"
environment:
# xxl-job-admin 本身就是一个 springboot 程序,因此可以覆盖其参数进行启动
# 覆盖的参数有:数据库连接字符串,连接数据库的账号密码,连接 xxl-job-admin 的 accessToken
PARAMS: "
--spring.datasource.url=jdbc:mysql://192.168.136.128:3306/xxl_job?characterEncoding=utf8&allowMultiQueries=true&useSSL=false
--spring.datasource.username=root
--spring.datasource.password=root
--xxl.job.accessToken=mytest123"
最后在 docker-compose.yml 文件所在目录下,运行 docker-compose up -d
启动服务即可。
上面对外映射的端口是 8989,因此我们访问 http://192.168.136.128:8989/xxl-job-admin
进入登录页面
对于 xxl-job-admin 默认的登录账号是 admin 密码是 123456 ,登录成功后进入首页。
二、添加执行器和任务
我们需要添加一个自定义的执行器,以及 4 个任务,用于下面 SpringBoot 代码演示。
执行器可以简单理解为是对定时任务的分组名称。在左侧菜单中选择【执行器管理】菜单,系统默认有一个 xxl-job-executor-sample 的示例执行器,我们创建一个自己的测试执行器:mytest-executor ,创建成功后界面如下:
然后在左侧选择【任务管理】菜单,添加 4 个任务,添加后的效果如下:
具体每个任务的配置细节,后面会跟代码一起进行展示,这样比较容易理解代码细节。
三、代码细节展示
新建一个 springboot 工程,名称为 springboot_xxljob,具体结构如下所示:
首先看一下 pom 文件中的依赖包:
<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://maven.apache.org/POM/4.0.0
http://maven.apache.org/xsd/maven-4.0.0.xsd">
<modelVersion>4.0.0</modelVersion>
<groupId>com.jobs</groupId>
<artifactId>springboot_xxljob</artifactId>
<version>1.0</version>
<parent>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-parent</artifactId>
<version>2.4.5</version>
</parent>
<properties>
<maven.compiler.source>8</maven.compiler.source>
<maven.compiler.target>8</maven.compiler.target>
</properties>
<dependencies>
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-web</artifactId>
</dependency>
<!--引入 xxl-job 的依赖-->
<dependency>
<groupId>com.xuxueli</groupId>
<artifactId>xxl-job-core</artifactId>
<version>2.4.0</version>
</dependency>
<dependency>
<groupId>org.projectlombok</groupId>
<artifactId>lombok</artifactId>
</dependency>
</dependencies>
</project>
然后看一下 application.yml 中的配置文件内容,主要参考了源码包中的 properties 配置文件。
server:
port: 8080
xxl:
job:
# 连接 xxl-job-admin 的 token 字符串
accessToken: mytest123
admin:
addresses: http://192.168.136.128:8989/xxl-job-admin
executor:
appname: mytest-executor
port: 18989
有关 xxl job 的配置,是我们自己编写的,因此没有任何提示
- accessToken 必须与 docker-compose.yml 中配置的值一样
- addresses 配置为 xxl-job-admin 部署的地址即可
- appname 就是我们上面自己创建的执行器 mytest-executor,可以理解为是对多个定时任务的分组名称
- port 端口是当前 springboot 提供给 xxl-job-admin 调度平台的端口,可以随便自定义
然后我们读取配置文件,对执行器进行配置,并放入 Spring 容器中:
package com.jobs.config;
import com.xxl.job.core.executor.impl.XxlJobSpringExecutor;
import lombok.extern.slf4j.Slf4j;
import org.springframework.beans.factory.annotation.Value;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
@Slf4j
@Configuration
public class XxlJobConfig {
@Value("${xxl.job.accessToken}")
private String accessToken;
@Value("${xxl.job.admin.addresses}")
private String adminAddresses;
@Value("${xxl.job.executor.appname}")
private String appname;
@Value("${xxl.job.executor.port}")
private int port;
@Bean
public XxlJobSpringExecutor xxlJobExecutor() {
log.info("xxl-job 配置初始化...");
XxlJobSpringExecutor xxlJobSpringExecutor = new XxlJobSpringExecutor();
xxlJobSpringExecutor.setAdminAddresses(adminAddresses);
xxlJobSpringExecutor.setAppname(appname);
xxlJobSpringExecutor.setPort(port);
xxlJobSpringExecutor.setAccessToken(accessToken);
return xxlJobSpringExecutor;
}
}
然后编写 4 个被 xxl-job-admin 调用的定时任务的代码:
package com.jobs.jobhandler;
import com.xxl.job.core.context.XxlJobHelper;
import com.xxl.job.core.handler.annotation.XxlJob;
import org.springframework.stereotype.Component;
import java.time.LocalDateTime;
import java.time.format.DateTimeFormatter;
import java.util.ArrayList;
import java.util.List;
@Component
public class MyTestJobs {
// 注解使用方法
// @XxlJob(value="自定义jobhandler名称",
// init = "JobHandler初始化方法",
// destroy = "JobHandler销毁方法")
//----------------------------------------
//该 demo 展示日志记录,以及返回任务执行状态,可以在 web 界面中查看
@XxlJob("JobHandler01")
public void testJob1() {
System.out.println("JobHandler01 每 3 秒执行一次...");
//通过 XxlJobHelper.log 记录的日志,可在 web 界面中进行查看
XxlJobHelper.log("我自定义的日志:"
+ LocalDateTime.now().format(DateTimeFormatter.ofPattern("yyyy-MM-dd HH:mm:ss")));
//通过 XxlJobHelper.handleSuccess 方法,在 web 界面中会展示任务执行成功状态
//默认情况下,任务执行都是成功状态,不需要刻意操作,
//XxlJobHelper.handleSuccess("执行成功");
//通过 XxlJobHelper.handleFail 方法,在 web 界面中会展示任务执行失败状态
//如果任务执行过程中有异常,可以在 catch 方法中记录错误日志,让任务展示执行失败状态
//XxlJobHelper.handleFail("错误日志");
}
//----------------------------------------
//该 demo 展示如果获取 web 界面中配置的传入参数值
@XxlJob("JobHandler02")
public void testJob2() {
//可以通过 XxlJobHelper.getJobParam() 方法获取 web 界面上配置的参数值
//你可以传入 json 格式的参数值,方便在这里进行解析使用。
String parm = XxlJobHelper.getJobParam();
System.out.println("JobHandler02 每 5 秒执行一次,传入的 parm 参数为:" + parm);
}
//----------------------------------------
//该 demo 展示 init 方法和 destory 方法的使用
@XxlJob(value = "JobHandler03", init = "JobHandler03Init", destroy = "JobHandler03Destory")
public void testJob3() {
System.out.println("JobHandler03 每 2 秒执行一次,seq 为:" + seq);
seq = seq + 1;
}
//定义一个变量
private Integer seq;
//自定义 init 方法,
//当前的 Springboot 程序启动后,JobHandler03 第一次被调用之前执行,
//该方法仅仅只会执行一次,除非重启了当前的 Springboot 程序
public void JobHandler03Init() {
seq = 0;
System.out.println("everyFifteenJob 执行了初 init 方法...");
}
//当前的 spring 容器销毁时执行该方法,通常是 SprngBoot 停止的时候销毁 Spring 容器,
//一般情况下我们看不到下面代码打印的日志,除非采用特殊的方案停止 spring 容器。
public void JobHandler03Destory() {
System.out.println("everyFifteenJob 执行了 destory 方法...");
}
//----------------------------------------
//该 demo 演示如果获取分片信息
@XxlJob("JobHandler04")
public void testJobs4() {
//获取该 springboot 程序的分片索引(索引从 0 开始)
int shardIndex = XxlJobHelper.getShardIndex();
//总分片数,springboot 执行器的实例总数
int shardTotal = XxlJobHelper.getShardTotal();
//获取所有的任务列表
List<Integer> list = getList();
//根据【列表索引】与【总分片数】的余数是否等于【分片索引】,确定当前 springboot 程序要执行的任务
for (int i = 0; i < list.size(); i++) {
if (i % shardTotal == shardIndex) {
System.out.println("当前第" + shardIndex + "分片执行了,任务项为:" + list.get(i));
}
}
}
//表示 10000 个任务
public List<Integer> getList() {
List<Integer> list = new ArrayList<>();
for (int i = 0; i < 10000; i++) {
list.add(i);
}
return list;
}
}
注意:代码中 @XxlJob 注解中配置的 value 值,必须与 web 界面中配置的 JobHandler 的值一致。
第一个定时任务,在调度平台的配置界面如下:
代码主要展示定时任务执行时,可以通过 XxlJobHelper.log 方法记录日志,该日志可以在 web 界面的日志界面中查看到。
第二个定时任务,在调度平台的配置界面如下:
代码主要展示如果获取 web 界面中配置的参数值,最好使用 json 的参数值,这样在代码中比较容易解析
第三个任务,在调度平台的配置界面如下:
代码主要展示 @XxlJob 注解中,有关 init 方法和 destory 方法的使用,这俩方法在 SpringBoot 整个生命周期中仅执行一次。
第四个任务,在调度平台的配置界面如下:
代码主要展示如果让每个 SpringBoot 程序,也就是执行器实例,分别执行不同的任务,而不是全部的任务,这样可以分散压力。
本篇博客编写了一个 SpringBoot 程序,如果是在同一台机器上运行多个程序的话,可以修改 application.yml 中的端口,这样就启动了执行器的集群,方便 xxl-job-admin 调度平台使用相关的路由器策略进行调度,比如上面配置的【轮询】、【随机】、【故障转移】、【分片广播】等。这里就不展示具体执行效果的界面了,大家可以下载代码自行验证,我已经测试没有问题了。
本篇博客的源代码下载地址为:https://files.cnblogs.com/files/blogs/699532/springboot_xxljob.zip