XXL-JOB怎么使用？

wen python案例 2026-07-21 5

XXL-JOB怎么使用？从入门到实战的完整指南（2025最新版）

📖 目录导读

XXL-JOB是什么？核心概念速览
环境搭建：5分钟跑通第一个任务
任务开发与部署（含代码示例）
高级特性：分片、路由与动态参数
常见问题Q&A（解决90%的踩坑）

XXL-JOB是什么？核心概念速览

XXL-JOB是一个轻量级分布式任务调度平台，支持任务分片、动态配置、故障转移等特性,其核心架构包含三个角色：

XXL-JOB怎么使用？

调度中心：统一管理任务、分配执行器、触发任务
执行器：部署在业务服务中，接收调度指令并执行具体任务
任务：具体的业务逻辑代码（如：每日数据同步）

适用场景：定时统计报表、订单超时处理、数据清理、分布式爬虫调度等。

环境搭建：5分钟跑通第一个任务

1 下载与启动

# 从Gitee或GitHub下载稳定版
wget https://github.com/xuxueli/xxl-job/archive/refs/tags/2.4.0.tar.gz
# 解压后进入调度中心项目
cd xxl-job-admin
# 初始化数据库（需MySQL 5.7+）
mysql -u root -p < tables_xxl_job.sql
# 启动调度中心（默认端口8080）
mvn clean package -Dmaven.test.skip=true
java -jar xxl-job-admin-2.4.0.jar

2 配置执行器（Spring Boot项目）

在application.yml中添加：

xxl:
  job:
    admin:
      addresses: http://127.0.0.1:8080/xxl-job-admin
    executor:
      appname: my-executor
      port: 9999
      logretentiondays: 30
# 引入Maven依赖
<dependency>
    <groupId>com.xuxueli</groupId>
    <artifactId>xxl-job-core</artifactId>
    <version>2.4.0</version>
</dependency>

3 启动验证

访问 http://localhost:8080/xxl-job-admin（默认账号admin/123456）
在“执行器管理”中看到 my-executor 在线
到“任务管理”中新建一个任务，选择“GLUE(Shell)”类型，输入 echo Hello XXL-JOB
点击“执行一次”，查看日志输出

任务开发与部署（含代码示例）

1 创建Bean模式任务

@Component
public class SampleXxlJob {
    @XxlJob("demoJobHandler")
    public void demoJobHandler() throws Exception {
        XxlJobHelper.log("任务开始执行...");
        // 模拟业务处理
        for (int i = 0; i < 5; i++) {
            Thread.sleep(1000);
            XxlJobHelper.log("处理进度: %d/5", i+1);
        }
        XxlJobHelper.log("任务执行完成");
    }
}

2 配置任务参数

在调度中心“任务管理”中：

JobHandler：填写 demoJobHandler（对应@XxlJob注解值）
Cron：0 0 2 * * ?（每天凌晨2点执行）
路由策略：选择“轮询”或“故障转移”
阻塞策略：推荐“丢弃后续调度”

3 生产级最佳实践

@XxlJob("orderExpireHandler")
public void orderExpireHandler() throws Exception {
    // 获取分片参数（用于分布式场景）
    ShardingUtil.ShardingVO shardingVO = XxlJobHelper.getShardingVo();
    int shardIndex = shardingVO.getIndex();
    int shardTotal = shardingVO.getTotal();
    // 分页查询未支付订单（只处理当前分片）
    List<Order> orders = orderMapper.selectExpiredOrders(
        param -> param.setShardIndex(shardIndex).setShardTotal(shardTotal)
    );
    for (Order order : orders) {
        try {
            expireService.process(order.getId());
            XxlJobHelper.log("订单 %s 处理成功", order.getOrderNo());
        } catch (Exception e) {
            XxlJobHelper.log(e);
        }
    }
}

高级特性：分片、路由与动态参数

1 任务分片实现

当shardTotal=2时，系统会自动向两个节点分配shardIndex=0和shardIndex=1，业务上实现N%2取模即可。

2 动态参数配置

在“任务管理”中配置 任务参数
代码获取：String params = XxlJobHelper.getJobParam();
典型用法：灵活调整任务处理的数据范围或阈值

3 失败告警与重试

失败重试次数：可在执行器配置中设置executor.failRetryCount=3

告警邮箱：调度中心application.properties中配置

spring.mail.host=smtp.qq.com   # 发信服务器
spring.mail.username=yourmail@qq.com
spring.mail.password=授权码

常见问题Q&A（解决90%的踩坑）

❓ Q1: 调度中心启动报错“数据库连接失败”

A：检查application.properties中的数据库配置，重点确认：

MySQL版本需5.7+，且已执行初始化SQL
如果使用0+，记得添加&useSSL=false&serverTimezone=UTC

❓ Q2: 执行器注册不上，调度中心显示离线

A：按顺序排查：

检查执行器IP是否可被调度中心ping通
执行器appname必须与调度中心配置完全一致
防火墙是否放行了执行器port和调度中心addresses中的端口

❓ Q3: 任务执行超时，如何设置？

A：在调度中心的“任务管理”中，编辑任务→“运行模式”选择“BEAN”→“任务超时时间(秒)”设置，例如填300（5分钟）。

❓ Q4: 日志太多导致磁盘爆满怎么办？

A：执行器application.yml中配置：

xxl:
  job:
    executor:
      logretentiondays: 7   # 日志保留天数

调度中心同样可配置xxl.job.logretentiondays

❓ Q5: 能同时运行多个相同任务吗？

A：可以，在任务管理中勾选“允许多机运行”，然后设置路由策略为“轮询”或“随机”,注意此时任务需要实现幂等性。

❓ Q6: 是否需要单独部署执行器服务？

A：不需要，执行器代码可以直接嵌入业务微服务中（例如订单服务、用户服务），只需要在业务服务中添加XXL-JOB依赖并配置执行器参数即可。

❓ Q7: Cron表达式怎样写更准确？

A：推荐工具 crontab.guru（在线生成器）,常用示例：

0 0 3 * * ? → 每天凌晨3点
0 0/15 * * * ? → 每15分钟
0 0 0 1 1 ? 2025 → 2025年1月1日零点

XXL-JOB作为国产开源调度平台，功能完整度堪比商业软件，从单机定时任务迁移到分布式调度，平均只需要半天开发量，关键在于理解其 “调度中心+执行器” 的分离模式，以及灵活运用分片、路由等特性解决高并发场景问题。

建议初学者先从“Bean模式”入手，配合官方文档（官网：xxl-job.com）逐步掌握高级功能，若遇到报错，优先检查网络连通性、执行器注册状态和数据库配置这三个最容易出错的环节。