定时任务调度平台XXL-JOB

---

一、什么是 XXL-JOB？

想象你有一个需要每天凌晨3点自动执行的任务（比如数据统计），传统做法是写个定时任务。但如果有以下需求：

• 多台服务器同时运行任务
• 任务失败自动重试
• 实时查看任务执行日志
• 动态调整执行时间

XXL-JOB 就是为解决这些问题而生的任务调度平台。它分为两部分：

1. 调度中心（管理后台）：负责定时触发任务，像指挥中心
2. 执行器（你的程序）：实际干活的代码，像工人

---

二、手把手环境搭建（Windows版）

1. 安装基础软件

1. JDK 1.8
   • 验证安装：命令行输入 java -version
2. MySQL 5.7+
   • 创建数据库：CREATE DATABASE xxl_job;
3. Maven 3.2+
   • 验证安装：命令行输入 mvn -v

2. 部署调度中心（可视化后台）

1. 下载源码：

   git clone https://gitee.com/xuxueli0323/xxl-job.git
   

2. 导入数据库：

   • 找到文件 /xxl-job/doc/db/tables_xxl_job.sql
   • 用 MySQL 客户端执行这个SQL文件

3. 修改数据库配置：
   打开文件 /xxl-job/xxl-job-admin/src/main/resources/application.properties

   # 修改这三行配置
   spring.datasource.url=jdbc:mysql://localhost:3306/xxl_job?useUnicode=true
   spring.datasource.username=你的MySQL账号
   spring.datasource.password=你的MySQL密码
   

4. 启动调度中心：

   • 用 IDEA/Eclipse 打开项目
   • 运行 XxlJobAdminApplication 类
   • 访问 http://localhost:8080/xxl-job-admin
   • 登录账号：admin/123456

---

三、创建你的第一个定时任务

1. 新建 Spring Boot 项目

使用 Spring Initializr 创建项目，选择：

• Maven
• Java 8
• Spring Boot 2.x
• 依赖：Web

2. 添加 XXL-JOB 依赖

在 pom.xml 中添加：

<dependency><groupId>com.xuxueli</groupId><artifactId>xxl-job-core</artifactId><version>2.4.0</version>
</dependency>

3. 配置执行器

在 application.yml 中配置：

xxl:job:admin:addresses: http://localhost:8080/xxl-job-admin  # 调度中心地址executor:appname: my-first-executor  # 执行器名称（重要！）port: 9999  # 执行器端口accessToken:  # 留空（生产环境需要）

accessToken：开发环境可以设置为空，生产环境需要设置

4. Java 配置类

创建 XxlJobConfig.java：

@Configuration
public class XxlJobConfig {@Value("${xxl.job.admin.addresses}")private String adminAddresses;@Beanpublic XxlJobSpringExecutor xxlJobExecutor() {XxlJobSpringExecutor executor = new XxlJobSpringExecutor();executor.setAdminAddresses(adminAddresses);executor.setAppname("my-first-executor");executor.setPort(9999);return executor;}
}

5. 编写定时任务

创建 DemoJob.java：

@Component
public class DemoJob {// 使用 @XxlJob 注解定义任务@XxlJob("myDemoJob")public void myJobHandler() throws Exception {// 获取任务参数（在调度中心配置）String param = XxlJobHelper.getJobParam();XxlJobHelper.log("任务开始执行，参数：" + param);// 模拟业务逻辑for (int i = 1; i <= 5; i++) {XxlJobHelper.log("正在处理第 " + i + " 步");Thread.sleep(1000); // 模拟耗时操作}// 任务完成XxlJobHelper.handleSuccess("任务执行成功！");}
}

---

四、在调度中心配置任务

1. 添加执行器：

   • 登录调度中心
   • 进入「执行器管理」
   • 点击「新增」
   • 填写：

     AppName: my-first-executor（必须与配置文件中的appname一致）
     名称: 我的第一个执行器
     注册方式: 自动注册
     

2. 创建任务：

   • 进入「任务管理」
   • 点击「新建」
   • 填写：

     任务描述：我的演示任务
     JobHandler：myDemoJob（必须与@XxlJob注解的值一致）
     Cron：0/10 * * * * ?  （每10秒执行一次）
     运行模式：BEAN
     路由策略：第一个
     

3. 启动任务：

   • 在任务列表中找到新建的任务
   • 点击「操作」列的「启动」按钮

---

五、查看运行结果

1. 控制台日志：

   • 在你的 Spring Boot 应用控制台查看输出

2. 调度中心日志：

   • 进入「调度日志」
   • 点击「执行日志」查看详细记录

3. 执行效果：

   2023-10-01 15:30:00 [XXL-JOB] 任务开始执行，参数：testParam
   2023-10-01 15:30:00 [XXL-JOB] 正在处理第 1 步
   2023-10-01 15:30:01 [XXL-JOB] 正在处理第 2 步
   ...
   2023-10-01 15:30:04 [XXL-JOB] 任务执行成功！
   

---

六、核心概念详解

1. 调度流程

2. 路由策略

策略名称	说明
第一个	选择第一个在线执行器
轮询	依次选择不同执行器
随机	随机选择执行器
分片广播	所有执行器同时执行

3. 任务参数传递

// 调度中心配置参数
@XxlJob("paramDemo")
public void paramJob() {String param = XxlJobHelper.getJobParam(); // 获取参数XxlJobHelper.log("收到参数：" + param);
}

---

七、常见问题解决

1. 执行器未注册

• 检查点：
  • 执行器的 appname 是否与调度中心配置一致
  • 网络是否连通（telnet 调度中心地址 8080）
  • 执行器是否成功启动

2. 任务未触发

• 检查点：
  • Cron 表达式是否正确（可用在线工具验证）
  • 任务是否处于「运行中」状态
  • 调度中心的服务器时间是否准确

3. 日志不显示

• 检查点：
  • 执行器配置的 logpath 是否有写入权限
  • 查看本地日志文件 /data/applogs/xxl-job/jobhandler

---

八、真实场景案例

1. 数据库数据同步

@XxlJob("syncUserData")
public void syncUserData() {// 1. 从源数据库读取数据List<User> users = sourceUserMapper.selectList();// 2. 处理数据List<User> processedUsers = processData(users);// 3. 写入目标数据库targetUserMapper.batchInsert(processedUsers);XxlJobHelper.handleSuccess("同步完成，共处理 " + processedUsers.size() + " 条数据");
}

2. 文件清理任务

@XxlJob("cleanTempFiles")
public void cleanFiles() {File tempDir = new File("/tmp/uploads");File[] files = tempDir.listFiles();int count = 0;if (files != null) {for (File file : files) {if (file.lastModified() < System.currentTimeMillis() - 24*60*60*1000) {file.delete();count++;}}}XxlJobHelper.handleSuccess("已清理 " + count + " 个过期文件");
}

---

遇到问题时，多查看：

• 执行器本地日志
• 调度中心的「调度日志」
• XXL-JOB 官方文档（https://www.xuxueli.com/xxl-job/）