xxl-job在 Spring Boot 项目中的完整配置指南

一、Maven依赖配置

xml 复制代码

<!-- 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 配置

yaml 复制代码

# 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格式：

yaml 复制代码

# 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. 基础配置类

java 复制代码

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. 多环境配置支持

java 复制代码

@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模式（推荐）

java 复制代码

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模式配置

java 复制代码

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

五、高级配置

1. 自定义注册策略

java 复制代码

@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. 任务执行监控

java 复制代码

@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（开发环境）

yaml 复制代码

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（测试环境）

yaml 复制代码

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（生产环境）

yaml 复制代码

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. 网络隔离配置

yaml 复制代码

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容器配置

yaml 复制代码

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

3. 安全配置

java 复制代码

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

八、项目结构

dart 复制代码

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连接池参数
监控告警：集成监控系统，实时监控任务执行状态
高可用：部署多个执行器实例，实现负载均衡