XXL-JOB分布式任务调度框架详解（全网最详细！！！）

                        ​​​​​​​   引言

第一部分：XXL-JOB概述

第二部分：架构与组件

第三部分：使用教程

第四部分：源码分析

第五部分：最佳实践

---

引言

在分布式系统中，任务调度是一项基础而又关键的服务，它涉及到定时任务的管理和执行、负载均衡、容错处理等多个方面。XXL-JOB正是这样一款轻量级、高效且易于使用的分布式任务调度框架，它由大众点评的许雪里（XXL）开源，旨在解决分布式环境下定时任务的执行难题。本教案将从XXL-JOB的起源、架构设计、核心功能、使用教程、源码解析、最佳实践以及典型应用场景进行全面深入的讲解，帮助开发者理解和掌握XXL-JOB的精髓。

第一部分：XXL-JOB概述

1.1 起源与发展

XXL-JOB起源于大众点评内部的分布式任务调度需求，自2016年起开始接入线上产品线，至今已迭代数十个版本，广泛应用于互联网、金融、教育、物流等多个行业。其核心设计目标是“开发迅速、学习简单、轻量级、易扩展”，并且提供开箱即用的体验。

1.2 核心设计理念

XXL-JOB通过将调度行为与任务执行解耦的设计思想，形成了两个核心组件：调度中心和执行器。调度中心负责任务的调度策略、触发时机及调度请求的发起，而执行器则负责接收调度请求并执行具体的任务逻辑。

第二部分：架构与组件

2.1 架构图解析

• 调度中心：作为大脑，维护调度信息（任务信息、执行器信息等），并按照预设策略触发任务调度请求。
• 执行器：作为手脚，部署在业务服务器上，负责接收调度中心的任务调度请求并执行任务，执行完毕后将执行结果返回给调度中心。
• 数据库：存储任务配置、执行日志、调度记录等数据，保证调度中心与执行器之间的信息同步。

2.2 核心组件功能

• 任务管理：通过Web界面进行任务的增删改查操作，支持多种调度类型（cron、固定频率、手动触发等）。
• 执行器管理：管理执行器节点，包括注册、心跳检测、负载均衡等功能。
• 日志管理：记录任务执行日志，便于问题排查和审计。
• 报警策略：支持任务执行失败后的邮件、短信等报警通知。

第三部分：使用教程

3.1 快速入门

环境准备：Java开发环境、Maven、MySQL数据库。

<!-- http://repo1.maven.org/maven2/com/xuxueli/xxl-job-core/ -->
<dependency>
    <groupId>com.xuxueli</groupId>
    <artifactId>xxl-job-core</artifactId>
    <version>1.8.2</version>
</dependency>

下载与安装：从GitHub上下载XXL-JOB源码，解压后分别启动调度中心与执行器。

https://github.com/xuxueli/xxl-job 

数据库初始化：执行提供的SQL脚本，创建必要的数据库表。

请下载项目源码并解压，获取 “调度数据库初始化SQL脚本” 并执行即可。

位置：/xxl-job/doc/db/tables_xxl_job.sql 共8张表

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：系统用户表；

配置调度中心与执行器：通过application.properties文件配置数据库连接、执行器地址等。

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

创建任务：登录Web界面，添加任务，配置任务执行逻辑、触发策略等。

调度中心访问地址：http://localhost:8080/xxl-job-admin (该地址执行器将会使用到，作为回调地址)

用户名和密码：admin/123456

至此“调度中心”项目已经部署成功。

3.2 进阶配置

• 分布式部署：多节点部署调度中心，实现高可用。
• 执行器集群：部署多个执行器实例，实现任务的负载均衡与故障转移。
• 自定义JobHandler：编写自定义任务处理器，实现业务逻辑。

第四部分：源码分析

4.1 核心模块

• xxl-job-admin：调度中心模块，包含Web管理界面、调度逻辑等。
• xxl-job-core：核心模块，包含任务调度模型、执行器与调度中心通信协议等。
• xxl-job-executor-samples：执行器示例模块，包含多种框架下的执行器实现。

4.2 关键技术点

• 任务调度算法：分析XXL-JOB如何实现高效的任务调度算法，包括时间轮、延迟队列等。
• 通讯机制：深入理解HTTP长轮询、MQ等通讯方式在XXL-JOB中的应用。
• 容错与重试：分析XXL-JOB的失败重试策略、故障转移机制。

第五部分：最佳实践

搭建springboot项目(执行器)

新建项目：在test模块下新建xxl-job-demo子模块

（1）pom文件

 <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.3.0</version>
        </dependency>
    </dependencies>

(2)配置application.yml

# web port
server.port=8881
# no web
#spring.main.web-environment=false

# log config
logging.config=classpath:logback.xml


### 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.accessToken=default_token

### xxl-job executor appname
xxl.job.executor.appname=xxl-job-executor-test
### 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=9999
### 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

检查执行器中appname是否为：xxl_job_sharding_sample

(3)引导类：

package com.xxl.job;

import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;

@SpringBootApplication
public class XxlJobApplication {

    public static void main(String[] args) {
        SpringApplication.run(XxlJobApplication.class,args);
    }
}

（4）添加xxl-job配置

添加配置类：

这个类主要是创建了任务执行器，参考官方案例编写，无须改动

package com.xxl.job.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
 */
@Configuration
public class XxlJobConfig {
    private Logger logger = LoggerFactory.getLogger(XxlJobConfig.class);

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

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

    @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.setLogPath(logPath);
        xxlJobSpringExecutor.setLogRetentionDays(logRetentionDays);

        return xxlJobSpringExecutor;
    }
}

 （5）创建任务

package com.xxl.job.config;


import com.xxl.job.core.biz.model.ReturnT;
import com.xxl.job.core.handler.annotation.XxlJob;
import org.springframework.beans.factory.annotation.Value;
import org.springframework.stereotype.Component;

import java.time.LocalDateTime;


@Component
public class HelloJob {

    @Value("${server.port}")
    private String port;

    @XxlJob("demoJobHandler")
    public ReturnT helloJob() {
        System.out.println("简单任务执行了。。。。" + port);
        return  ReturnT.SUCCESS;
    }
}

@XxlJob(“demoJobHandler”)这个一定要与调度中心新建任务的JobHandler的值保持一致！

 配置执行器

在任务调度中心，点击进入"执行器管理"界面, 如下图:

1、此处的AppName,会在创建任务时被选择，每个任务必然要选择一个执行器。

2、“执行器列表” 中显示在线的执行器列表, 支持编辑删除。

以下是执行器的属性说明：
AppName  ：是每个执行器集群的唯一标示AppName, 执行器会周期性以AppName为对象进行自动注册：可通过该配置自动发现注册成功的执行器, 供任务调度时使用;
名称 ： 执行器的名称, 因为AppName限制字母数字等组成,可读性不强, 名称为了提高执行器的可读性;
排序 ： 执行器的排序, 系统中需要执行器的地方,如任务新增, 将会按照该排序读取可用的执行器列表;
注册方式  ：调度中心获取执行器地址的方式；
机器地址  ：注册方式为"手动录入"时有效，支持人工维护执行器的地址信息；

具体操作：

（1）新增执行器： xxl-job-executor-test

（2）在调度中心新建任务
在任务管理->新建，填写以下内容

测试

（1）首先启动调度中心，xxl-job-admin

（2）启动xxl-job-demo项目

（3）启动任务：任务调度中心

（4）打开idea控制台，查看任务执行情况：