沉梦听雨的编程指南
  • 开发日常
  • 工具库篇
  • 定时任务相关
沉梦听雨
2025-01-07
目录

xxl-job学习

# xxl- job 学习

附上笔者写的测视示例：chenmeng-test-demos/demo8-task/task-xxl-job at master · cmty256/chenmeng-test-demos (opens new window)

# 官方文档

源码仓库地址：

快捷克隆指令：git clone https://gitee.com/xuxueli0323/xxl-job.git

对应 git 分支，注意版本号！！！

官方源码架构：

xxl-job-admin：调度中心
xxl-job-core：公共依赖
xxl-job-executor-samples：执行器Sample示例（选择合适的版本执行器，可直接使用，也可以参考其并将现有项目改造成执行器）
    ：xxl-job-executor-sample-springboot：Springboot版本，通过Springboot管理执行器，推荐这种方式；
    ：xxl-job-executor-sample-frameless：无框架版本；
1
2
3
4
5

# 什么是 XXL-JOB？

XXL-JOB 是一个轻量级、分布式、开源的任务调度框架，广泛应用于定时任务的执行和管理，尤其在微服务架构中有着重要的作用。

具备以下特点：

  1. 简单易用：提供直观的 Web 管理界面，方便任务配置和监控。
  2. 分布式支持：支持多节点部署，具备高可用能力。
  3. 强大的任务管理：支持任务分片、失败重试、调度日志等功能。
  4. 丰富的扩展性：支持多种任务执行模式，如 Bean 模式、GLUE 模式等。

# XXL-JOB 的核心架构

XXL-JOB 的架构分为两个核心部分：

  1. 调度中心（Admin）
    • 提供任务调度的管理后台。
    • 负责任务的调度分发、调度结果的存储与展示。
    • 支持任务的创建、修改、删除、手动触发等操作。
  2. 执行器（Executor）
    • 实际执行任务的节点。
    • 可以是单个应用，也可以是多个应用组成的集群。
    • 通过心跳机制向调度中心汇报状态。

# 1、初始化数据库

在官方源码此目录下：doc/db/tables_xxl_job.sql

调度表结构说明：

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

# 2、启动调度中心

调度中心访问地址：http://localhost:8080/xxl-job-admin

作用：统一管理任务调度平台上调度任务，负责触发调度执行，并且提供任务管理平台。

修改配置文件信息：

  • 启动项目前，先将数据库连接信息修改成自己的
### xxl-job, datasource
spring.datasource.url=jdbc:mysql://127.0.0.1:3306/xxl_job?useUnicode=true&characterEncoding=UTF-8&autoReconnect=true&serverTimezone=Asia/Shanghai
spring.datasource.username=root
spring.datasource.password=123456
spring.datasource.driver-class-name=com.mysql.cj.jdbc.Driver
1
2
3
4
5

# 3、启动执行器

# 引入依赖

在 Spring Boot 项目中，引入以下依赖：

<!-- http://repo1.maven.org/maven2/com/xuxueli/xxl-job-core/ -->
<dependency>
    <groupId>com.xuxueli</groupId>
    <artifactId>xxl-job-core</artifactId>
    <version>${最新稳定版本}</version> <!-- 跟随调度中心的版本 -->
</dependency>
1
2
3
4
5
6

# 执行器配置

server:
  port: 9108 # 指定一个端口，避免和 XXL-JOB 调度中心的端口冲突。
spring:
  application:
    name:
      task-xxl-job

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

# 执行器组件配置

@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;
    }

}
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

# 定义任务

使用 @XxlJob 注解定义任务：

  • 官方文档参考：[3.2 BEAN模式（方法形式）](https://www.xuxueli.com/xxl-job/#3.2 BEAN模式（方法形式）)
@Component
public class DemoJob {

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

    private final AtomicInteger counts = new AtomicInteger();

    /**
     * BEAN 模式（方法形式）
     * 注解配置：
     * - 为Job方法添加注解 "@XxlJob(value="自定义jobhandler名称", init = "JobHandler初始化方法", destroy = "JobHandler销毁方法")"，
     * - 注解value值对应的是调度中心新建任务的JobHandler属性的值。
     */
    @XxlJob("demoJob")
    public void execute() throws Exception {
        // 业务打印日志，不能在调度中心查看
        logger.info("[execute][定时第 ({}) 次执行]", counts.incrementAndGet());

        // 官方打印日志，可在调度中心查看
        XxlJobHelper.log("[demoJob][定时第 ({}) 次执行]", counts.incrementAndGet());
    }
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22

# 4、在调度中心配置任务

# 新增执行器

  • 可在 xxl_job_group 执行器信息表中查看到具体的信息

image

# 新增任务

  • 在【任务管理】中新增
  • 联系代码中 @XxlJob("") 注解 的 value 值，对应的是调度中心新建任务的 JobHandler 属性的值

image

# 启动任务

  • 官方文档参考：[4.5 启动/停止任务](https://www.xuxueli.com/xxl-job/#4.5 启动/停止任务)
  • 在【任务管理】中，点击【操作】按钮
  • 此处的启动/停止仅针对任务的后续调度触发行为，不会影响到已经触发的调度任务

# 调度中心查看日志

  • 查看步骤：点击【调度日志】，点击【操作】，点击【执行日志】

image

# 常见问题

# 调度中心和执行器的通信方式是什么？

调度中心和执行器通过 HTTP 接口通信。执行器需要暴露一个 HTTP 服务供调度中心调用。

# 如何实现任务的高可用？

  • 调度中心可以部署为集群模式，保证高可用。
  • 执行器支持多实例部署，实现负载均衡和容错。

# 执行器如何避免任务重复执行？

通过分布式锁机制（如 Redis 锁）可以保证任务在集群环境中不被重复执行。

# 如何监控 XXL-JOB 的运行状态？

调度中心提供任务运行日志和执行器心跳检测功能，开发者可以在 Web 界面查看任务运行情况。

# 学习参考

上次更新: 2025/1/9 17:40:38
Quartz学习
xxl-job高级参数配置篇

← xxl-job高级参数配置篇→

Theme by Vdoing | Copyright © 2023-2025 沉梦听雨 | MIT License