XXL admin 源码解析

Posted 2023-04-19

参考技术A

xxl-job 的 admin 服务是 xxl-job 的调度中心，负责管理和调度注册的 job，关于 xxl-job 的使用，可以阅读 “参考阅读” 中的《XXL-JOB分布式调度框架全面详解》，这里主要是介绍 admin 中的源码。

admin 服务除了管理页面上的一些接口外，还有一些核心功能，比如：

1、根据 job 的配置，自动调度 job；

2、接收 executor 实例的请求，实现注册和下线；

3、监视失败的 job，进行重试；

4、结束一些异常的 job；

5、清理和统计日志；

这些功能都是在 admin 服务启动后，在后台自动运行的，下面将详细介绍 admin 服务这些功能的实现。

XxlJobAdminConfig 是 admin 服务的配置类，在 admin 服务启动时，它除了配置 admin 服务的一些参数外，还会启动 admin 服务的所有后台线程。

该类的属性主要分为5类：

1、配置文件中的参数，比如 accessToken；

2、DAO 层各个数据表的 mapper；

3、Spring 容器中的一些 Bean，比如 JobAlarmer、DataSource 等；

4、私有变量 XxlJobScheduler 对象；

5、私有静态变量 adminConfig，指向实例自身。

该类有两个重要方法，分别实现自接口 InitializingBean、DisposableBean，作用如下：

这两个方法分别调用了 XxlJobScheduler 对象的 init 、 destroy 方法，源码如下：

XxlJobAdminConfig 作为 admin 服务的配置类，作用就是在 Spring 容器启动时，调用 XxlJobScheduler 的初始化方法，来初始化和启动 admin 服务的功能。

XxlJobScheduler 的作用就是调用各个辅助类（xxxHelper）来启动和结束不同的线程和功能，初始化方法 init 的代码如下：

下面我们主要介绍 init 中各个类及其作用，最后再简单一下介绍 destroy 的作用。

当 admin 服务向 executor 实例发出一个调度请求来执行 job 时，会调用 XxlJobTrigger.trigger() 方法把要传输的参数（比如 job_id、jobHandler、job_log_id、阻塞策略等，包装成 TriggerParam 对象）传给 ExecutorBiz 对象来执行一次调度。

xxl-job 对调度过程做了两个优化：

JobTriggerPoolHelper 在 toStart 方法中初始化了它的两个线程池属性，代码如下：

每次有调度请求时，就会在这两个线程池中创建线程，创建线程的逻辑在 addTrigger 方法中。

不同 job 存在执行时长的差异，为了避免不同耗时 job 之间相互阻塞，xxl-job 根据 job 的响应时间，对 job 进行了区分，主要体现在：

如果快 job 与调用频繁的慢 job 在同一个线程池中创建线程，慢 job 会占用大量的线程，导致快 job 线程不能及时运行，降低了线程池和线程的利用率。xxl-job 通过快慢隔离，避免了这个问题。

不能，因为慢 job 还是会占用大量线程，抢占了快 job 的线程资源；增加线程池中的线程数不但没有提升利用率，还会导致大量线程看空闲，利用率反而降低了。最好的方法还是用两个线程池把两者隔离，可以合理地使用各自线程池的资源。

为了记录慢 job 的超时次数，代码中使用一个 map（变量 jobTimeoutCountMap ）来记录一分钟内 job 超时次数，key 值是 job_id，value 是超时次数。在调用 XxlJobTrigger.trigger() 方法之前，会先判断 map 中，该 job_id 的超时次数是否大于 10，如果大于10，就是使用 slowTriggerPool，代码如下：

调用 XxlJobTrigger.trigger() 方法后，根据两个值来更新 jobTimeoutCountMap 的值：

和上面的代码相结合，一个 job 在一分钟内有10次调用超过 500 毫秒，就认为该 job 是一个 频繁调度且耗时的 job。

代码如下：

在该类中，属性变量 minTim 和 jobTimeoutCountMap 都使用 volatile 来修饰，保证了并发调用 addTrigger 时数据的一致性和可见性。

admin 服务发起 job 调度请求时，是在静态方法 public static void trigger() 中调用静态变量 private static JobTriggerPoolHelper helper 的 addTrigger 方法来发起请求的。minTim 和 jobTimeoutCountMap 虽然不是 static 修饰的，但可以看做是全局唯一的（因为持有它们的对象是全局唯一的），因此这两个参数维护的是 admin 服务全局的调度时间和超时次数，为了避免记录的数据量过大，需要每分钟清空一次数据的操作。

admin 服务提供了接口给 executor 来注册和下线，另外，当 executor 长时间（90秒）没有发心跳时，要把 executor 自动下线。前一个功能通过暴露一个接口来接收请求，后一个功能需要开启一个线程，定时更新过期 executor 的状态。

xxl-job 为了提升 admin 服务的性能，在前一个功能的接口接收到 executor 的请求时，不是同步执行，而是在线程池中开启一个线程，异步执行 executor 的注册和下线请求。

JobRegistryHelper 类就负责管理这个线程池和定时线程的。

线程池的定义和初始化代码如下：

executor 实例在发起注册和下线请求时，会调用 AdminBizImpl 类的对应方法，该类的方法如下：

可以看到，AdminBizImpl 类的两个方法都是调用了 JobRegistryHelper 方法来实现，其中 JobRegistryHelper.registry 方法代码如下（registryRemove 代码与之相似）：

这两个方法是通过在线程池 registryOrRemoveThreadPool 中创建线程来异步执行请求，然后把数据更新或新建到数据表 xxl_job_registry 中。

当 executor 注册到 admin 服务后（数据入库到 xxl_job_registry 表），是不会在页面上显示的，需要要用户手动添加 job_group 数据（添加到 xxl_job_group 表），admin 服务会自动把用户添加的 job_group 数据与 xxl_job_registry 数据关联。这就需要 admin 定时从 xxl_job_group 表读取数据，关联 xxl_job_registry 表和 xxl_job_group 表的数据。

这个功能是与 “executor 自动下线” 功能在同一个线程中实现，该线程的主要逻辑是：

相关代码如下：

从这里可以看出，如果是对外接口（接收请求等）的功能，使用线程池和异步线程来实现；如果是一些自动任务，则是通过一个线程来定时执行。

如果一个 Job 调度后，没有响应返回，需要定时重试。作为一种“自动执行”的任务，很显然可以像前面 JobRegistryHelper 一样，使用一个线程定时重试。

在这个类中，定义了一个监视线程，以每10 秒一次的频率运行，对失败的 job 进行重试。如果 job 剩余的重试次数大于0，就会 job 进行重试，并把发送告警信息。线程的定义如下：

在这个线程中，它利用 “数据库执行 UPDATE 语句时会加上互斥锁” 的特性，使用了 “基于数据库的分布式锁”，代码如下所示：

在这个语句中，会把 jobLog 的状态设置为 -1，这是一个无效状态值，当其他线程通过有效状态值来搜索失败记录时，会略过该记录，这样该记录就不会被其他线程重试，达到的分布式锁的功能（这个锁是一个行锁）。或者说，-1状态类似于 java 中的对象头的锁标志位，表明该记录已经被加锁了，其他线程会“忽略”该记录。

在 try 代码块中加锁和解锁，如果加锁后重试时抛出异常，会导致该记录永远无法解锁。所以，应该在 finnally 块中执行解锁操作，或者使用 redis 给锁加一个过期时间来实现分布式锁。

从失败的日志中取出 jobId，查询出对应的 jobInfo 数据，如果日志中的剩余重试次数大于 0，就执行重试。代码如下：

调度任务使用的就是前面介绍的 JobTriggerPoolHelper.trigger 方法，最后更新 jobLog 的 alarm_status 值，有两个作用：

这个类与 JobRegistryHelper 类似，都有一个线程池、一个线程，通过前面 JobRegistryHelper 的学习，可以大胆猜测：

实际上，该类中线程池和线程的作用就是用来 “完成” 一个 job。

当 executor 接收到 admin 的调度请求后，会异步执行 job，并立刻返回一个回调。

admin 接受到回调后，和前面的 “注册、下线” 一样，在线程池中创建线程来处理回调，主要是更新 job 和日志。

当有回调请求时， public callback 方法（该方法被 AdminBizImpl 调用）会在线程池中创建一个线程，遍历回调请求的参数列表，依次处理回调参数，代码如下：

从代码可以看出，最后调用 XxlJobCompleter.updateHandleInfoAndFinish 方法完成回调逻辑。

如果一个 job 较长时间前被调度，但是一直处于 “运行中” 且它所属的 executor 已经超过 90 秒没有心跳了，那么可以认为该 job 已经丢失了，需要把该 job 结束掉。这个就是线程 monitorThread 的主要功能。

monitorThread 会以 60秒 一次的频率，从 xxl_job_log 表中找出 10分钟前调度、仍处于”运行中“状态、executor 已经下线 的 job，然后调用 XxlJobCompleter.updateHandleInfoAndFinish 来更新 handler 的信息和结束 job，代码如下：

从代码可以看出，上面的两个功能最后都调用了 XxlJobCompleter.updateHandleInfoAndFinish 方法，关于该方法的介绍，可以看后面 XxlJobCompleter 部分的介绍，这里不详细展开。

如果去看 XxlJobTrigger.triger 方法，会发现每次调度 job 时，都会先新增一个 jobLog 记录，这也是为什么 JobFailMonitorHelper 中的线程在重试时，先查询 jobLog 的原因。

JobLog 作为 job 的调度记录，还可以用来统计一段时间内 job 的调度次数、成功数等；另外，会清理超出有效期（配置的参数 logretentiondays ）的日志，避免日志数据过大。很显然，这又是一个 ”自动任务“，可以使用一个线程定时完成。

该类持有一个线程变量，线程以 每分钟一次的频率，执行两个操作：

在线程 run 方法的前半部分，线程会统计 3 天内，每天的调度次数、运行次数、成功运行数、失败次数；然后更新或新增 xxl_job_log_report 表的数据。

在线程 run 方法的后半部分，线程按天对日志进行清理，如果当前时间与上次清理的时间相隔超过一天，就会清理日志记录，代码如下：

如果不使用参数 lastCleanLogTime 来记录上次清理的时间，只是清理一天前创建的数据记录。那么该线程每分钟执行一次时，都会删除前天当前时刻的数据，导致前一年的数不完整。

使用参数 lastCleanLogTime 来记录上次清理的时间，并且与当前时间相差超过一天时才清理，能保证前一天的日志是完整的。

不明白为什么清理日志时，不是一次性删除全部的过期日志，而是每次删除 1000条。按理说，这些旧的日志数据应该已经不在 buffer pool 中了，trigger_time 字段又是普通索引，那么 DELETE 操作会先更新到 change buffer 中，之后再合并。现在先查询再删除，相当于多了一次 IO 且没有使用到 change buffer。

admin 服务是用来管理和调度 job 的，用户也可以在它的管理后台新建一个 job，配置 CRON 和 JobHandler，然后 admin 服务就会按照配置的参数来调度 job。很显然，这种“自动化工作”也是由线程定时执行的。

1、如果使用线程调度 Job，存在的第一个问题是：如果某个 Job 在调度时比较耗时，就可能阻塞后续的 Job，导致后续 job 的执行有延迟，怎么解决这个问题？

在前面 JobTriggerPoolHelper 我们已经知道，admin 在调度 job 时是 ”使用线程池、线程“ 异步执行调度任务，避免了主线程的阻塞。

2、使用线程定时调度 job，存在的第二个问题是：怎么保证 job 在指定的时间执行，而不会出现大量延迟？

admin 使用 ”预读“ 的方式，提前读取在未来一段时间内要执行的 job，提前取到内存中，并使用 “时间轮算法” 按时间分组 job，把未来要执行的 job 下一个时间段执行。

3、还隐藏第三个问题：admin 服务是可以多实例部署的，在这种情况下该怎么避免一个 job 被多个实例重复调度？

admin 把一张数据表作为 “分布式锁” 来保证只有一个 admin 实例能执行 job 调度，又通过随机 sleep 线程一段时间，来降低线程之间的竞争。

下面我们就通过代码来了解 xxl-job 是怎么解决上述问题的。

在该类中，定义了一个调度线程，用来调度要执行的 job 和已经过期一段时间的 job，定义代码如下：

该线程会预读出 “下次执行时间 <= now + 5000 毫秒内” 的部分 job，根据它们下一次执行时间划分成三段，执行三种不同的逻辑。

1、下次执行时间在 (- , now - 5000) 范围内

说明过期时间已经大于 5000 毫秒，这时如果过期策略要求调度，就调度一次。代码如下：

2、下次执行时间在 [now - 5000, now) 范围内

说明过期时间小于5000毫秒，只能算是延迟不能算是过期，直接调度一次，代码如下：

如果 job 的下一次执行时间在 5000 毫秒以内，为了省下下次预读的 IO 耗时，这里会记录下 job id，等待后面的调度。

3、下次执行时间在 [now, now + 5000) 范围内

说明还没到执行时间，先记录下 job id， 等待后面的调度 ，代码如下：

上面的3个步骤结束后，会更新 jobInfo 的 trigger_last_time、trigger_next_time、trigger_status 字段：

可以看到，通过预读，一方面会把过期一小段时间的 job 执行一遍，另一方面会把未来一小段时间内要执行的 job 取出，保存进一个 map 对象 ringData 中，等待另一个线程调度。这样就避免了某些 job 到了时间还没执行。

因为 admin 是可以多实例部署的，所以在调度 job 时，需要考虑怎么避免 job 被多次调度。

xxl-job 在前面 JobFailMonitorHelper 中遍历失败的 job 时，会对每个 job 设置一个无效的状态作为 ”分布式行锁“，如果设置失败就跳过。而在这里，如果还使用该方法，有可能出现，一个 job 被设置为无效状态后，线程就崩溃了，导致该 job 永远无法被调度。因此，要尽量避免对 job 状态的修改。

在这里，admin 服务使用一张表 xxl_job_lock 作为分布式锁，每个 admin 实例都要先尝试获取该表的锁，获取成功才能继续执行；同时，为了降低不同实例之间的竞争，会在线程开始执勤随机 sleep 一段时间。

如何获取分布式锁？

在线程中会开启一个事务，设置为手动提交，然后对表 xxl_job_lock 执行 FOR UPDATE 查询。如果该线程执行语句成功，其他实例的线程就会排队等待该表的锁，实现了分布式锁功能。代码如下：

怎么降低锁的竞争？

为了降低锁竞争，在线程开始前会先 sleep 4000 5000 毫秒的随机值（不能大于 5000 毫秒，5000 毫秒是预读的时间范围）；在线程结束当前循环时，会根据耗时和是否有预读数据，选择不同的 sleep 策略：

代码如下：

在前面的线程中，对即将要开始的 job，不是立刻调度，而是按照执行的时刻（秒），把 job id 保存进一个 map 中，然后由 ringThread 线程按时刻进行调度，这只典型的“时间轮算法”。代码如下：

每次轮询调度时，只取出当前时刻（秒）、前一秒内的 job，不会去调度与现在相隔太久的 job。

在执行轮询调度前，有一个时间在 0 1000 毫秒范围内的 sleep。如果没有这个 sleep，该线程会一直执行，而 ringData 中当前时刻（秒）的数据可能已经为空，会导致大量无效的操作；增加了这个 sleep 之后，可以避免这种无效的操作。之所以 sleep 时间在 1000 毫秒以内，是因为调度时刻最小精确到秒，一秒的 sleep 可以避免 job 的延迟。

因为在前面的 scheduleThread 线程中，最后一个操作是把 job 的 next_trigger_time 值更新为大于 now + 5000 毫秒，其他 admin 实例 scheduleThread 线程的查询条件是：next_trigger_time < now + 5000，不会查询出这里调度的 job，所以不需要加分布式锁。

至此，XxlJobScheduler-init 方法的作用我们介绍完毕，下面我们简单介绍一下 XxlJobScheduler-destroy 方法

destroy 方法很简单，就是销毁前面初始化的线程池和线程，它销毁的顺序与前面启动的顺序相反。

代码如下：

因为各个 toStop 方法都很相似，所以我们只介绍 JobScheduleHelper 的 toStop 方法。

该方法的步骤如下：

1、设置停止标志位为 true；

2、sleep 一段时间，让出 CPU 时间片给线程执行任务；

3、如果线程不是终止状态（线程正在 sleep），中断它；

4、线程执行 join 方法，直到线程结束，执行最后一次。

代码如下：

至此，JobScheduleHelper 的主要功能就介绍完了，可以看出， admin 服务在启动时，启动了多个线程池和线程，异步执行任务和异步响应 executor 的请求。

下面，我们介绍前面涉及到的 XxlJobTrigger 和 XxlJobCompleter。

XxlJobTrigger 是调度 job 时的封装类，它主要工作就是接受传入的 jobId、调度参数等，查询对应的 jobGroup、jobInfo，然后调用 ExecutorBiz 对象来执行调度（run 方法）。

该类中三个核心方法及其调用关系如下： trigger -> processTrigger -> runExecutor ，

该方法的功能比较简单，就是根据传入的参数查询 jobGroup 和 jobInfo 对象，设置相关的字段值，然后调用 processTrigger 方法。

该方法的主要工作分为以下几步：

1、保存一条调度日志；

2、从 jobInfo、jobGroup 中取出字段值，构造 TriggerParam 对象；

3、根据 jobInfo 的路由策略，从 jobGroup 中取出要调度的 executor 地址；

4、调用 runExecutor 方法执行调度；

5、保存调度参数、设置调度信息、更新日志。

这里不会修改 jobInfo、jobGroup 对象的字段值，只取出字段值来使用，对这两个对象字段的修改，是在前一步 trigger 方法中进行的。

该方法会执行调度，并返回调度结果，它的核心代码如下：

这里使用 XxlJobScheduler 类取出 ExecutorBiz 对象，以 “懒加载” 的方式给每个 address 创建一个 ExecutorBiz 对象，代码如下：

可以看出，该类中的三个方法其实可以归类为：pre -> execute -> post，在执行前、执行时、执行后做一些前置和收尾工作。

该类在前面 JobCompleteHelper 中被使用，最终 job 的完成就是在该类中执行的，该类有两个主要方法：

下面主要介绍 finishJob 方法。

finishJob 的主要功能是：如果当前任务执行成功了，就调度它的所有子任务，最后把子任务的调度消息添加到当前 job 的日志中。代码如下：

需要注意的是：

1、这里依赖于 JobTriggerPoolHelper 来调度 job，所以在 JobCompleteHelper 的监视线程开始时，有一个 50 秒的等待，就是等待 JobTriggerPoolHelper 启动完成；

2、在 finishJob 方法中，调度子任务的时候，默认子任务的调度结果是成功，注意，这里是指 “调度” 这个行为是成功的，而不是指子任务执行是成功的。

1、XxlJobAdminConfig 作为 admin 服务的启动入口，要尽可能保持简洁，作用类似于一个仓库，来管理和持有所有的类和对象，并不会去启动具体的线程，它只需要“按下启动器的按钮”就可以了；

2、XxlJobScheduler 是 admin 服务的启动器类，它会调用各个辅助类（xxxHelper）来启动对应的线程；

3、对外的接口，比如调度 job、接收注册或下线等，都是使用线程池 + 线程 的异步方式实现，避免 job 对主线程的阻塞；

4、对“自动任务“类的功能，都是使用线程定时执行；

XXL-JOB分布式调度框架全面详解： https://juejin.cn/post/6948397386926391333

时间轮算法：https://spongecaptain.cool/post/widget/timingwheel

一个开源的时间轮算法介绍：https://spongecaptain.cool/post/widget/timingwheel2

【基建—xxl-job定时任务平台】

参考技术A SpringBoot项目，接入定时任务平台xxl-job

1.本地搭建xxl-job环境并启动（网上很多，不做赘述）；
2.SpringBoot项目导入依赖

3.SpringBoot项目核心模块(common-core)配置xxl-job

3.启动类导入配置文件

4.编写JobHandler

5.application.yaml配置xxl-job

6.启动SpringBoot项目
7.登录xxl-job控制台: http://127.0.0.1:8080/xxl-job-admin/ ，账号admin，密码123456
8.新增执行器

刚才选择的是Bean模式，利用Spring环境中写好的Bean执行任务；
还有一种是GLUE模式，将任务以源码形式，在调度中心实时维护：
1.新增任务，选择我们刚刚的执行器，新增任务
“运行模式”选择“GLUE(Java)”，
“阻塞处理策略”选择单机串行，
“JobHandler”可以不选择

然后选择右边的“GLUDE IDE”，编辑可在单独中心实时维护的任务：