另一个大脑

主题

XXL-JOB使用手册 ​

XXL-JOB是什么？ ​

XXL-Job是一款开源的分布式任务调度平台，用于实现大规模任务的调度和执行。它是中国开发者开源社区XXL-Code推出的一个项目，旨在解决企业级任务调度的需求。

项目源码结构 ​

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

系统架构 ​

xxl-job由两部分组成，一是调度模块（调度中心），二是执行模块（执行器）。

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

部署 ​

  1. 从github仓库https://github.com/xuxueli/xxl-job下载源码。
  2. 修改\xxl-job\xxl-job-admin\src\main\resources\application.properties配置文件。
    • server.port=8080：端口号
    • 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=root_pwd：数据库密码
    • spring.mail：邮箱配置
    • xxl.job.accessToken：通讯token
    • xxl.job.triggerpool.fast.max=200：快任务最大线程数
    • xxl.job.triggerpool.slow.max=100：慢任务最大线程数
  3. 使用maven编译源码并打包
shell
mvn clean package
  1. 启动控制台应用。
shell
java -jar xxl-job-amind.jar
  1. 访问http://localhost:8080/xxl-job-admin登录调用中心，默认登录账户admin/123456。

任务类型 ​

任务类型分为BEAN模式和GLUE模式。

BEAN模式 ​

一个任务注册为一个bean，分为类形式和方法形式。

BEAN模式的类形式（无框架时使用） ​

支持基于类的开发方式，每个任务对应一个Java类。

执行器项目中，开发Job类，按照以下步骤：

  1. 继承com.xxl.job.core.handler.IJobHandler类，实现其中的方法。
  2. 通过XxlJobSimpleExecutor类的 xxlJobExecutor.setXxlJobBeanList(Arrays.asList(new SampleXxlJob())); 方法注入到执行器容器。
java
XxlJobSimpleExecutor xxlJobExecutor = new XxlJobSimpleExecutor();
// registry job bean
xxlJobExecutor.setXxlJobBeanList(Arrays.asList(new SampleXxlJob()));
// start executor
xxlJobExecutor.start();

BEAN模式的方法形式（Spring时推荐使用） ​

支持基于方法的开发方式，每个任务对应一个方法。

执行器项目中，开发job方法，按照以下步骤：

  1. 使用@XxlJob(value="自定义jobhandler名称", init = "JobHandler初始化方法", destroy = "JobHandler销毁方法")注解方法，value对应控制台的新建任务时的JobHandler。
  • init方法为任务线程初始化时执行，在任务第一次启动时执行。
  • destory方法为任务线程销毁时执行，在应用停止时执行。
java
@Component
public class MethodBeanXxlJobHandler {

    @XxlJob(value = "methodBeanXxlJobHandler", init = "init", destroy = "destroy")
    public void methodBeanXxlJobHandler() {
        XxlJobHelper.log("methodBeanXxlJobHandler hello world");
        System.out.println("methodBeanXxlJobHandler hello world");
    }

    public void init() {
        XxlJobHelper.log("methodBeanXxlJobHandler init");
        System.out.println("methodBeanXxlJobHandler init");
    }

    public void destroy() {
        XxlJobHelper.log("methodBeanXxlJobHandler destroy");
        System.out.println("methodBeanXxlJobHandler destroy");
    }
}
原理 ​
  • 将XxlJobSpringExecutor对象注入到bean容器后，会执行初始化方法afterSingletonsInstantiated
  • afterSingletonsInstantiated方法执行initJobHandlerMethodRepository方法
  • initJobHandlerMethodRepository方法会获取所有被@XxlJob注解的bean
  • 执行registJobHandler方法，获取@XxlJob注解的参数，注册到执行器map的jobHandlerRepository中。

GLUE模式： ​

任务以源码方式维护在调度中心，支持通过Web IDE在线更新，实时编译和生效，因此不需要指定JobHandler。

原理：脚本任务的源码托管在调度中心，脚本逻辑在执行器运行。当触发脚本任务时，执行器会加载脚本源码在执行器机器上生成一份脚本文件，然后通过Java代码调用该脚本；并且实时将脚本输出日志写到任务日志文件中，从而在调度中心可以实时监控脚本运行情况；

开发模式如下：

  1. 在任务管理页面创建任务，运行模式选择为GLUE模式。
  2. 任务创建后，进入任务的GLUE IDE页面，开发任务逻辑。
  3. 完成任务业务逻辑开发，完成后点击保存。

日志 ​

执行日志：需要通过 "XxlJobHelper.log" 打印执行日志；

java
XxlJobHelper.log("XXL-JOB, Hello World.");

分片广播 & 动态分片 ​

执行器集群部署时，任务路由策略选择”分片广播”情况下，一次任务调度将会广播触发对应集群中所有执行器执行一次任务，同时系统自动传递分片参数；可根据分片参数开发分片任务；

分片任务在调度中心调度执行器时，会向执行器传递两个参数，分别为：

  • total：总分片数，执行器集群的总机器数量；
  • index：当前分片序号(从0开始)，执行器集群列表中当前执行器的序号；

在java语言环境下，执行器通过以下api获取分片参数。

java
int shardTotal = XxlJobHelper.getShardTotal();
int shardIndex = XxlJobHelper.getShardIndex();

访问令牌（AccessToken） ​

为提升系统安全性，调度中心和执行器进行安全性校验，双方AccessToken匹配才允许通讯；

  • 调度中心和执行器配置相同的access token，可以正常通讯。
  • 调度中心和执行器均没有配置access token，可以正常通讯。
  • 调度中心和执行器配置的access token不相同，不可以通讯。

springboot下使用xxl-job ​

  1. 引入xxl-job-core等相关依赖。
xml
<dependencies>
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-web</artifactId>
    </dependency>
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-test</artifactId>
        <scope>test</scope>
    </dependency>
    <dependency>
        <groupId>com.xuxueli</groupId>
        <artifactId>xxl-job-core</artifactId>
        <version>${xxl-job-core.version}</version>
    </dependency>
</dependencies>
  1. 在配置文件中添加xxl-job执行器的配置，添加xxl-job调度中心相关信息。
yaml
server:
  port: 7101
xxl:
  job:
    ### 执行器通讯TOKEN [选填]：非空时启用；
    accessToken: default_token
    admin:
      ### 调度中心部署根地址 [选填]：如调度中心集群部署存在多个地址则用逗号分隔。执行器将会使用该地址进行"执行器心跳注册"和"任务结果回调"；为空则关闭自动注册；
      addresses: http://127.0.0.1:7302/xxl-job-admin
    executor:
      ### 执行器注册 [选填]：优先使用该配置作为注册地址，为空时使用内嵌服务 ”IP:PORT“ 作为注册地址。从而更灵活的支持容器类型执行器动态IP和动态映射端口问题。
      address:
      ### 执行器AppName [选填]：执行器心跳注册分组依据；为空则关闭自动注册
      appname: xxl-job-study-executor
      ### 执行器IP [选填]：默认为空表示自动获取IP，多网卡时可手动设置指定IP，该IP不会绑定Host仅作为通讯实用；地址信息用于 "执行器注册" 和 "调度中心请求并触发任务"；
      ip:
      ### 执行器运行日志文件存储磁盘路径 [选填]
      logpath: /data/applogs/xxl-job/jobhandler
      ### 执行器日志文件保存天数 [选填] ： 过期日志自动清理, 限制值大于等于3时生效; 否则, 如-1, 关闭自动清理功能；
      logretentiondays: 30
      ### 执行器端口号 [选填]：小于等于0则自动获取；默认端口为9999，单机部署多个执行器时，注意要配置不同执行器端口；
      port: 9999
  1. 添加configuration类。类中获取配置文件的参数，生成XxlJobSpringExecutor对象并注入到容器中。
java
@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;
    }
}
  1. 开发任务执行器逻辑，使用@XxlJobHandler注解方法。
java
@Component
public class MethodBeanXxlJobHandler {

    @XxlJob(value = "methodBeanXxlJobHandler", init = "init", destroy = "destroy")
    public void methodBeanXxlJobHandler() {
        XxlJobHelper.log("methodBeanXxlJobHandler hello world");
        System.out.println("methodBeanXxlJobHandler hello world");
    }

    public void init() {
        XxlJobHelper.log("methodBeanXxlJobHandler init");
        System.out.println("methodBeanXxlJobHandler init");
    }

    public void destroy() {
        XxlJobHelper.log("methodBeanXxlJobHandler destroy");
        System.out.println("methodBeanXxlJobHandler destroy");
    }
}

Powered by VitePress

Copyright © 2024-present Evan Chen