Spring Boot集成XXL-Job

一、项目简介

XXL‑Job 是一款开源的分布式任务调度框架，提供可视化的任务管理后台、灵活的任务触发策略、失败重试、日志查看等功能。将 XXL‑Job 与 Spring Boot 集成，可以快速在微服务或独立应用中调度定时任务，下面将详细介绍如何一步步完成接入。

二、环境准备

  • JDK 1.8+
  • Maven 3.5+
  • Spring Boot 2.3+
  • 已搭建好的 XXL‑Job Admin（管理后台），可参考XXL部署篇

三、添加依赖

在项目根目录下的 pom.xml 添加 xxl-job-core 依赖。以下为完整的 pom.xml 示例：

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
<?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
                             http://maven.apache.org/xsd/maven-4.0.0.xsd">
    <modelVersion>4.0.0</modelVersion>
    <groupId>com.example</groupId>
    <artifactId>springboot-xxljob-demo</artifactId>
    <version>0.0.1-SNAPSHOT</version>
    <packaging>jar</packaging>

    <parent>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-parent</artifactId>
        <version>2.7.5</version>
        <relativePath/> <!-- lookup parent from repository -->
    </parent>

    <dependencies>
        <!-- Spring Boot Starter -->
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter</artifactId>
        </dependency>

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

        <!-- 可选：日志打印（默认已包含） -->
        <dependency>
            <groupId>ch.qos.logback</groupId>
            <artifactId>logback-classic</artifactId>
        </dependency>
    </dependencies>

    <build>
        <plugins>
            <!-- Spring Boot Maven Plugin -->
            <plugin>
                <groupId>org.springframework.boot</groupId>
                <artifactId>spring-boot-maven-plugin</artifactId>
            </plugin>
        </plugins>
    </build>
</project>

四、全局配置

在 src/main/resources/application.yml 中，添加 XXL‑Job 执行器（Executor）的配置。以下为完整的 application.yml 示例：

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
spring:
  application:
    name: springboot-xxljob-demo

# XXLJob配置
executor:
  name: job-executor

xxl:
  job:
    # 管理端地址
    admin:
      addresses: "http://localhost:9090/xxl-job-admin"
    # 访问令牌
    accessToken: "default_token"
    executor:
      # 应用名
      appname: "${executor.name}"
      # 执行器直连地址（留空则自动注册）
      address: ""
      # 指定 IP（留空则自动获取）
      ip: ""
      # 端口
      port: 9999
      # 日志存储路径
      logpath: "/code/xxl/${executor.name}"
      # 日志保留天数
      logretentiondays: 3

新建配置类：

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
/**
 * @Author：xukun
 * @Date：2025/5/10 下午1:34
 */
@Slf4j
@Configuration
public class XxlJobConfig {
    protected static final Logger logger = LoggerFactory.getLogger(XxlJobConfig.class);

    @Value("${xxl.job.admin.addresses}")
    private String adminAddresses;

    @Value("${xxl.job.accessToken}")
    private String accessToken;

    @Value("${xxl.job.executor.appname}")
    private String appname;

    @Value("${xxl.job.executor.address}")
    private String address;

    @Value("${xxl.job.executor.ip}")
    private String ip;

    @Value("${xxl.job.executor.port}")
    private int port;

    @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.setAddress(address);
        xxlJobSpringExecutor.setIp(ip);
        xxlJobSpringExecutor.setPort(port);
        xxlJobSpringExecutor.setAccessToken(accessToken);
        xxlJobSpringExecutor.setLogPath(logPath);
        xxlJobSpringExecutor.setLogRetentionDays(logRetentionDays);
        return xxlJobSpringExecutor;
    }
}

五、编写任务处理器

创建一个 JobHandler，实现具体的业务逻辑，并在管理后台调度。示例：

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
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
/**
 * @Author：xukun
 * @Date：2025/5/10 下午1:39
 */
@Slf4j
@Component
public class ArchiveTaskXxlJobHandler {

    @Autowired
    private RoleService roleService;

    @Autowired
    private WssController wssController;

    @Autowired
    private DailyTaskService dailyTaskService;


    /**
     * JobHandler 名称：dailyTasksJobHandler
     * 由 XXL-JOB 调度器反射调用
     *
     * @param param 通过调度中心配置的任意入参
     */
    @XxlJob("dailyTasksJobHandler")
    public void dailyTasksJobHandler(String param) throws Exception {
        List<Long> roleIds = roleService.getDailyOpenRoleIds();
        for (Long roleId : roleIds) {
            try {
                dailyTaskService.executeDailyTasks(roleId);
                XxlJobHelper.log("角色 {} 每日任务执行成功", roleId);
            } catch (Exception e) {
                XxlJobHelper.log("角色 {} 每日任务执行失败：{}", roleId, e.getMessage());
            }
        }
    }

    /**
     * JobHandler 名称：signTasks
     * 由 XXL-JOB 调度器反射调用
     *
     * @param param 通过调度中心配置的任意入参
     */
    @XxlJob("signTasks")
    public void signTasks(String param) throws Exception {
        List<Long> roleIds = roleService.getSignOpenRoleIds();
        for (Long roleId : roleIds) {
            try {
                dailyTaskService.signTasks(roleId);
                XxlJobHelper.log("角色 {} 排位赛报名执行成功", roleId);
            } catch (Exception e) {
                XxlJobHelper.log("角色 {} 排位赛报名执行失败：{}", roleId, e.getMessage());
            }
        }
    }

    /**
     * JobHandler 名称：dailyTasksJobHandler
     * 由 XXL-JOB 调度器反射调用
     *
     * @param param 通过调度中心配置的任意入参（这里不使用，可忽略）
     */
    @XxlJob("bottleTasks")
    public void bottleTasks(String param) throws Exception {
        List<Long> roleIds = roleService.getBottleOpenRoleIds();
        for (Long roleId : roleIds) {
            try {
                dailyTaskService.bottleTasks(roleId);
                XxlJobHelper.log("角色 {} 发条重启执行成功", roleId);
            } catch (Exception e) {
                XxlJobHelper.log("角色 {} 发条重启执行失败：{}", roleId, e.getMessage());
            }
        }
    }

    /**
     * JobHandler 名称：hangupTasks
     * 由 XXL-JOB 调度器反射调用
     *
     * @param param 通过调度中心配置的任意入参
     */
    @XxlJob("hangupTasks")
    public void hangupTasks(String param) throws Exception {
        List<Long> roleIds = roleService.getHangOpenRoleIds();
        for (Long roleId : roleIds) {
            try {
                dailyTaskService.hangupTasks(roleId);
                XxlJobHelper.log("角色 {} 挂机奖励领取成功", roleId);
            } catch (Exception e) {
                XxlJobHelper.log("角色 {} 挂机奖励领取执行失败：{}", roleId, e.getMessage());
            }
        }
    }
}

六、运行与调度

  1. 启动 XXL‑Job Admin 服务（默认在 http://localhost:9090/xxl-job-admin）。

  2. 启动本地 Spring Boot 应用，控制台会看到注册信息。

  3. 访问管理后台，进入「执行器管理」可看到 job-executor。

  4. 在「任务管理」中新建任务：

    • 执行器：选择本项目
    • 任务描述：打印时间
    • 执行 JobHandler：填 代码中绑定的对应Handler
    • 调度类型：Cron
    • 调度配置：例如 */10 * * * * ?（每 10 秒执行一次）

    image-20250717154021542

  5. 点击「立即执行」或「开启」后，可在日志页面查看执行效果。

image-20250717154150833