tacit/common/xxljob

XXL-Job Starter

一个基于XXL-Job的Spring Boot Starter，提供自动配置、服务发现和容器部署支持。

功能特性

• ✅ Spring Boot自动配置，简化XXL-Job集成
• ✅ 支持Nacos服务发现，自动获取XXL-Job Admin地址
• ✅ 容器部署支持，自动处理IP和端口映射
• ✅ 执行器地址自动补全协议前缀(http://)
• ✅ 环境变量动态配置，灵活适配不同部署环境
• ✅ 完善的日志记录和错误处理

快速开始

1. 添加依赖

在你的Spring Boot项目中添加以下依赖：

<dependency>
    <groupId>com.tacit</groupId>
    <artifactId>xxljob</artifactId>
    <version>1.0.0-SNAPSHOT</version>
</dependency>

2. 启用XXL-Job

在Spring Boot主类上添加@EnableXxlJob注解：

@SpringBootApplication
@EnableXxlJob
public class Application {
    public static void main(String[] args) {
        SpringApplication.run(Application.class, args);
    }
}

3. 配置XXL-Job

在application.yml或bootstrap.yml中添加XXL-Job配置：

xxl:
  job:
    admin:
      # XXL-Job Admin地址，多个地址用逗号分隔
      addresses: http://localhost:8080/xxl-job-admin
      # 可选，调度中心通讯TOKEN
      access-token: default_token
    executor:
      # 执行器AppName，默认使用spring.application.name
      appname: my-xxl-job-executor
      # 执行器IP，默认为空表示自动获取
      ip: 
      # 执行器端口，默认9099
      port: 9999
      # 执行器通讯TOKEN
      access-token: default_token
      # 执行器日志路径
      log-path: logs/applogs/xxl-job/jobhandler
      # 执行器日志保存天数
      log-retention-days: 30

4. 创建JobHandler

@Component
public class MyJobHandler {
    
    @XxlJob("myJobHandler")
    public ReturnT<String> execute(String param) throws Exception {
        XxlJobLogger.log("XXL-Job, Hello World.");
        System.out.println("执行任务: " + param);
        return ReturnT.SUCCESS;
    }
}

配置说明

核心配置项

配置项	说明	默认值
xxl.job.admin.addresses	XXL-Job Admin地址	-
xxl.job.admin.access-token	调度中心通讯TOKEN	-
xxl.job.executor.appname	执行器AppName	spring.application.name
xxl.job.executor.ip	执行器IP	自动获取
xxl.job.executor.port	执行器端口	9099
xxl.job.executor.access-token	执行器通讯TOKEN	-
xxl.job.executor.log-path	执行器日志路径	logs/applogs/xxl-job/jobhandler
xxl.job.executor.log-retention-days	日志保存天数	30

容器部署环境变量

环境变量	说明
XXL_JOB_EXECUTOR_IP	容器真实IP（宿主机IP）
XXL_JOB_EXECUTOR_PORT	容器映射后的真实端口
XXL_JOB_ADMIN_ADDRESSES	XXL-Job Admin地址

高级特性

自动服务发现

如果未配置xxl.job.admin.addresses，Starter会自动从Nacos注册中心发现XXL-Job Admin服务（服务名包含"xxl-job-admin"）。

容器部署支持

在Docker或Kubernetes环境中，执行器会自动处理IP和端口映射：

apiVersion: apps/v1
kind: Deployment
metadata:
  name: my-executor
spec:
  replicas: 1
  template:
    spec:
      containers:
      - name: my-executor
        image: my-executor:latest
        ports:
        - containerPort: 9999
        env:
        - name: XXL_JOB_EXECUTOR_IP
          valueFrom:
            fieldRef:
              fieldPath: status.hostIP
        - name: XXL_JOB_EXECUTOR_PORT
          value: "30099"  # Kubernetes节点端口
        - name: spring.application.name
          value: my-executor

自定义执行器地址

xxl:
  job:
    executor:
      # 完整的执行器地址，会自动补全协议前缀
      address: 192.168.3.67:9999
      ip: 192.168.3.67
      port: 9999

常见问题

1. 执行器注册失败

• 检查xxl.job.admin.addresses配置是否正确
• 检查网络连接是否正常
• 检查防火墙设置

2. 任务执行失败，提示"no protocol"

这是因为执行器地址缺少协议前缀导致的，请确保配置的地址包含http://前缀，或使用Starter的自动补全功能。

3. 容器环境下执行器地址不正确

请配置XXL_JOB_EXECUTOR_IP和XXL_JOB_EXECUTOR_PORT环境变量，指定宿主机的IP和映射后的端口。

开发和贡献

构建项目

mvn clean install -DskipTests

目录结构

src/
├── main/
│   ├── java/
│   │   └── com/tacit/starter/xxljob/
│   │       ├── annotation/          # 注解类
│   │       ├── properties/          # 配置属性类
│   │       └── XxlJobAutoConfiguration.java  # 自动配置类
│   └── resources/
│       └── META-INF/
│           └── spring.factories     # Spring Boot自动配置入口

版本依赖

• Spring Boot 2.x
• XXL-Job Core 2.5.0
• Spring Cloud Alibaba Nacos Discovery

许可证

MIT License