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

一、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配置内容请搜索代码网以前的文章或继续浏览下面的相关文章希望大家以后多多支持代码网！

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

2025年12月11日 • Java •我要评论