勤奋的凯尔森同学

# SpringBoot集成XXL-Job企业级实战教程

XXL-Job是一款轻量级分布式任务调度框架，具有易扩展、高可用、操作便捷等特点，广泛应用于企业级项目的定时任务、分布式任务调度场景。本教程将从零开始，基于IDEA 2023 Ultimate、JDK 17、SpringBoot 3.5.10搭建企业级的SpringBoot-XXL-Job项目，完整覆盖XXL-Job的核心集成流程、企业级任务开发及最佳实践，确保你能快速落地到实际项目中。

# 1. 环境准备

# 1.1 开发环境确认

在开始前，请确保你的开发环境满足以下要求：

  • IDE：IntelliJ IDEA 2023 Ultimate 版
  • JDK：17（SpringBoot 3.x 最低要求JDK 17）
  • SpringBoot：3.5.10
  • Maven：3.9.4
  • XXL-Job Admin：已部署，地址为 http://192.168.31.113:8080/xxl-job-admin/，登录账号admin，密码123456，通信端口9999

# 1.2 XXL-Job Admin前置检查

确认XXL-Job Admin服务已正常启动：

  1. 访问 http://192.168.31.113:8080/xxl-job-admin/，能正常显示登录页
  2. 使用admin/123456登录成功，进入控制台
  3. 确认XXL-Job Admin的通信端口9999未被占用

# 2. 新建SpringBoot项目

# 2.1 初始化项目

01

# 2.2 项目结构整理

初始化后，整理项目结构为企业级标准结构：

SpringBoot-XXL-Job
├── src
│   ├── main
│   │   ├── java
│   │   │   └── cc
│   │   │       └── hep
│   │   │           ├── SpringBootXxlJobApplication.java  // 启动类
│   │   │           ├── config                           // 配置类
│   │   │           │   └── XxlJobConfig.java            // XXL-Job核心配置
│   │   │           └── job                              // 任务实现类
│   │   │               ├── SimpleXxlJob.java            // 简单任务
│   │   │               ├── ParamXxlJob.java             // 带参数任务
│   │   │               └── ShardingXxlJob.java          // 分片任务
│   │   └── resources
│   │       └── application.yml                          // 核心配置文件
│   └── test
│       └── java
│           └── cc
│               └── hep
│                   └── SpringBootXxlJobApplicationTests.java
└── pom.xml                                              // 依赖配置
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21

# 3. 引入XXL-Job核心依赖

编辑pom.xml，添加SpringBoot基础依赖和XXL-Job核心依赖（适配SpringBoot 3.x的版本为2.4.0+）：

<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
		 xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 https://maven.apache.org/xsd/maven-4.0.0.xsd">
	<modelVersion>4.0.0</modelVersion>
	<parent>
		<groupId>org.springframework.boot</groupId>
		<artifactId>spring-boot-starter-parent</artifactId>
		<version>3.5.10</version>
		<relativePath/> <!-- lookup parent from repository -->
	</parent>
	<groupId>cc.hep</groupId>
	<artifactId>SpringBoot-XXL-Job</artifactId>
	<version>0.0.1-SNAPSHOT</version>
	<name>SpringBoot-XXL-Job</name>
	<description>SpringBoot集成XXL-Job企业级实战项目</description>

	<properties>
		<java.version>17</java.version>
		<!-- XXL-Job版本（适配SpringBoot3.x） -->
		<xxl-job.version>2.4.0</xxl-job.version>
	</properties>

	<dependencies>
		<!-- SpringBoot核心依赖 -->
		<dependency>
			<groupId>org.springframework.boot</groupId>
			<artifactId>spring-boot-starter</artifactId>
		</dependency>

		<!-- SpringBoot测试依赖 -->
		<dependency>
			<groupId>org.springframework.boot</groupId>
			<artifactId>spring-boot-starter-test</artifactId>
			<scope>test</scope>
		</dependency>

		<!-- XXL-Job核心依赖 -->
		<dependency>
			<groupId>com.xuxueli</groupId>
			<artifactId>xxl-job-core</artifactId>
			<version>${xxl-job.version}</version>
		</dependency>

		<!-- 新增：SpringBoot Web依赖（让项目成为常驻Web应用） -->
		<dependency>
			<groupId>org.springframework.boot</groupId>
			<artifactId>spring-boot-starter-web</artifactId>
		</dependency>
		<!-- 日志依赖（企业级日志规范） -->
		<dependency>
			<groupId>org.slf4j</groupId>
			<artifactId>slf4j-api</artifactId>
		</dependency>
		<dependency>
			<groupId>ch.qos.logback</groupId>
			<artifactId>logback-classic</artifactId>
		</dependency>
	</dependencies>

	<build>
		<plugins>
			<plugin>
				<groupId>org.springframework.boot</groupId>
				<artifactId>spring-boot-maven-plugin</artifactId>
				<version>3.5.10</version>
			</plugin>
		</plugins>
	</build>
</project>
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69

依赖说明：

  • xxl-job-core：XXL-Job执行器核心依赖，2.4.0及以上版本兼容SpringBoot 3.x
  • 日志依赖：统一日志输出，符合企业级日志规范

# 4. XXL-Job核心配置

# 4.1 配置文件

在resources目录下编写application.yml，配置XXL-Job执行器核心参数：

# 服务器端口（避免与XXL-Job Admin的8080冲突）
server:
  port: 8081

# Spring配置
spring:
  application:
    name: SpringBoot-XXL-Job

# XXL-Job配置
xxl:
  job:
    enabled: true
    admin:
      addresses: http://192.168.31.113:8080/xxl-job-admin/
    executor:
      appname: springboot-xxl-job-executor
      # 这里改成你的实际IP：192.168.31.16
      ip: 192.168.31.16
      port: 9999
      # Windows下改为相对路径
      logpath: ./logs/xxl-job
      logretentiondays: 30
    accessToken: Hep@XXLJob2026&Admin
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24

配置说明：

  • admin.addresses：必须与XXL-Job Admin的实际地址一致
  • executor.appname：执行器唯一标识，控制台添加执行器时需完全匹配
  • executor.port：用户指定的通信端口9999，需确保未被占用
  • logpath：企业级部署时建议配置绝对路径，便于日志收集和排查

# 4.2 配置类

在cc.hep.config包下编写XXL-Job核心配置类，注入执行器核心Bean：

package cc.hep.config;

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 static final 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}")
    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.");
        logger.info("Admin addresses: {}", adminAddresses);
        logger.info("App name: {}", appname);
        logger.info("IP: {}", ip.isEmpty() ? "自动获取" : ip);
        logger.info("Port: {}", port);

        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;
    }
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54

配置类说明：

  • XxlJobSpringExecutor：XXL-Job针对Spring的执行器核心Bean，必须注入
  • 所有参数通过@Value从application.yml读取，符合企业级“配置与代码分离”规范
  • 添加日志输出，便于启动时排查配置问题

# 5. 企业级任务开发

基于XXL-Job的注解式开发，编写不同场景的企业级任务（覆盖简单任务、参数任务、分片任务）。

# 5.1 简单定时任务（无参数）

在cc.hep.job包下编写SimpleXxlJob，实现无参数的基础定时任务：

package cc.hep.job;

import com.xxl.job.core.context.XxlJobHelper;
import com.xxl.job.core.handler.annotation.XxlJob;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import org.springframework.stereotype.Component;

/**
 * 简单定时任务（企业级规范：类名+Job，方法名清晰）
 * @author hep
 */
@Component
public class SimpleXxlJob {
    private static final Logger logger = LoggerFactory.getLogger(SimpleXxlJob.class);

    /**
     * 简单任务示例
     * @XxlJob注解：value为任务唯一标识（控制台配置需一致）
     */
    @XxlJob("simpleXxlJobHandler")
    public void simpleXxlJobHandler() {
        // 1. 任务日志（企业级规范：输出任务开始日志）
        logger.info(">>>>>>>>>>> 简单定时任务开始执行 <<<<<<<<<<<");

        try {
            // 2. 核心业务逻辑（模拟企业级数据处理）
            String jobParam = XxlJobHelper.getJobParam(); // 获取任务参数（此处为空）
            logger.info("当前任务参数：{}", jobParam);
            logger.info("执行企业级业务逻辑：数据同步、报表生成等");

            // 3. 任务结果返回（XXL-Job控制台可见）
            XxlJobHelper.handleSuccess("简单定时任务执行成功");
        } catch (Exception e) {
            // 4. 异常处理（企业级规范：捕获所有异常，标记任务失败）
            logger.error("简单定时任务执行失败", e);
            XxlJobHelper.handleFail("简单定时任务执行失败：" + e.getMessage());
        } finally {
            logger.info(">>>>>>>>>>> 简单定时任务执行结束 <<<<<<<<<<<");
        }
    }
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42

核心说明：

  • @Component：将任务类交给Spring容器管理，XXL-Job才能扫描到
  • @XxlJob("simpleXxlJobHandler")：任务唯一标识（Handler名称），控制台配置任务时需一致
  • XxlJobHelper：XXL-Job提供的工具类，用于获取参数、返回执行结果、日志输出等
  • 异常捕获：企业级任务必须捕获所有异常，避免任务中断且便于排查

# 5.2 带参数任务

编写ParamXxlJob，实现支持动态参数的任务（企业级常用场景）：

package cc.hep.job;

import com.xxl.job.core.context.XxlJobHelper;
import com.xxl.job.core.handler.annotation.XxlJob;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import org.springframework.stereotype.Component;

/**
 * 带参数任务（企业级场景：动态传入业务参数）
 * @author hep
 */
@Component
public class ParamXxlJob {
    private static final Logger logger = LoggerFactory.getLogger(ParamXxlJob.class);

    /**
     * 带参数任务示例
     */
    @XxlJob("paramXxlJobHandler")
    public void paramXxlJobHandler() {
        logger.info(">>>>>>>>>>> 带参数任务开始执行 <<<<<<<<<<<");

        try {
            // 1. 获取控制台配置的任务参数（企业级场景：JSON格式参数）
            String jobParam = XxlJobHelper.getJobParam();
            logger.info("接收的任务参数：{}", jobParam);

            // 2. 模拟参数解析（企业级规范：参数校验+JSON解析）
            if (jobParam == null || jobParam.isEmpty()) {
                throw new IllegalArgumentException("任务参数不能为空");
            }
            // 示例：解析JSON参数（实际项目可引入fastjson/jackson）
            // JSONObject paramJson = JSONObject.parseObject(jobParam);

            // 3. 核心业务逻辑
            logger.info("根据参数执行业务逻辑：{}", jobParam);

            XxlJobHelper.handleSuccess("带参数任务执行成功，参数：" + jobParam);
        } catch (Exception e) {
            logger.error("带参数任务执行失败", e);
            XxlJobHelper.handleFail("带参数任务执行失败：" + e.getMessage());
        } finally {
            logger.info(">>>>>>>>>>> 带参数任务执行结束 <<<<<<<<<<<");
        }
    }
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47

核心说明：

  • 任务参数通过XxlJobHelper.getJobParam()获取，控制台配置任务时可动态传入
  • 企业级规范：参数建议使用JSON格式，便于扩展和解析
  • 参数校验：必须校验参数合法性，避免空指针或解析异常

# 5.3 分片广播任务（集群场景）

编写ShardingXxlJob，实现分片任务（企业级集群部署核心场景）：

package cc.hep.job;

import com.xxl.job.core.context.XxlJobHelper;
import com.xxl.job.core.handler.annotation.XxlJob;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import org.springframework.stereotype.Component;

/**
 * 分片广播任务（企业级集群场景：任务分片执行，提高效率）
 * @author hep
 */
@Component
public class ShardingXxlJob {
    private static final Logger logger = LoggerFactory.getLogger(ShardingXxlJob.class);

    /**
     * 分片任务示例
     */
    @XxlJob("shardingXxlJobHandler")
    public void shardingXxlJobHandler() {
        logger.info(">>>>>>>>>>> 分片任务开始执行 <<<<<<<<<<<");

        try {
            // 1. 获取分片信息（企业级集群核心）
            int shardIndex = XxlJobHelper.getShardIndex(); // 当前分片索引（0开始）
            int shardTotal = XxlJobHelper.getShardTotal(); // 总分片数

            logger.info("分片信息：当前分片索引={}，总分片数={}", shardIndex, shardTotal);

            // 2. 分片业务逻辑（模拟：不同分片处理不同数据范围）
            switch (shardIndex) {
                case 0:
                    logger.info("分片0：处理用户ID 0-10000的数据");
                    break;
                case 1:
                    logger.info("分片1：处理用户ID 10001-20000的数据");
                    break;
                case 2:
                    logger.info("分片2：处理用户ID 20001-30000的数据");
                    break;
                default:
                    logger.info("分片{}：处理剩余数据", shardIndex);
            }

            XxlJobHelper.handleSuccess("分片任务执行成功，分片索引：" + shardIndex);
        } catch (Exception e) {
            logger.error("分片任务执行失败", e);
            XxlJobHelper.handleFail("分片任务执行失败：" + e.getMessage());
        } finally {
            logger.info(">>>>>>>>>>> 分片任务执行结束 <<<<<<<<<<<");
        }
    }
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54

核心说明：

  • 分片任务适用于集群部署，将一个大任务拆分为多个小任务，由不同执行器节点执行
  • XxlJobHelper.getShardIndex()：获取当前执行器的分片索引（0~n-1）
  • XxlJobHelper.getShardTotal()：获取总分片数（控制台配置）
  • 企业级场景：分片任务常用于大数据量处理（如订单统计、数据同步），提高执行效率

# 6. XXL-Job Admin控制台配置

# 6.1 添加执行器

  1. 访问http://192.168.31.113:8080/xxl-job-admin/，使用admin/123456登录
  2. 点击左侧菜单执行器管理 -> 添加执行器
  3. 填写执行器信息：
    • 执行器名称：SpringBoot-XXL-Job-Executor（自定义）
    • 执行器AppName：springboot-xxl-job-executor（必须与application.yml中executor.appname一致）
    • 注册方式：自动注册（推荐，执行器启动后自动注册到Admin）
    • 机器地址：留空（自动注册无需填写）
  4. 点击保存

# 6.2 添加任务

以“简单定时任务”为例，添加任务配置：

  1. 点击左侧菜单任务管理 -> 添加任务
  2. 填写任务信息：
    • 执行器：选择上一步添加的SpringBoot-XXL-Job-Executor
    • 任务描述：简单定时任务（自定义）
    • 调度类型：CRON
    • CRON表达式：0/10 * * * * ?（每10秒执行一次，测试用）
    • 任务Handler：simpleXxlJobHandler（必须与@XxlJob注解的value一致）
    • 任务参数：留空（简单任务无参数）
    • 路由策略：第一个（测试用，集群场景可选择分片广播）
    • 执行超时时间：30秒（企业级建议配置，避免任务卡死）
    • 失败重试次数：3次（企业级建议配置，提高任务成功率）
  3. 点击保存

# 6.3 其他任务配置

  • 带参数任务：任务Handler填写paramXxlJobHandler，任务参数填写JSON格式（如{"userId":1001,"date":"2026-01-26"}）
  • 分片任务：任务Handler填写shardingXxlJobHandler，路由策略选择分片广播，总分片数配置为3（与代码中switch匹配）

# 7. 项目启动与测试

# 7.1 启动前检查

  1. 确认XXL-Job Admin已启动
  2. 确认application.yml中executor.port=9999未被占用
  3. 确认日志目录/data/xxl-job/logs/springboot-xxl-job已创建（无权限可修改为本地目录，如D:/xxl-job/logs）

# 7.2 启动项目

  1. 找到SpringBootXxlJobApplication.java启动类：
package cc.hep;

import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;

/**
 * 项目启动类（企业级规范：放在根包下）
 * @author hep
 */
@SpringBootApplication
public class SpringBootXxlJobApplication {

    public static void main(String[] args) {
        SpringApplication.run(SpringBootXxlJobApplication.class, args);
        System.out.println(">>>>>>>>>>> SpringBoot-XXL-Job项目启动成功 <<<<<<<<<<<");
    }

}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
  1. 点击IDEA右上角Run按钮启动项目，控制台输出以下日志表示执行器注册成功：
>>>>>>>>>>> xxl-job config init.
XXL-Job Registry Param: RegistryParam{registryGroup='EXECUTOR', registryKey='springboot-xxl-job-executor', registryValue='192.168.31.xxx:9999'}
XXL-Job Registry Success.
1
2
3

# 7.3 任务测试

  1. 在XXL-Job Admin控制台，找到已添加的任务，点击执行 -> 触发执行
  2. 查看任务执行日志：
    • 控制台日志：IDEA控制台输出任务执行日志
    • Admin日志：点击任务日志按钮，查看XXL-Job Admin记录的执行日志
  3. 验证结果：
    • 简单任务：每10秒执行一次，日志显示“简单定时任务执行成功”
    • 带参数任务：触发时传入参数，日志显示参数解析结果
    • 分片任务：集群部署多个执行器，每个执行器执行对应分片逻辑

02

# 8. 企业级最佳实践

# 8.1 日志规范

  1. 统一日志格式：包含任务ID、分片信息、执行时间、业务关键词
  2. 日志持久化：配置日志输出到文件，结合ELK收集日志（企业级必做）
  3. 敏感信息脱敏：日志中避免输出密码、手机号等敏感信息

# 8.2 任务异常处理

  1. 全局异常捕获：在任务类中捕获所有异常，避免任务中断
  2. 失败重试：合理配置重试次数（建议3次以内），避免重复执行导致数据问题
  3. 告警机制：XXL-Job Admin配置邮件/钉钉告警，任务失败时及时通知开发人员

# 8.3 集群部署

  1. 执行器集群：部署多个执行器节点，相同appname自动注册到Admin
  2. 分片策略：根据业务场景选择分片策略（如平均分配、轮询）
  3. 避免重复执行：任务逻辑中添加幂等性校验（如订单号唯一）

# 8.4 性能优化

  1. 任务拆分：将大任务拆分为多个小任务，避免单任务执行超时
  2. 异步执行：非核心逻辑采用异步处理，提高任务执行效率
  3. 资源隔离：重要任务单独部署执行器，避免资源抢占

# 9. 常见问题与解决方案

# 9.1 执行器注册失败

  • 原因：Admin地址配置错误、端口被占用、网络不通
  • 解决方案：
    1. 检查admin.addresses是否与Admin实际地址一致
    2. 检查executor.port是否被占用（使用netstat -ano | findstr 9999排查）
    3. 测试执行器与Admin的网络连通性（ping 192.168.31.113）

# 9.2 任务执行失败

  • 原因：Handler名称不匹配、参数解析错误、业务逻辑异常
  • 解决方案：
    1. 检查@XxlJob注解的value与控制台任务Handler是否一致
    2. 检查任务参数格式是否正确（如JSON格式是否合法）
    3. 查看IDEA控制台日志，定位业务逻辑异常

# 9.3 任务执行超时

  • 原因：业务逻辑复杂、数据量过大、资源不足
  • 解决方案：
    1. 优化业务逻辑，拆分任务
    2. 增加执行超时时间配置
    3. 升级服务器资源或采用分片执行

# 总结

  1. SpringBoot集成XXL-Job的核心是引入xxl-job-core依赖、配置执行器参数、注入XxlJobSpringExecutor Bean，任务开发基于@XxlJob注解实现。
  2. 企业级开发需关注日志规范、异常处理、集群部署和性能优化，确保任务稳定执行。
  3. 控制台配置的执行器AppName、任务Handler必须与代码中一致，否则会导致注册失败或任务执行失败。

通过本教程，你已掌握SpringBoot 3.5.10集成XXL-Job的全流程，可直接将这套方案落地到企业级项目中，满足定时任务、分布式任务调度的核心需求。

最近更新: 2026/2/3

← SpringBoot集成EasyExcel企业级实战教程 →

 |  Copyright © -Present Kelsen All Rights Reserved. | Author KelsenJing
SpringBoot集成XXL-Job企业级实战教程