XXL-JOB 极简入门

1 概述

XXL-JOB 是一个轻量级分布式任务调度平台，其核心设计目标是开发迅速、学习简单、轻量级、易扩展。

从它登记的接入公司列表 ，可以看到拍拍贷、优信二手车、京东、哈啰出行等知名的互联网公司正在使用中。所以，胖友们是可以放心大胆的在项目中使用。

2 特性

XXL-JOB 提供了 35 点特性列表

3 架构设计

3.1设计思想

• 将调度行为抽象形成“调度中心”公共平台，而平台自身并不承担业务逻辑，“调度中心”负责发起调度请求。
• 将任务抽象成分散的 JobHandler ，交由“执行器”统一管理，“执行器”负责接收调度请求并执行对应的 JobHandler中 业务逻辑。

因此，“调度”和“任务”两部分可以相互解耦，提高系统整体稳定性和扩展性。

如果对分布式任务调度平台有一定了解的话，如果从调度系统的角度来看，可以分成两类：

• 中心化： 调度中心和执行器分离，调度中心统一调度，通知某个执行器处理任务。
• 去中心化：调度中心和执行器一体化，自己调度自己执行处理任务。

如此可知 XXL-Job 属于中心化的任务调度平台。目前采用这种方案的还有：

• 链家的 kob
• 美团的 Crane（暂未开源）

去中心化的任务调度平台，目前有：

• Elastic Job
• 唯品会的 Saturn
• Quartz 基于数据库的集群方案
• 淘宝的 TBSchedule（暂停更新，只能使用阿里云 SchedulerX 服务）

3.2 系统组成

整个 XXL-JOB 系统，由调度中心和执行器两个角色组成，分别处于不同的进程中。

调度中心：

• 负责管理调度信息，按照调度配置发出调度请求，自身不承担业务代码。
• 调度系统与任务解耦，提高了系统可用性和稳定性，同时调度系统性能不再受限于任务模块。
• 支持可视化、简单且动态的管理调度信息，包括任务新建，更新，删除， GLUE 开发和任务报警等，所有上述操作都会实时生效。
• 支持监控调度结果以及执行日志，支持执行器 Failover 。

执行器：

• 负责接收调度请求并执行任务逻辑。任务模块专注于任务的执行等操作，开发和维护更加简单和高效。
• 接收“调度中心”的执行请求、终止请求和日志请求等。

一般来说，XXL-JOB 执行器可以内嵌到应用服务里。例如说，一个提供 Restful API 的 Spring Boot 项目中，引入 xxl-job-core 依赖，同时也作为一个 XXL-JOB 执行器。本质上，每次 Restful API 是请求任务，而每次任务调度是定时任务。（？）

3.3架构图

注意，【】 中填写调度中心和执行器；[] 中填写组件名。
注意，左边是调度中心，右边是执行器。
【执行器】：[注册线程] 根据配置的【调度中心】的地址，自动注册到【调度中心】。
【调度中心】：达到任务触发条件，【调度中心】下发任务给【执行器】。
【执行器】：基于 [任务线程池] 执行任务，并把执行结果放入 [内存队列] 中、把 [执行日志] 写入 Log 日志文件中。
【执行器】：[回调线程] 消费 [内存队列] 中的调度结果，主动上报给【调度中心】。
当用户在【调度中心】查看 [Rolling 任务日志]，【调度中心】请求【执行器】，【执行器】读取 Log 日志文件并返回日志详情。

3.4 高可用

XXL-JOB 的高可用，需要考虑调度中心的高可用、以及执行器的高可用。

注意，虽然说 XXL-JOB 执行的是后台任务，即使挂掉，用户的感知度也比较低，但是考虑高可用是一种良好的习惯，在高性能之前请做好高可用。

3.4.1 调度中心的高可用

调度中心支持多节点部署，基于数据库行锁，保证触发器的名称和执行时间相同，则只且仅有一个调度中心节点去下发任务给执行器。

核心代码可见 XXL-JOB 的 JobScheduleHelper#start() 方法：

// JobScheduleHelper.java

// 获得行锁
conn = XxlJobAdminConfig.getAdminConfig().getDataSource().getConnection();
connAutoCommit = conn.getAutoCommit();
conn.setAutoCommit(false);
preparedStatement = conn.prepareStatement(  "select * from xxl_job_lock where lock_name = 'schedule_lock' for update" );
preparedStatement.execute();

// ...触发任务调度

// 事务提交
conn.commit();

3.4.2 执行器的高可用

执行器支持多节点部署，通过调度中心选择其中的执行器，下发任务来执行。

当任务”路由策略”选择”故障转移(FAILOVER)”时，当调度中心每次发起调度请求时，会按照顺序对执行器发出心跳检测请求，第一个检测为存活状态的执行器将会被选定并发送调度请求。

1. 路由策略
   ——调度中心基于路由策略，选择一个执行器节点下发任务，从而让执行器执行任务。XXL-JOB 提供了如下路由策略保证任务调度高可用：

   • 忙碌转移(BUSYOVER)策略：当调度中心每次发起调度请求时，会按照顺序对执行器发出空闲检测请求，第一个检测为空闲状态的执行器将会被选定并发送调度请求。具体代码，见 ExecutorRouteFailover 类。
   • 故障转移(FAILOVER)策略：当调度中心每次发起调度请求时，会按照顺序对执行器发出心跳检测请求，第一个检测为存活状态的执行器将会被选定并发送调度请求。具体代码，见 ExecutorRouteFailover 类。

   还有第一个(FIRST)、LAST(最后一个)、轮询(ROUND)、随机(RANDOM)、CONSISTENT_HASH(一致性 HASH)、最不经常使用(LEAST_FREQUENTLY_USED)、最近最久未使用(LEAST_RECENTLY_USED)、分片广播(SHARDING_BROADCAST)路由策略在 com.xxl.job.admin.core.route.strategy/ 包下

2. 阻塞处理策略
   ——当调度过于密集时，执行器来不及处理时，则当执行器节点存在多个相同任务编号的任务未执行完成，则需要基于阻塞处理策略对任务进行取舍：

   • 单机串行（默认）：调度请求进入单机执行器后，调度请求进入 FIFO 队列并以串行方式运行。
   • 丢弃后续调度：调度请求进入单机执行器后，发现执行器存在运行的调度任务，本次请求将会被丢弃并标记为失败。
   • 覆盖之前调度：调度请求进入单机执行器后，发现执行器存在运行的调度任务，将会终止运行中的调度任务并清空队列，然后运行本地调度任务。

   具体可见 ExecutorBizImpl#run() 方法的代码。

4 搭建调度中心

本小节，我们来搭建一个调度中心。XXL-JOB 暂未提供直接直接启动的 jar 包，所以需要自己编译源码。

考虑到降低大家的学习成本，我们使用 IDEA 进行操作。

4.1 克隆源码

用 IDEA ，从码云 https://gitee.com/xuxueli0323/xxl-job 克隆源码，或者从 XXL-JOB Releases中克隆。

克隆完成后，耐心等待下载完依赖。完成后，整体项目结构如下：

• xxl-job-core模块：XXL-JOB 核心。后续我们在编写执行器时，会引入该模块。
• xxl-job-admin模块：调度中心。
• xxl-job-executor-samples模块：提供了在 Spring、Spring Boot、JFinal、Nutz 等框架下的使用示例。

这里，我们需要编译的主要是 xxl-job-admin 模块，即调度中心。

4.2 初始化 XXL-JOB 表结构

在 doc/db/tables_xxl_job.sql 地址，是 XXL-JOB 表结构的初始化脚本。我们需要在数据库中执行该脚本，完成初始化 XXL-JOB 表结构。如下图所示：XXL-JOB 表结构

• xxl_job_lock：任务调度锁表；
• xxl_job_group：执行器信息表，维护任务执行器信息；
• xxl_job_info：调度扩展信息表： 用于保存 XXL-JOB 调度任务的扩展信息，如任务分组、任务名、机器地址、执行器、执行入参和报警邮件等等；
• xxl_job_log：调度日志表： 用于保存 XXL-JOB 任务调度的历史信息，如调度结果、执行结果、调度入参、调度机器和执行器等等；
• xxl_job_log_report：调度日志报表：用户存储 XXL-JOB 任务调度日志的报表，调度中心报表功能页面会用到；
• xxl_job_logglue：任务GLUE日志：用于保存 GLUE 更新历史，用于支持 GLUE 的版本回溯功能；
• xxl_job_registry：执行器注册表，维护在线的执行器和调度中心机器地址信息；
• xxl_job_user：系统用户表；

自 XXL-JOB 2.1.0 Release 版本，去除对 Quartz 的依赖，所以我们就看不到 Quartz 相关的表哈。

修改配置文件

打开 xxl-job-admin 模块，修改 src/main/resources/application.properties 配置文件。如下：

### web # Web 服务器
server.port=8080
server.context-path=/xxl-job-admin

### actuator
management.context-path=/actuator
management.health.mail.enabled=false

### resources
spring.mvc.static-path-pattern=/static/**
spring.resources.static-locations=classpath:/static/

### freemarker
spring.freemarker.templateLoaderPath=classpath:/templates/
spring.freemarker.suffix=.ftl
spring.freemarker.charset=UTF-8
spring.freemarker.request-context-attribute=request
spring.freemarker.settings.number_format=0.##########

### mybatis
mybatis.mapper-locations=classpath:/mybatis-mapper/*Mapper.xml

### xxl-job, datasource 调度中心 JDBC 链接
spring.datasource.url=jdbc:mysql://127.0.0.1:3306/xxl_job?Unicode=true&characterEncoding=UTF-8
spring.datasource.username=root
spring.datasource.password=root_pwd
spring.datasource.driver-class-name=com.mysql.jdbc.Driver

spring.datasource.type=org.apache.tomcat.jdbc.pool.DataSource
spring.datasource.tomcat.max-wait=10000
spring.datasource.tomcat.max-active=30
spring.datasource.tomcat.test-on-borrow=true
spring.datasource.tomcat.validation-query=SELECT 1
spring.datasource.tomcat.validation-interval=30000

### xxl-job email 报警邮箱
spring.mail.host=smtp.qq.com
spring.mail.port=25
[email protected]
spring.mail.password=xxx
spring.mail.properties.mail.smtp.auth=true
spring.mail.properties.mail.smtp.starttls.enable=true
spring.mail.properties.mail.smtp.starttls.required=true
spring.mail.properties.mail.smtp.socketFactory.class=javax.net.ssl.SSLSocketFactory

### xxl-job, access token 调度中心通讯TOKEN [选填]：非空时启用；调度中心国际化配置 [选填]： 默认为空，表示中文; "en" 表示英文；
xxl.job.accessToken=

### xxl-job, i18n (default empty as chinese, "en" as english)
xxl.job.i18n=

## xxl-job, triggerpool max size 调度线程池最大线程配置
xxl.job.triggerpool.fast.max=200
xxl.job.triggerpool.slow.max=100

### xxl-job, log retention days 调度中心日志表数据保存天数 [必填]：过期日志自动清理；限制大于等于7时生效，否则, 如-1，关闭自动清理功能；
xxl.job.logretentiondays=30

可以看到 XXL-JOB 使用了 Spring Boot ，配置项比较多，说下必须要改的项：

• server.port ：XXL-JOB 调度中心的服务器地址。可以根据自己的需要，修改该端口。
• spring.datasource ：XXL-JOB 调度中心的数据源地址，必须修改成自己准备提供给 XXL-JOB 的数据库地址。
• spring.mail ：报警邮箱，生产环境下必须配置，不然定时任务执行报错都不知道，简直要命。 一般来说下，建议有时间的胖友，修改下 XXL-JOB 的源码，把钉钉告警接入。
• xxl.job.accessToken ：调度中心通讯令牌，建议填写。虽然说，内网一般很安全，但是以防万一，并且又没啥成本，直接给整上。

4.4 修改日志配置文件

打开 xxl-job-admin 模块，修改 src/main/resources/logback.xml 配置文件。如下：

<?xml version="1.0" encoding="UTF-8"?>
<configuration debug="false" scan="true" scanPeriod="1 seconds">

    <contextName>logback</contextName>
    <property name="log.path" value="/data/applogs/xxl-job/xxl-job-admin.log"/>

    <appender name="console" class="ch.qos.logback.core.ConsoleAppender">
        <encoder>
            <pattern>%d{HH:mm:ss.SSS} %contextName [%thread] %-5level %logger{36} - %msg%n</pattern>
        </encoder>
    </appender>

    <appender name="file" class="ch.qos.logback.core.rolling.RollingFileAppender">
        <file>${log.path}</file>
        <rollingPolicy class="ch.qos.logback.core.rolling.TimeBasedRollingPolicy">
            <fileNamePattern>${log.path}.%d{yyyy-MM-dd}.zip</fileNamePattern>
        </rollingPolicy>
        <encoder>
            <pattern>%date %level [%thread] %logger{36} [%file : %line] %msg%n
            </pattern>
        </encoder>
    </appender>

    <root level="info">
        <appender-ref ref="console"/>
        <appender-ref ref="file"/>
    </root>

</configuration>

默认情况下，日志输出的地址是 /data/applogs/xxl-job/xxl-job-admin.log 。可以根据自己的需要，进行调整。

4.5 IDEA 启动调度中心

在开始编译源码之前，我们先直接使用 XxlJobAdminApplication 类，运行启动调度中心。这样，避免我们后面编译源码，进行打包查出来的 jar 包，结果配置文件不对的尴尬。

当看到如下日志，代表启动成功：

启动成功后，浏览器 http://127.0.0.1:8080/xxl-job-admin 地址，并使用默认 “admin/123456” 进行登录。如果登录成功，说明我们已经配置正确啦。

4.6 编译源码

使用 Maven 打包指定 xxl-job-admin 模块，打包完成后，在 xxl-job-admin/target/xxl-job-admin-2.1.2-SNAPSHOT.jar 地址下，就是我们要启动的 XXL-JOB 调度中心的 jar 包。

4.7 命令行启动调度中心

# 启动调度中心
$ jar -jar xxl-job-admin-2.1.2-SNAPSHOT.jar

启动成功后，浏览器 http://127.0.0.1:8080/xxl-job-admin 地址，并使用默认 “admin/123456” 进行登录。如果登录成功，说明我们已经配置正确啦。

另外，启动完成之后，记得右上角，修改下管理员的密码。

4.8 搭建集群

在生产环境下，一定要部署 XXL-JOB 调度中心的集群，提升调度系统容灾和可用性。

调度中心集群部署时，几点要求和建议：

• DB 配置保持一致；
• 集群机器时钟保持一致（单机集群忽视）；
• 推荐通过 Nginx 为调度中心集群做负载均衡，分配域名。调度中心访问、执行器回调配置、调用 API 服务等操作均通过该域名进行。

另外，如果胖友想要使用 Docker 镜像方式搭建调度中心，可以自行参看 XXL-JOB 的官方文档。

5 搭建执行器

5.1 引入依赖

新建一个springboot项目，在 pom.xml 文件中，引入相关依赖。注意这里的依赖版本要与调度中心的版本一致！！

<!-- XXL-JOB 相关依赖 -->
        <dependency>
            <groupId>com.xuxueli</groupId>
            <artifactId>xxl-job-core</artifactId>
            <version>2.3.1</version>
        </dependency>

5.2 应用配置文件

在 application.yml 中，添加 Quartz 的配置，如下：

server:
  port: 9090 #指定一个端口，避免和 XXL-JOB 调度中心的端口冲突。仅仅测试之用

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

5.3 XxlJobConfiguration

在Application同级目录下创建config包，并创建 DataSourceConfiguration 类，配置 XXL-JOB 执行器。代码如下：

@Configuration
public class XxlJobConfiguration {

    @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.accessToken}")
    private String accessToken;
    @Value("${xxl.job.executor.logpath}")
    private String logPath;
    @Value("${xxl.job.executor.logretentiondays}")
    private int logRetentionDays;

    @Bean
    public XxlJobSpringExecutor xxlJobExecutor() {
        // 创建 XxlJobSpringExecutor 执行器
        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;
    }

}

在 xxlJobExecutor() 方法，创建了 Spring 容器下的 XXL-JOB 执行器 Bean 对象。要注意，方法上添加了的 @Bean 注解，配置了启动和销毁方法。

5.4 DemoJob

在Application同级目录下创建job包,并创建 DemoJob 类，示例定时任务类。代码如下：

在xxl-job 2.2版本之前可以使用@JobHandler并继承IJobHandler类

@Component
@JobHandler("demoJob")
public class DemoJob extends IJobHandler {

    private Logger logger = LoggerFactory.getLogger(getClass());

    private final AtomicInteger counts = new AtomicInteger();

    @Override
    public ReturnT<String> execute(String param) throws Exception {
        // 打印日志
        logger.info("[execute][定时第 ({}) 次执行]", counts.incrementAndGet());
        // 返回执行成功
        return ReturnT.SUCCESS;
    }

}

在xxl-job 2.2版本之后，使用@XxlJob替代了原方法

@Component
public class DemoJob {
    private Logger logger = LoggerFactory.getLogger(getClass());
//
    private final AtomicInteger counts = new AtomicInteger();

    @XxlJob("demoJobHandler")
    public ReturnT<String> demoJobHandler(String param) throws Exception {
        logger.info("[execute][定时第 ({}) 次执行]", counts.incrementAndGet());
        return ReturnT.SUCCESS;
    }
}

此时运行项目并不会成功，因为我们还需要在调度中心先注册执行器

5.6 新增执行器

浏览器打开 http://127.0.0.1:8080/xxl-job-admin/jobgroup 地址，即「执行器管理」菜单。如下图：

新增执行器：

在xxl-job 2.3.1版本中，使用自动注册的机器地址不会加上http://而会导致之后调用任务失败，这里推荐手动配置一下

5.7 新建任务

浏览器打开 http://127.0.0.1:8080/xxl-job-admin/jobinfo 地址，即「任务管理」菜单。如下图：

点击最右边的「新增」按钮，弹出「新增」界面。如下图：

填写完记得切换执行器

点击 “demoJob” 任务的「操作」按钮，选择「启动」，确认后，该 “demoJob” 任务的状态就变成了 RUNNING 。

此时，我们打开执行器的 IDE 界面，可以看到 DemoJob 已经在每秒钟执行一次了。