RuoYi-Vue-fast集成XXL-Job：分布式任务调度实践

RuoYi-Vue-fast集成XXL-Job：分布式任务调度实践

【免费下载链接】RuoYi-Vue-fast :tada: (RuoYi)官方仓库 基于SpringBoot，Spring Security，JWT，Vue & Element 的前后端分离权限管理系统 项目地址: https://gitcode.com/GitHub_Trending/ru/RuoYi-Vue-fast

你是否还在为单体应用中的定时任务难以扩展而烦恼？当系统部署多实例时，如何避免任务重复执行？如何监控任务运行状态并进行故障报警？本文将带你一步步实现RuoYi-Vue-fast与XXL-Job的集成，构建稳定高效的分布式任务调度系统。

为什么选择XXL-Job

在分布式系统中，传统的单机定时任务（如Spring的@Scheduled注解）存在以下痛点：

• 任务无法水平扩展，多实例部署时会重复执行
• 缺乏任务管理界面，无法动态调整任务状态
• 没有执行日志和报警机制，故障排查困难
• 不支持任务失败重试和失败处理

XXL-Job（分布式任务调度平台）是一个轻量级分布式任务调度框架，支持任务编排、失败重试、动态配置等功能，完美解决了以上问题。与RuoYi-Vue-fast原有的Quartz调度框架相比，XXL-Job提供了更友好的管理界面和更强大的分布式能力。

集成准备工作

环境要求

• JDK 1.8+
• Maven 3.0+
• MySQL 5.7+
• XXL-Job Admin（管理端）

下载XXL-Job源码

从XXL-Job官方仓库下载最新版本源码，并初始化数据库：

-- 数据库脚本位置：xxl-job/doc/db/tables_xxl_job.sql
-- 可参考项目中现有的SQL文件结构：[sql/quartz.sql](https://link.gitcode.com/i/f5a34ed16b3fc51a31ed243e26193264)

集成步骤

1. 添加XXL-Job依赖

修改项目的pom.xml文件，添加XXL-Job执行器依赖：

<!-- XXL-Job 执行器 -->
<dependency>
    <groupId>com.xuxueli</groupId>
    <artifactId>xxl-job-core</artifactId>
    <version>2.4.0</version>
</dependency>

文件路径：pom.xml

2. 配置执行器

在src/main/resources目录下创建或修改application.yml文件，添加XXL-Job配置：

xxl:
  job:
    admin:
      addresses: http://127.0.0.1:8080/xxl-job-admin  # XXL-Job管理端地址
    executor:
      appname: ruoyi-vue-fast-executor  # 执行器名称
      ip:  # 默认为空，自动获取
      port: 9999  # 执行器端口
      logpath: ./data/xxl-job/logs/  # 日志路径
      logretentiondays: 30  # 日志保留天数
    accessToken:  # 通信令牌，非空时启用

文件路径：src/main/resources/application.yml（假设创建此文件）

3. 创建XXL-Job配置类

在com.ruoyi.framework.xxljob包下创建XxlJobConfig.java：

package com.ruoyi.framework.xxljob;

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;

@Configuration
public class XxlJobConfig {
    private Logger logger = LoggerFactory.getLogger(XxlJobConfig.class);

    @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:0}")
    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() {
        logger.info(">>>>>>>>>>> xxl-job config init.");
        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;
    }
}

文件路径：src/main/java/com/ruoyi/framework/xxljob/XxlJobConfig.java（新建文件）

4. 创建任务处理器

在com.ruoyi.project.job.handler包下创建任务处理器类，替换原有的RyTask.java：

package com.ruoyi.project.job.handler;

import com.xxl.job.core.context.XxlJobHelper;
import com.xxl.job.core.handler.annotation.XxlJob;
import org.springframework.stereotype.Component;
import com.ruoyi.common.utils.StringUtils;

@Component
public class XxlJobHandler {

    /**
     * 测试任务
     */
    @XxlJob("testJobHandler")
    public void testJobHandler() throws Exception {
        String param = XxlJobHelper.getJobParam();
        if (StringUtils.isEmpty(param)) {
            XxlJobHelper.log("任务参数为空");
            return;
        }
        XxlJobHelper.log("执行测试任务，参数：{}", param);
        // 任务逻辑...
    }

    /**
     * 定时清理日志任务
     */
    @XxlJob("logCleanJobHandler")
    public void logCleanJobHandler() throws Exception {
        XxlJobHelper.log("执行日志清理任务");
        // 日志清理逻辑...
    }
}

文件路径：src/main/java/com/ruoyi/project/job/handler/XxlJobHandler.java（新建文件）

配置管理端

1. 启动XXL-Job Admin服务
2. 访问管理界面：http://127.0.0.1:8080/xxl-job-admin
3. 配置执行器：进入"执行器管理"，新增执行器，AppName填写"ruoyi-vue-fast-executor"
4. 创建任务：进入"任务管理"，新增任务，JobHandler填写"testJobHandler"

测试任务

1. 在管理端启动任务
2. 查看执行日志：通过管理端"调度日志"查看任务执行情况
3. 验证业务逻辑：检查任务是否按预期执行

注意事项

1. 端口冲突：确保执行器端口（默认9999）未被占用
2. 网络连通：执行器需能访问XXL-Job Admin
3. 任务幂等性：分布式环境下需确保任务幂等性
4. 日志处理：合理配置日志路径和保留天数
5. 任务超时：根据任务耗时设置合理的超时时间

集成架构图

总结

通过本文的步骤，我们成功将XXL-Job集成到RuoYi-Vue-fast项目中，实现了分布式任务调度。相比原有的Quartz框架，XXL-Job提供了更强大的管理能力和分布式支持，适合在集群环境中使用。

后续可以进一步扩展：

• 集成任务失败报警
• 实现任务依赖调度
• 优化任务执行性能

项目仓库地址：https://gitcode.com/GitHub_Trending/ru/RuoYi-Vue-fast

本文档基于RuoYi-Vue-fast 3.9.0版本编写，XXL-Job版本为2.4.0。实际使用时请根据版本调整配置。

【免费下载链接】RuoYi-Vue-fast :tada: (RuoYi)官方仓库 基于SpringBoot，Spring Security，JWT，Vue & Element 的前后端分离权限管理系统 项目地址: https://gitcode.com/GitHub_Trending/ru/RuoYi-Vue-fast