XXL-JOB 安装及使用教程

前言

XXL-JOB 是一个可以在 WEB 界面配置执行定时任务的中间件，支持分布式服务调用。XXL-JOB 本身是一个基于 SpringBoot 的 Java WEB 程序，可以部署多个节点组成集群，我们可以通过下载 GitHub 源码进行部署。

一、XXL-JOB 安装教程

进入 XXL-JOB 官网，下方的 README.md 文件讲述了 XXL 的功能。

1. 执行命令下载源码。

git clone [email protected]:xuxueli/xxl-job.git

通过 IDEA 打开后目录如下：

我们先打开 doc/db/tables_xxl_job.sql 文件，里面有创建数据库的建表语句。

2. 本地数据库执行 SQL

执行后得到如下几张表：

3. 修改 application.properties 配置文件

打开 xxl-job-admin/src/main/resources 下的 application.properties 配置文件。

修改数据库配置：

### 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=your_username
spring.datasource.password=your_password
spring.datasource.driver-class-name=com.mysql.cj.jdbc.Driver

将数据库信息配置为你本地的账户密码。

4. 修改报警邮件和 accessToken（可选配置）

spring.mail.host=smtp.qq.com
spring.mail.port=25
[email protected]
[email protected]
spring.mail.password=xxx
### xxl-job, access token
xxl.job.accessToken=c9%a16ft#pQoQH2X^ElMyzLyox9o2$dX

accessToken 用于客户端连接时可配置的 token。

5. 启动 xxl-job-admin

运行 xxl-job-admin/src/main/java 包下的 XxlJobAdminApplication 的 main() 方法，实际为一个 SpringBoot 项目，启动后即运行一个 web 程序。

启动成功后会打印日志：

11:45:13.937 logback [main] INFO  o.s.b.w.e.tomcat.TomcatWebServer - Tomcat started on port(s): 8080 (http) with context path '/xxl-job-admin'
11:45:13.947 logback [main] INFO  c.x.job.admin.XxlJobAdminApplication - Started XxlJobAdminApplication in 1.627 seconds (JVM running for 2.054)
11:45:18.005 logback [xxl-job, admin JobScheduleHelper#scheduleThread] INFO  c.x.j.a.c.thread.JobScheduleHelper - >>>>>>>>> init xxl-job admin scheduler success.

在浏览器中访问 http://localhost:8080/xxl-job-admin/toLogin，出现如下页面，默认登录账户：admin, 密码 123456，第一次登录成功后请修改密码。

二、客户端配置连接

1. 创建一个 SpringBoot 项目（此处自行创建）

引入 Maven 依赖：

<!-- xxl job -->
<dependency>
    <groupId>com.xuxueli</groupId>
    <artifactId>xxl-job-core</artifactId>
    <version>2.4.0</version>
</dependency>

2. yaml 文件配置

xxl:
  job:
    executor:
      appname: ${spring.application.name}
      logpath: ${spring.application.name}/xxl-job
      logretentiondays: 30
    admin:
      addresses: http://127.0.0.1:8080/xxl-job-admin
    accessToken: c9%a16ft#pQoQH2X^ElMyzLyox9o2$dX

将 addresses 修改为自己部署的 xxl-job-admin 地址，accessToken 修改为服务端配置 token，两端需保持一致才能注册成功。

3. 创建启动配置文件

因 xxl-job 没有使用 spring-boot-starter，需自行将配置类注入到 Spring 容器中。

@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("${server.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.setPort(port + 10000);
        xxlJobSpringExecutor.setAccessToken(accessToken);
        xxlJobSpringExecutor.setLogPath(logPath);
        xxlJobSpringExecutor.setLogRetentionDays(logRetentionDays);

        return xxlJobSpringExecutor;
    }
}

这里将客户端接收的端口设置为 server.port+10000，也可指定为 0，将自动获取系统可用端口。

4. 在 xxl-job-admin 中创建执行器

将 AppName 替换为你的服务名，选择自动注册。

5. 启动客户端项目

启动你的客户端程序，将会自动注册到 xxl-job-admin 服务端中：

2024-01-31 14:34:05.854  INFO 7806 --- [      Thread-10] com.xxl.job.core.server.EmbedServer      : >>>>>>>>>>> xxl-job remoting server start success, nettype = class com.xxl.job.core.server.EmbedServer, port = 18990

至此客户端和服务端配置均已完成，接下来我们创建一个任务执行。

三、编写一个定时任务调度

1. 创建一个任务调度

在客户端中编写如下代码，并重新启动客户端。

@Slf4j
@Component
public class XxlJobHandler {

    /**
     * 更新状态
     **/
    @XxlJob("UpdateStatus")
    public void updateStatus() {
        String jobParam = XxlJobHelper.getJobParam();
        log.info("任务执行" + jobParam);
    }

}

注意@XxlJob(“UpdateStatus”)注解中的UpdateStatus，即任务的唯一名称，之后执行任务调度将会使用。

XxlJobHelper.getJobParam();可以用来获取执行任务时传递的参数。

2. xxl-job-admin 中添加任务

主要配置在 Cron 中配置任务调度的时间周期，可选择 Cron 或固定速度。JobHandler 中需配置 @XxlJob 注解中的名称。

3. 执行任务

点击执行一次，任务执行成功将会打印日志

2024-01-31 14:50:20.199  INFO 10123 --- [Pool-1270998288] c.xxl.job.core.executor.XxlJobExecutor   : >>>>>>>>>>> xxl-job regist JobThread success, jobId:2, handler:com.xxl.job.core.handler.impl.MethodJobHandler@58aeccc[class com.example.demo.job.XxlJobHandler#updateStatus]
2024-01-31 14:50:20.201  INFO 10123 --- [2-1706683820199] com.example.demo.job.XxlJobHandler       : 任务执行第一次执行任务

点击启动任务，将会按照我们既定的调度周期执行任务。

这里可以查看我们的调度日志。

4. 定制化拦截器

我们可以通过 Spring Aop 拦截 @XxlJob 注解，去处理一些通用业务逻辑。

@Slf4j
@Order(1)
@Aspect
@Component
public class XxlJobAspect {

    @Pointcut("@annotation(com.xxl.job.core.handler.annotation.XxlJob)")
    public void pointCut() {
    }

    @Around("pointCut() && @annotation(xxlJob)")
    public Object doAround(ProceedingJoinPoint point, XxlJob xxlJob) {
        String traceId = UUID.randomUUID().toString();
        MDC.put("traceId", traceId);

        String jobName = xxlJob.value();
        StopWatch sw = new StopWatch();
        sw.start();
        log.info("定时任务[{}]开始，开始时间：{}，输入参数：{}", jobName, LocalDateTime.now(), XxlJobHelper.getJobParam());
        Object proceed;
        try {
            proceed = point.proceed();
        } catch (Throwable e) {
            log.warn("定时任务[{}]执行失败", jobName, e);
            failure(e, traceId);
            return null;
        }
        sw.stop();
        log.info("定时任务[{}]结束！执行时间：{} ms", jobName, sw.getTotalTimeMillis());
        success(traceId);
        return proceed;
    }

    private void failure(Throwable e, String traceId) {
        XxlJobHelper.handleFail("traceId=" + traceId + ",<br>exception=" + ExceptionUtils.getStackTrace(e));
        MDC.remove("traceId");
    }

    private void success(String traceId) {
        XxlJobHelper.handleSuccess("traceId=" + traceId);
        MDC.remove("traceId");
    }

}

上述代码将拦截在请求日志中串连 traceId，用于查询单次任务执行的链路。

在 logback 配置文件中修改 pattern 包含 %X{traceId}。

再次执行任务将打印日志：

15:03:29.889 [xxl-job, JobThread-2-1706684609877] INFO  c.e.d.a.XxlJobAspect - [doAround,43] 720a7fde-4b7b-4a2d-b5eb-e0f96c3d3dca - 定时任务[UpdateStatus]开始，开始时间：2024-01-31T15:03:29.888977，输入参数：第一次执行任务
15:03:29.893 [xxl-job, JobThread-2-1706684609877] INFO  c.e.d.j.XxlJobHandler - [updateStatus,22] 720a7fde-4b7b-4a2d-b5eb-e0f96c3d3dca - 任务执行第一次执行任务
15:03:29.893 [xxl-job, JobThread-2-1706684609877] INFO  c.e.d.a.XxlJobAspect - [doAround,53] 720a7fde-4b7b-4a2d-b5eb-e0f96c3d3dca - 定时任务[UpdateStatus]结束！执行时间：8 ms

720a7fde-4b7b-4a2d-b5eb-e0f96c3d3dca 即为当前请求中的 traceId，在调度日志中也将打印此 id。