xxl-job在 Spring Boot 项目中的完整配置指南(最新整理)

更新时间：2025年12月11日 10:45:53 作者：JavaBoy_XJ

本文详细介绍了Spring Boot任务调度配置,包括依赖配置、多环境支持、任务处理器、高级配置、常见问题及解决方法,以及项目结构和注意事项,感兴趣的朋友跟随小编一起看看吧

一、Maven依赖配置

<!-- XXL-Job 核心依赖 -->
<dependency>
    <groupId>com.xuxueli</groupId>
    <artifactId>xxl-job-core</artifactId>
    <version>2.4.0</version>
</dependency>
<!-- Spring Boot Starter（推荐） -->
<dependency>
    <groupId>com.xuxueli</groupId>
    <artifactId>xxl-job-core</artifactId>
    <version>2.4.0</version>
</dependency>

二、配置文件详解

1. application.yml/application.properties 配置

# XXL-Job 执行器配置
xxl:
  job:
    # 调度中心部署地址 [选填]：调度中心地址，如：http://127.0.0.1:8080/xxl-job-admin
    admin:
      addresses: http://127.0.0.1:8080/xxl-job-admin
    # 执行器通讯TOKEN [选填]：非空时启用，与调度中心配置保持一致
    accessToken: default_token
    # 执行器配置
    executor:
      # 执行器AppName [选填]：执行器心跳注册分组依据，为空则关闭自动注册
      appname: xxl-job-executor-sample
      # 执行器IP [选填]：默认为空表示自动获取IP
      # ip: 192.168.1.100
      # 执行器端口号 [选填]：小于等于0则自动获取，默认端口为9999
      port: 9999
      # 执行器运行日志文件存储路径 [选填]：需要配置权限
      logpath: /data/applogs/xxl-job/jobhandler
      # 执行器日志文件保存天数 [选填]：过期日志自动清理，限制值大于等于3
      logretentiondays: 30
      # 执行器注册方式 [选填]：默认自动注册，支持手动录入
      # address: http://127.0.0.1:9999/

Properties格式：

# XXL-Job 配置
xxl.job.admin.addresses=http://127.0.0.1:8080/xxl-job-admin
xxl.job.accessToken=default_token
xxl.job.executor.appname=xxl-job-executor-sample
xxl.job.executor.port=9999
xxl.job.executor.logpath=/data/applogs/xxl-job/jobhandler
xxl.job.executor.logretentiondays=30

三、Spring Boot配置类

1. 基础配置类

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.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;
    }
}

2. 多环境配置支持

@Configuration
@ConfigurationProperties(prefix = "xxl.job")
@Data
public class XxlJobProperties {
    /**
     * 是否启用XXL-Job
     */
    private boolean enabled = true;
    /**
     * 调度中心配置
     */
    private Admin admin = new Admin();
    /**
     * 执行器配置
     */
    private Executor executor = new Executor();
    @Data
    public static class Admin {
        private String addresses;
    }
    @Data
    public static class Executor {
        private String appname;
        private String ip;
        private Integer port;
        private String logPath;
        private Integer logRetentionDays;
        private String address;
    }
    @Bean
    @ConditionalOnProperty(prefix = "xxl.job", name = "enabled", havingValue = "true")
    public XxlJobSpringExecutor xxlJobExecutor(XxlJobProperties xxlJobProperties) {
        XxlJobSpringExecutor xxlJobSpringExecutor = new XxlJobSpringExecutor();
        // 设置配置项
        xxlJobSpringExecutor.setAdminAddresses(xxlJobProperties.getAdmin().getAddresses());
        xxlJobSpringExecutor.setAppname(xxlJobProperties.getExecutor().getAppname());
        xxlJobSpringExecutor.setIp(xxlJobProperties.getExecutor().getIp());
        xxlJobSpringExecutor.setPort(xxlJobProperties.getExecutor().getPort());
        xxlJobSpringExecutor.setLogPath(xxlJobProperties.getExecutor().getLogPath());
        xxlJobSpringExecutor.setLogRetentionDays(xxlJobProperties.getExecutor().getLogRetentionDays());
        xxlJobSpringExecutor.setAddress(xxlJobProperties.getExecutor().getAddress());
        return xxlJobSpringExecutor;
    }
}

四、任务处理器配置

1. Bean模式（推荐）

import com.xxl.job.core.handler.annotation.XxlJob;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import org.springframework.stereotype.Component;
@Component
public class SampleXxlJob {
    private static final Logger logger = LoggerFactory.getLogger(SampleXxlJob.class);
    /**
     * 简单任务示例
     */
    @XxlJob("demoJobHandler")
    public void demoJobHandler() throws Exception {
        logger.info("XXL-JOB, Hello World.");
        // 模拟任务执行
        for (int i = 0; i < 5; i++) {
            logger.info("beat at:" + i);
            Thread.sleep(1000);
        }
        // 默认执行结果
        // return ReturnT.SUCCESS;
    }
    /**
     * 带参数的任务
     */
    @XxlJob("paramJobHandler")
    public ReturnT<String> paramJobHandler(String param) throws Exception {
        logger.info("接收参数: {}", param);
        // 业务逻辑处理
        if (param == null || param.trim().length() == 0) {
            return new ReturnT<>(ReturnT.FAIL_CODE, "参数不能为空");
        }
        return ReturnT.SUCCESS;
    }
    /**
     * 分片广播任务
     */
    @XxlJob("shardingJobHandler")
    public void shardingJobHandler() throws Exception {
        // 分片参数
        ShardingUtil.ShardingVO shardingVO = ShardingUtil.getShardingVo();
        logger.info("分片参数：当前分片序号 = {}, 总分片数 = {}", 
            shardingVO.getIndex(), shardingVO.getTotal());
        // 分片处理逻辑
        List<String> dataList = fetchData();
        for (int i = 0; i < dataList.size(); i++) {
            // 取模分片
            if (i % shardingVO.getTotal() == shardingVO.getIndex()) {
                processItem(dataList.get(i));
            }
        }
    }
    /**
     * 初始化方法（可选）
     */
    @XxlJob(value = "demoJobHandler", init = "init", destroy = "destroy")
    public void demoJobHandler2() throws Exception {
        logger.info("任务执行...");
    }
    public void init() {
        logger.info("任务初始化...");
    }
    public void destroy() {
        logger.info("任务销毁...");
    }
}

2. GLUE模式配置

/**
 * GLUE(Java)模式，任务在调度中心编写代码
 * 执行器只需要配置以下空方法
 */
@Component
public class GlueJob {
    @XxlJob("glueJavaJobHandler")
    public ReturnT<String> glueJavaJobHandler(String param) throws Exception {
        // GLUE代码在调度中心管理平台编写和维护
        // 执行器只需要提供空方法即可
        return ReturnT.SUCCESS;
    }
}

五、高级配置

1. 自定义注册策略

@Configuration
public class CustomXxlJobConfig extends XxlJobSpringExecutor {
    @Override
    public void start() throws Exception {
        // 自定义初始化逻辑
        logger.info(">>>>>>>>>>> xxl-job custom executor start.");
        super.start();
    }
    @Override
    public void destroy() {
        // 自定义销毁逻辑
        logger.info(">>>>>>>>>>> xxl-job custom executor destroy.");
        super.destroy();
    }
    @Override
    public ReturnT<String> beat() {
        // 自定义心跳检测
        ReturnT<String> beatResult = super.beat();
        logger.info("Custom heartbeat result: {}", beatResult);
        return beatResult;
    }
}

2. 任务执行监控

@Aspect
@Component
@Slf4j
public class JobExecutionMonitorAspect {
    @Around("@annotation(xxlJob)")
    public Object monitorJobExecution(ProceedingJoinPoint joinPoint, XxlJob xxlJob) throws Throwable {
        String jobName = xxlJob.value();
        long startTime = System.currentTimeMillis();
        log.info("Job [{}] 开始执行", jobName);
        try {
            Object result = joinPoint.proceed();
            long executionTime = System.currentTimeMillis() - startTime;
            log.info("Job [{}] 执行成功，耗时：{}ms", jobName, executionTime);
            // 可以记录到数据库或发送监控报警
            recordJobExecution(jobName, true, executionTime);
            return result;
        } catch (Exception e) {
            long executionTime = System.currentTimeMillis() - startTime;
            log.error("Job [{}] 执行失败，耗时：{}ms，错误：{}", 
                jobName, executionTime, e.getMessage(), e);
            recordJobExecution(jobName, false, executionTime);
            throw e;
        }
    }
    private void recordJobExecution(String jobName, boolean success, long executionTime) {
        // 记录执行记录到数据库
        // JobExecutionRecord record = new JobExecutionRecord();
        // record.setJobName(jobName);
        // record.setSuccess(success);
        // record.setExecutionTime(executionTime);
        // record.setExecuteTime(new Date());
        // jobExecutionService.save(record);
    }
}

六、多环境配置文件示例

1. application-dev.yml（开发环境）

xxl:
  job:
    admin:
      addresses: http://localhost:8080/xxl-job-admin
    executor:
      appname: xxl-job-executor-dev
      port: 9999
      logpath: ./logs/xxl-job/jobhandler
      logretentiondays: 7

2. application-test.yml（测试环境）

xxl:
  job:
    admin:
      addresses: http://test-xxl-job-admin:8080/xxl-job-admin
    accessToken: test_token_123
    executor:
      appname: xxl-job-executor-test
      port: 9999
      logpath: /data/logs/xxl-job/jobhandler
      logretentiondays: 30

3. application-prod.yml（生产环境）

xxl:
  job:
    admin:
      addresses: http://prod-xxl-job-admin-01:8080/xxl-job-admin,http://prod-xxl-job-admin-02:8080/xxl-job-admin
    accessToken: prod_secure_token_${RANDOM}
    executor:
      appname: xxl-job-executor-prod
      ip: ${EXECUTOR_IP:}
      port: ${EXECUTOR_PORT:9999}
      logpath: /data/applogs/xxl-job/jobhandler
      logretentiondays: 90

七、常见问题配置

1. 网络隔离配置

xxl:
  job:
    admin:
      addresses: ${XXL_JOB_ADMIN_URL:http://localhost:8080/xxl-job-admin}
    executor:
      appname: ${HOSTNAME:${spring.application.name:xxl-job-executor}}
      # 使用内网IP注册
      ip: ${INTRANET_IP:}
      # 使用外网地址访问（如有NAT）
      address: ${EXTERNAL_URL:}

2. Docker容器配置

xxl:
  job:
    executor:
      appname: ${HOSTNAME:xxl-job-executor}
      # 自动获取IP
      ip: 
      # 使用服务发现地址
      address: ${SERVICE_URL:}
      port: 9999

3. 安全配置

@Configuration
public class SecurityXxlJobConfig {
    @Bean
    public XxlJobSpringExecutor xxlJobExecutor() {
        XxlJobSpringExecutor executor = new XxlJobSpringExecutor();
        // 从安全配置中心获取token
        String accessToken = getAccessTokenFromVault();
        executor.setAccessToken(accessToken);
        // 其他配置...
        return executor;
    }
}

八、项目结构

src/main/java/
├── com/example/job
│   ├── config
│   │   ├── XxlJobConfig.java          # 主配置类
│   │   └── XxlJobProperties.java      # 配置属性类
│   ├── handler
│   │   ├── DemoJobHandler.java        # 示例任务
│   │   ├── OrderJobHandler.java       # 订单相关任务
│   │   └── ReportJobHandler.java      # 报表任务
│   ├── aspect
│   │   └── JobMonitorAspect.java      # 任务监控切面
│   └── JobApplication.java            # 启动类

九、注意事项

端口冲突：确保9999端口未被占用，或修改为其他端口
网络连通：确保执行器能访问调度中心地址
权限问题：日志目录需要有写入权限
注册失败：检查appname是否在调度中心存在
版本兼容：调度中心和执行器版本要保持一致
日志清理：定期清理过期日志，避免磁盘占满

十、性能优化建议

线程池配置：根据任务量调整线程池大小
日志优化：使用异步日志，避免IO阻塞
连接池：配置合适的HTTP连接池参数
监控告警：集成监控系统，实时监控任务执行状态
高可用：部署多个执行器实例，实现负载均衡

到此这篇关于xxl-job在 Spring Boot 项目中的完整配置指南(最新整理)的文章就介绍到这了,更多相关springboot xxl-job配置内容请搜索脚本之家以前的文章或继续浏览下面的相关文章希望大家以后多多支持脚本之家！

您可能感兴趣的文章:

SpringBoot2+Netty+WebSocket(netty实现websocket支持URL参数)问题记录
Netty 是一个利用 Java 的高级网络的能力,隐藏其背后的复杂性而提供一个易于使用的 API 的客户端/服务器框架,这篇文章主要介绍了SpringBoot2+Netty+WebSocket(netty实现websocket,支持URL参数),需要的朋友可以参考下
2023-12-12
Java中final关键字的用法总结
在Java中,final可以别用来修饰类、修饰方法、修饰变量和修饰参数等,这里就来简单作一个Java中final关键字的用法总结:
2016-06-06
你知道Tomcat安装之前为什么要安装JDK
这篇文章主要介绍了你知道Tomcat安装之前为什么要安装JDK吗？具有很好的参考价值,希望对大家有所帮助,如有错误或未考虑完全的地方,望不吝赐教
2024-03-03
IDEA中properties与yml文件的转变方式
文章介绍了如何在IntelliJ IDEA 2021.1.1中安装和使用ConvertYAMLandPropertiesFile插件进行YAML和Properties文件之间的转换,安装步骤包括导航到设置、安装插件、找到并安装插件等,插件支持从Properties文件转换为YAML文件,但转换过程中会丢失注释
2024-12-12
详解Java使用双异步后如何保证数据一致性
这篇文章主要为大家详细介绍了Java使用双异步后如何保证数据一致性,文中的示例代码讲解详细,具有一定的借鉴价值,有需要的小伙伴可以了解下
2024-01-01
Spring整合mybatis实现过程详解
这篇文章主要介绍了Spring整合mybatis实现过程详解,文中通过示例代码介绍的非常详细，对大家的学习或者工作具有一定的参考学习价值,需要的朋友可以参考下
2020-07-07
使用MyBatis查询千万级数据量操作实现
这篇文章主要为大家介绍了如何使用MyBatis 查询千万数据量的操作过程详解，有需要的朋友可以借鉴参考下，希望能够有所帮助，祝大家多多进步，早日升职加薪
2023-05-05
Spring Cloud 请求重试机制核心代码分析
这篇文章主要介绍了Spring Cloud 请求重试机制核心代码分析，小编觉得挺不错的，现在分享给大家，也给大家做个参考。一起跟随小编过来看看吧
2018-06-06
使用Java开发实现OAuth安全认证的应用
这篇文章主要介绍了使用Java开发实现OAuth安全认证的应用的方法,OAuth安全认证经常出现于社交网络API应用的相关开发中,需要的朋友可以参考下
2015-11-11
Java操作Elasticsearch rest-high-level-client 的基本使用
这篇文章主要介绍了Java操作Elasticsearch rest-high-level-client 的基本使用,本篇主要讲解一下 rest-high-level-client 去操作 Elasticsearch的方法，结合实例代码给大家详细讲解，需要的朋友可以参考下
2022-10-10