XXL-Job 入门介绍和快速开始

cheniy2025/8/15大约 4 分钟

XXL-Job 入门介绍和快速开始

前置知识

在开始本教程之前，建议您具备以下基础知识：

Java 基础知识
Spring Boot 基础
Maven 构建工具
分布式系统基础概念

什么是 XXL-Job？

XXL-Job 是一个轻量级分布式任务调度平台，其核心设计目标是开发迅速、学习简单、轻量级、易扩展。现已开放源代码并接入多家公司线上产品线，开箱即用。

主要特性

简单灵活
- 支持通过 Web 页面对任务进行 CRUD 操作
- 支持动态修改任务状态、启动/停止任务
- 支持动态修改任务参数以及任务分片参数
丰富的任务类型
- Bean模式任务
- GLUE模式任务
- 命令行任务
- HTTP任务
- 分片广播任务
调度方式
- Cron 表达式调度
- 固定速度调度
- 固定延迟调度
高可用
- 调度中心支持集群部署
- 执行器支持集群部署
- 任务路由策略
- 故障转移

系统架构

整体架构

                   调度中心                                     执行器
+------------------------+                      +-------------------------+
|                        |                      |                         |
|     任务管理（CRUD）    |                      |      任务执行（运行）    |
|     任务调度（调度）    | ----------------->   |      日志回调（回调）    |
|     任务分片（分发）    |                      |                         |
|                        |                      |                         |
+------------------------+                      +-------------------------+

核心组件

调度中心
- 负责管理调度信息
- 按照调度配置发出调度请求
- 接收和执行器心跳信息
- 接收任务执行结果
执行器
- 负责接收调度请求
- 执行任务
- 返回执行结果

快速开始

1. 添加依赖

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

2. 配置执行器

# application.yml
xxl:
  job:
    admin:
      addresses: http://localhost:8080/xxl-job-admin  # 调度中心地址
    executor:
      appname: xxl-job-executor-sample  # 执行器名称
      port: 9999  # 执行器端口号

3. 创建执行器配置类

@Configuration
public class XxlJobConfig {
    
    @Value("${xxl.job.admin.addresses}")
    private String adminAddresses;
    
    @Value("${xxl.job.executor.appname}")
    private String appName;
    
    @Value("${xxl.job.executor.port}")
    private int port;
    
    @Bean
    public XxlJobSpringExecutor xxlJobExecutor() {
        XxlJobSpringExecutor executor = new XxlJobSpringExecutor();
        executor.setAdminAddresses(adminAddresses);
        executor.setAppname(appName);
        executor.setPort(port);
        return executor;
    }
}

4. 编写任务处理类

@Component
public class SampleXxlJob {

    @XxlJob("demoJobHandler")
    public void demoJobHandler() throws Exception {
        System.out.println("XXL-Job 示例任务正在执行....");
        
        // 模拟业务处理
        TimeUnit.SECONDS.sleep(2);
    }
}

任务管理

1. 创建定时任务

在 XXL-Job 调度中心添加一个新任务：

基础配置
- 执行器：选择已配置的执行器
- JobHandler：填写 @XxlJob 注解的值
- 调度类型：CRON
- Cron：*/5 * * * * ?（每5秒执行一次）
高级配置
- 路由策略：第一个
- 阻塞处理策略：单机串行
- 任务超时时间：0
- 失败重试次数：0

2. 任务示例

完整的任务示例代码

@Component
public class ComplexXxlJob {

    private static Logger logger = LoggerFactory.getLogger(ComplexXxlJob.class);

    @XxlJob("complexJobHandler")
    public void complexJobHandler() throws Exception {
        // 1. 获取任务参数
        String param = XxlJobHelper.getJobParam();
        
        // 2. 获取分片参数
        int shardIndex = XxlJobHelper.getShardIndex();
        int shardTotal = XxlJobHelper.getShardTotal();
        
        // 3. 业务逻辑处理
        logger.info("任务开始执行，参数：{}，分片参数：{}/{}", param, shardIndex, shardTotal);
        
        try {
            // 模拟业务处理
            TimeUnit.SECONDS.sleep(2);
            
            // 设置任务结果
            XxlJobHelper.handleSuccess("任务执行成功");
        } catch (Exception e) {
            logger.error("任务执行异常", e);
            XxlJobHelper.handleFail("任务执行失败：" + e.getMessage());
        }
    }
}

最佳实践

开发建议

任务幂等性
- 确保任务可重复执行
- 使用唯一标识防止重复处理
异常处理
- 合理使用 try-catch
- 正确设置任务结果
日志记录
- 记录关键业务节点
- 便于问题排查

运维建议

资源配置
- 合理设置执行器线程池
- 注意任务超时配置
监控告警
- 配置任务失败告警
- 监控任务执行时间

常见问题

1. 如何实现任务失败重试？

在任务配置中设置失败重试次数，示例代码：

@XxlJob("retryJobHandler")
public void retryJobHandler() throws Exception {
    try {
        // 业务逻辑
        doSomething();
    } catch (Exception e) {
        // 任务失败，等待重试
        XxlJobHelper.handleFail();
    }
}

2. 如何实现任务分片？

使用分片参数处理大批量任务，示例代码：

@XxlJob("shardingJobHandler")
public void shardingJobHandler() throws Exception {
    int shardIndex = XxlJobHelper.getShardIndex();
    int shardTotal = XxlJobHelper.getShardTotal();
    
    // 根据分片参数处理数据
    List<Long> ids = getDataIds(shardIndex, shardTotal);
    processData(ids);
}

总结

本文详细介绍了 XXL-Job 的基础知识，包括：

✅ 基本概念：XXL-Job 的特性和架构
✅ 快速开始：环境搭建和基础配置
✅ 任务开发：任务示例和处理流程
✅ 最佳实践：开发和运维建议
✅ 常见问题：重试和分片处理

下一步学习

学习 XXL-Job 的核心功能
了解任务调度的高级特性
探索分布式任务的最佳实践

希望这篇文章能帮助您快速入门 XXL-Job！如果您有任何问题，欢迎在评论区讨论。