tacit/common/common-xxl-job/README.md

# XXL-Job Starter

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

## 功能特性

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

## 快速开始

### 1. 添加依赖

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

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

### 2. 启用XXL-Job

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

```java
@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配置：

```yaml
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

```java
@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和端口映射：

```yaml
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
```

### 自定义执行器地址

```yaml
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和映射后的端口。

## 开发和贡献

### 构建项目

```bash
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