1. 为什么你需要一个分布式任务调度系统?
如果你正在开发一个SpringBoot应用,是不是经常遇到这样的场景:每天凌晨需要跑个报表、每隔5分钟要同步一次用户数据、每周一早上要给所有用户发个提醒邮件……这些定时任务,一开始你可能直接用Spring自带的@Scheduled注解就搞定了,简单省事。
但随着业务发展,问题就来了。你的应用从单机部署变成了集群,这时候定时任务会在每个节点上都跑一遍,数据重复处理,甚至可能引发脏数据。任务执行失败了怎么办?你想手动触发一次怎么办?任务执行到一半,服务器重启了,任务状态怎么恢复?更头疼的是,你想看看任务执行的详细日志,却发现它们散落在各个服务器上,找起来像大海捞针。
我经历过一个真实的项目,早期就是用@Scheduled,后来用户量上来,上了三台服务器做负载均衡。结果“每日数据清理”这个任务,在三台机器上同时启动,把同一批数据删了三次,直接导致部分数据丢失。从那次以后,我就下定决心,必须引入一个中心化、可视化、高可靠的任务调度系统。
这就是XXL-Job登场的时候了。它本质上是一个“任务调度中心”,你可以把它想象成一个“项目经理”。所有的定时任务(比如生成报表、发送邮件)都注册到这个中心。由这个“项目经理”统一决定什么时候、在哪个“工人”(也就是你的业务应用,称为“执行器”)身上执行什么任务。任务执行的结果和日志,也会统一汇报给这个中心,方便你随时查看和管理。
和SpringBoot整合后,你的业务应用就变成了听话的“工人”,只负责干活(业务逻辑),而什么时候干、干得怎么样,全部交给XXL-Job这个“项目经理”来统筹。这样一来,即使你的SpringBoot应用部署了10个、100个实例,任务也只会被调度一次,完美解决了集群下的任务重复执行问题。接下来,我就手把手带你从零开始,把这个“项目经理”请进你的SpringBoot项目。
2. 第一步:部署调度中心(XXL-Job Admin)
调度中心是XXL-Job的大脑,是一个独立部署的Web应用。我们需要先把它搭建起来。
2.1 环境准备与源码获取
首先确保你的开发环境满足以下要求,这些都是基础,缺一不可:
- JDK 1.8+:我推荐用JDK 8或11,兼容性最好。
- Maven 3.x:用于项目构建。
- MySQL 5.7+:我用的是MySQL 8.0,完全没问题,调度中心的所有元数据(任务信息、日志等)都存储在这里。
获取源码有两种主流方式,我通常用Gitee,因为在国内下载速度更快:
- GitHub:
https://github.com/xuxueli/xxl-job - Gitee(码云):
https://gitee.com/xuxueli0323/xxl-job
打开终端,执行克隆命令:
git clone https://gitee.com/xuxueli0323/xxl-job.git
cd xxl-job
拉取完成后,用IDE(比如IntelliJ IDEA或Eclipse)打开这个项目。你会看到它的目录结构非常清晰:
doc/: 存放数据库脚本和文档。xxl-job-admin/: 调度中心模块,这就是我们要部署的核心。xxl-job-core/: 核心依赖包,执行器项目需要引入它。xxl-job-executor-samples/: 各种执行器示例,我们重点看里面的springboot版本。
2.2 初始化数据库
调度中心需要一个数据库来存储任务、日志、执行器注册信息等。这一步很简单,但至关重要。
- 在你的MySQL中创建一个数据库,名字可以自定义,比如
xxl_job。 - 找到项目中的数据库脚本文件:
/doc/db/tables_xxl_job.sql。 - 在你的数据库客户端(如Navicat、MySQL Workbench)或命令行中,连接到
xxl_job数据库,然后执行这个SQL脚本。
执行成功后,你会看到创建了若干张表,其中最重要的几张表是:
xxl_job_info: 存储所有任务的基本信息。xxl_job_log: 存储每次任务调度的详细日志。xxl_job_registry: 动态注册上来的执行器地址。xxl_job_group: 执行器集群分组信息。
有了这些表,调度中心就有了记忆能力,任务状态、执行历史都不会丢失。
2.3 配置与启动调度中心
现在我们来配置调度中心,让它能连上我们刚创建的数据库。配置文件位于:
/xxl-job-admin/src/main/resources/application.properties
你需要修改的核心配置项主要是数据库连接部分,找到下面这几行:
### 调度中心JDBC链接
spring.datasource.url=jdbc:mysql://127.0.0.1:3306/xxl_job?useUnicode=true&characterEncoding=UTF-8&autoReconnect=true&serverTimezone=Asia/Shanghai
spring.datasource.username=root
spring.datasource.password=你的数据库密码
把url中的IP、端口、数据库名,以及username和password换成你自己的。这里有个小坑要注意:如果用的是MySQL 8.0,驱动类spring.datasource.driver-class-name可能需要改为com.mysql.cj.jdbc.Driver,并且url里建议加上&allowPublicKeyRetrieval=true。
其他配置项你可以先保持默认,比如报警邮箱(spring.mail开头的配置)可以先不配,等后续需要邮件告警时再设置。还有一个叫xxl.job.accessToken的配置,这是调度中心和执行器之间通信的安全令牌,如果生产环境担心接口被随意调用,可以在这里设置一个复杂的字符串,执行器那边也要配置相同的令牌。
配置完成后,找到启动类 XxlJobAdminApplication,直接运行它。如果一切顺利,控制台会打印出启动成功的日志,默认端口是8080。
打开浏览器,访问 http://localhost:8080/xxl-job-admin。你会看到一个登录界面,使用默认账号 admin 和密码 123456 登录。恭喜你,至此调度中心这个“大脑”已经成功启动并运行了!登录后你能看到一个清晰的管理后台,这里就是未来你管理所有定时任务的“指挥所”。
3. 第二步:在SpringBoot项目中接入执行器
调度中心搭好了,现在需要让你的SpringBoot应用成为一个“工人”(执行器),并告诉“大脑”:“我在这里,有活可以派给我”。
3.1 引入核心依赖
在你的SpringBoot项目的pom.xml文件中,添加XXL-Job的核心依赖。版本号请务必与你的调度中心版本保持一致,否则可能会出现通信协议不兼容的问题。你可以查看调度中心项目pom.xml里的版本,或者去Maven中央仓库找最新稳定版。
<dependency>
<groupId>com.xuxueli</groupId>
<artifactId>xxl-job-core</artifactId>
<version>2.4.1</version> <!-- 请确认版本号 -->
</dependency>
添加依赖后,记得刷新一下Maven项目。
3.2 配置执行器参数
接下来,需要在你的application.yml(或application.properties)中,告诉你的应用如何找到调度中心,以及如何介绍自己。我更喜欢用YAML格式,更清晰:
xxl:
job:
admin:
# 调度中心的地址,如果集群部署,可以用逗号分隔多个地址
addresses: http://localhost:8080/xxl-job-admin
# 执行器自身的配置
executor:
# 执行器的应用名,这是最重要的标识!调度中心靠这个来识别你是哪个“班组”
appname: your-springboot-app
# 执行器监听的IP和端口,用于接收调度中心发来的任务指令
# ip 不配置默认会自动获取,但在多网卡服务器或容器内可能需要手动指定
# port 默认是9999,如果单机启动多个执行器实例,端口不能冲突
ip:
port: 9999
# 任务执行日志的本地存储路径
logpath: ./logs/xxl-job/jobhandler
# 日志保留天数,默认30天
logretentiondays: 30
# 访问令牌,需要和调度中心配置的 xxl.job.accessToken 一致,用于安全校验
accessToken: default_token
这里我解释几个关键点:
appname:这是执行器在调度中心的唯一标识。你可以理解为“班组名”。比如你有“用户服务”和“订单服务”两个SpringBoot应用,可以分别设置appname为user-service和order-service。调度中心会根据这个名称来分组管理执行器。addresses:必须确保这里填写的地址,能从你的SpringBoot应用网络访问到。如果是docker容器部署,不能写localhost。logpath:任务执行的详细日志会写在这个目录下。在调度中心Web界面点击“查看日志”时,调度中心会通过RPC请求到这个执行器来读取该目录下的日志文件。
3.3 创建执行器配置类
仅有配置文件还不够,我们需要一个Spring配置类来读取这些配置,并初始化XXL-Job的执行器组件。在你的项目里创建一个配置类,比如XxlJobConfig:
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 static final Logger logger = LoggerFactory.getLogger(XxlJobConfig.class);
@Value("${xxl.job.admin.addresses}")
private String adminAddresses;
@Value("${xxl.job.executor.appname}")
private String appName;
@Value("${xxl.job.executor.port:9999}") // 提供默认值
private int port;
@Value("${xxl.job.accessToken:}")
private String accessToken;
@Value("${xxl.job.executor.logpath}")
private String logPath;
@Value("${xxl.job.executor.logretentiondays:30}")
private int logRetentionDays;
@Bean
public XxlJobSpringExecutor xxlJobExecutor() {
logger.info(">>>>>>>>>>> XXL-Job执行器配置开始初始化,AppName: {}, Admin地址: {}", appName, adminAddresses);
XxlJobSpringExecutor executor = new XxlJobSpringExecutor();
executor.setAdminAddresses(adminAddresses);
executor.setAppname(appName);
executor.setPort(port);
executor.setAccessToken(accessToken);
executor.setLogPath(logPath);
executor.setLogRetentionDays(logRetentionDays);
// 其他属性如ip、address等,除非有特殊需求(如容器环境网络复杂),否则可以不设置,框架会自动处理
return executor;
}
}
这个类的作用是,在Spring容器启动时,自动创建一个XxlJobSpringExecutor Bean。这个Bean会做两件重要的事:第一,向配置的调度中心地址定时发送心跳,说“我活着”;第二,启动一个内嵌的Netty服务,监听指定端口,等待调度中心下发任务执行命令。
3.4 启动并验证注册
完成以上三步后,启动你的SpringBoot应用。观察启动日志,如果看到类似 >>>>>>>>>>> xxl-job config init. 和 >>>>>>>>>>> xxl-job executor start success. 的日志,说明执行器初始化成功。
现在,回到调度中心的管理界面 (http://localhost:8080/xxl-job-admin)。点击左侧菜单栏的 “执行器管理”。你应该能看到一个名为 your-springboot-app(就是你配置的appname)的执行器自动出现在列表里,并且“注册方式”是“自动注册”,“机器地址”那一列会显示你的应用IP和端口(如192.168.1.100:9999)。
如果没看到,别慌,按以下步骤排查:
- 检查网络:确保你的SpringBoot应用能访问到调度中心的地址 (
http://localhost:8080)。可以在应用服务器上用curl命令测试一下。 - 检查配置:核对
application.yml中的appname和addresses是否拼写正确。 - 查看日志:仔细查看SpringBoot应用启动日志,是否有关于XXL-Job的错误信息。常见错误包括数据库连接失败、端口被占用等。
- 等待心跳:执行器是周期性(30秒一次)注册的,刚启动可能需要等半分钟才能在调度中心看到。
当你看到执行器在线,就意味着你的SpringBoot应用已经成功“入职”,随时准备接受任务了。
4. 第三步:开发你的第一个分布式定时任务
执行器就绪后,我们就可以开发具体的任务逻辑了。XXL-Job支持多种任务模式,最常用、最推荐的是 BEAN模式。这种模式下,任务逻辑就写在你的SpringBoot项目里,像一个普通的Spring Bean一样,可以被依赖注入,管理起来非常方便。
4.1 编写任务处理器(JobHandler)
假设我们要做一个简单的任务:每分钟打印一次当前时间,并模拟处理一些业务数据。在你的Service包下创建一个类,比如DemoJobHandler:
import com.xxl.job.core.context.XxlJobHelper;
import com.xxl.job.core.handler.annotation.XxlJob;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import org.springframework.stereotype.Component;
@Component
public class DemoJobHandler {
private static final Logger logger = LoggerFactory.getLogger(DemoJobHandler.class);
/**
* 示例任务:打印当前时间
* 方法名无所谓,关键是@XxlJob注解里的value值,这就是任务的“代号”
*/
@XxlJob("demoJobHandler") // 这个“demoJobHandler”就是任务标识
public void executeDemoJob() throws Exception {
// 通过XxlJobHelper可以获取任务上下文信息,比如任务参数
String jobParam = XxlJobHelper.getJobParam();
logger.info("【XXL-JOB】开始执行示例任务,传入参数: {}", jobParam);
// 模拟业务逻辑
for (int i = 0; i < 5; i++) {
logger.info("【XXL-JOB】正在处理第 {} 条数据,当前时间: {}", i+1, new java.util.Date());
// 使用XxlJobHelper.log记录日志,这个日志可以在调度中心界面看到
XxlJobHelper.log("Processing item: {}, time: {}", i+1, new java.util.Date());
Thread.sleep(1000); // 模拟耗时操作
}
// 任务执行成功,返回成功结果。如果失败,可以返回XxlJobHelper.FAIL
XxlJobHelper.handleSuccess("示例任务执行完毕,共处理5条数据。");
logger.info("【XXL-JOB】示例任务执行结束。");
}
/**
* 再写一个任务,演示分片广播场景(比如处理数据库所有用户)
*/
@XxlJob("userSyncJobHandler")
public void executeUserSyncJob() {
// 获取分片参数:当前是第几个分片,总分片数是多少
int shardIndex = XxlJobHelper.getShardIndex();
int shardTotal = XxlJobHelper.getShardTotal();
logger.info("【XXL-JOB分片任务】开始执行,我是第 {}/{} 个分片", shardIndex + 1, shardTotal);
XxlJobHelper.log("分片参数: index={}, total={}", shardIndex, shardTotal);
// 假设这里根据分片参数去数据库查询属于自己分片的数据进行处理
// 例如:SELECT * FROM user WHERE id % {shardTotal} = {shardIndex}
// 这样可以实现集群下并行处理全量数据,避免重复
XxlJobHelper.handleSuccess(String.format("分片 %d/%d 执行完成", shardIndex, shardTotal));
}
}
代码很简单,但有几个关键点:
@XxlJob("demoJobHandler"):这个注解是核心,它把这个方法声明为一个XXL-Job任务。注解里的字符串"demoJobHandler"是任务的唯一标识符,后面在调度中心创建任务时必须用到。XxlJobHelper:这是一个工具类,非常重要。通过它可以:getJobParam():获取调度中心页面配置的任务参数。getShardIndex()/getShardTotal():在分片广播任务中,获取当前分片索引和总分片数,用于大数据量的并行处理。log(...):记录日志。这里记录的日志会专门发送到调度中心,你在Web界面点“查看日志”时看到的就是这个。handleSuccess()/handleFail():标记任务执行成功或失败。
- 业务逻辑:在方法体内,你可以写任何Java代码,就像普通的Service方法一样。可以注入其他Spring Bean,调用数据库,发送HTTP请求等等。
4.2 在调度中心创建并配置任务
代码写好了,现在需要去调度中心“登记”这个任务,并告诉它执行规则。
- 进入任务管理:登录调度中心,点击左侧 “任务管理”,然后点击 “新增” 按钮。
- 填写任务基础信息:
- 执行器:选择我们之前自动注册上来的
your-springboot-app。 - 任务描述:写清楚,比如“示例任务:每分钟打印日志”。
- 路由策略:当你的执行器有多个实例(集群)时,决定任务发给谁。常用“轮询”或“第一个”。我们先选“轮询”。
- Cron:定时表达式。点击输入框旁边的“生成Cron”可以可视化生成。我们输入
0 */1 * * * ?表示每分钟的第0秒执行。 - 运行模式:选择 BEAN模式。
- JobHandler:这里必须填写代码中
@XxlJob注解里定义的value值,我们填demoJobHandler。这是调度中心找到具体执行方法的钥匙。 - 阻塞处理策略:如果上一个任务还没跑完,下一个触发时间又到了怎么办?“单机串行”会排队,“丢弃后续调度”会忽略新触发,“覆盖之前调度”会终止旧任务。根据业务重要性选择,测试可以用“单机串行”。
- 任务参数:可以传递字符串参数给任务,在代码里用
XxlJobHelper.getJobParam()获取。比如可以传type=daily。
- 执行器:选择我们之前自动注册上来的
- 高级配置(可选但重要):
- 失败重试次数:任务执行失败后自动重试的次数,建议设置大于0。
- 报警邮件:任务失败后通知的邮箱。需要先在调度中心配置好邮件服务器。
- 负责人:填写你的名字或团队,方便排查问题。
填写完毕后,点击“保存”。任务就创建好了,但默认是“停止”状态。
4.3 启动任务与监控执行
在任务列表找到刚创建的任务,点击操作栏的 “启动” 按钮。任务状态会变成“运行中”。到了你设定的Cron时间(比如下一分钟的0秒),调度中心就会向你的执行器发起调度。
要验证任务是否成功执行,有几种方式:
- 查看执行器本地日志:去你的SpringBoot应用日志文件里,搜索
【XXL-JOB】,应该能看到我们代码里打印的日志。 - 查看调度中心日志(推荐):在调度中心任务列表,点击该任务右侧的 “日志” 按钮。这里会集中展示每一次调度的记录。点击某次调度记录后面的“执行日志”,就能看到通过
XxlJobHelper.log()打印的日志内容。这是最直观的监控方式。 - 手动执行一次:在任务列表,点击“操作”栏的 “执行一次”,可以立即触发任务,用于测试和调试。
如果日志显示执行成功,那么恭喜你,你的第一个分布式定时任务已经完美运行起来了!调度中心负责定时触发,你的SpringBoot应用负责执行,两者各司其职,配合默契。
5. 进阶实战:处理复杂场景与避坑指南
基本的跑通只是开始,在实际生产环境中,我们会遇到更复杂的需求和各种各样的“坑”。下面我结合自己的经验,分享几个进阶场景和关键注意事项。
5.1 集群部署与路由策略
当你的SpringBoot应用以集群方式部署(比如启动了2个或更多实例)时,XXL-Job的执行器会自动注册上来多个地址。这时候,调度中心的路由策略就派上用场了。
在创建任务时,“路由策略”选项决定了任务会被下发到哪个实例:
- 轮询(ROUND):依次选择在线执行器。适合负载均衡。
- 第一个(FIRST):总是选择第一个注册的执行器。
- 最后一个(LAST):总是选择最后一个。
- 随机(RANDOM):随机选择一个。
- 一致性HASH(CONSISTENT_HASH):根据任务ID进行Hash,同一个任务总是落到同一台机器。适合需要“粘性”的任务。
- 最不经常使用(LEAST_FREQUENTLY_USED) / 最近最久未使用(LEAST_RECENTLY_USED):基于使用频率的选择策略。
- 故障转移(FAILOVER):依次检测,选择第一个心跳检测成功的。
- 忙碌转移(BUSYOVER):依次检测,选择第一个空闲的。
我的经验:对于普通的定时任务,用“轮询”或“随机”就好,简单公平。对于需要保证同一类数据始终由同一台机器处理的任务(比如按用户ID分片),可以用“一致性HASH”。对于非常重要的任务,可以用“故障转移”来保证高可用。
5.2 分片广播:处理海量数据
这是XXL-Job一个非常强大的功能。假设你有一个任务需要处理数据库里1000万条用户数据,单机跑太慢。你可以用“分片广播”。
- 任务配置:在调度中心创建任务时,“路由策略”选择 “分片广播”。
- 代码改造:就像上面
userSyncJobHandler示例一样,在任务方法中调用XxlJobHelper.getShardIndex()和XxlJobHelper.getShardTotal()。 - 执行过程:当任务触发时,调度中心会向该执行器分组下的所有在线实例都下发这个任务。每个实例获取到的分片参数不同(例如,3个实例,总分片数
shardTotal=3,每个实例的shardIndex分别是0,1,2)。这样,每个实例就可以只处理属于自己的那一份数据(比如WHERE id % 3 = ?),实现并行处理,极大提升效率。
注意:分片总数是动态的,等于当前在线的执行器实例数。所以你的业务逻辑要能适应分片数的变化。
5.3 任务参数与动态配置
任务参数(JobParam)是一个非常灵活的功能。你可以在调度中心配置任务时填入参数,在代码中获取。这有什么用呢?比如你有一个数据清洗任务,有时需要清洗“用户表”,有时需要清洗“订单表”。你不需要写两个任务,只需要一个任务,然后通过传入不同的参数(如 tableName=user 或 tableName=order)来控制。
在调度中心任务配置的“任务参数”栏填入:type=full, date=2024-01-01
在代码中获取:
String param = XxlJobHelper.getJobParam(); // 得到 "type=full, date=2024-01-01"
// 可以自己解析这个字符串,或者用一些工具类转成Map
更高级的用法是,结合配置中心(如Nacos、Apollo),在参数里存放一个配置的Key,任务执行时去配置中心拉取最新的配置,实现任务行为的动态调整,无需重启应用或重新部署任务代码。
5.4 常见问题与排查技巧
在实际使用中,我踩过不少坑,这里总结一下:
-
任务显示“运行中”但执行器没收到:
- 检查执行器状态:去“执行器管理”看看你的
appname对应的执行器是否在线(绿色)。如果不在线,检查执行器项目日志,看是否注册失败。 - 检查网络和防火墙:确保调度中心能访问到执行器配置的
ip:port。执行器启动时默认会绑定0.0.0.0,但如果是容器环境,可能需要显式配置xxl.job.executor.ip为宿主机的IP或容器对外IP。 - 检查JobHandler名称:调度中心任务配置的“JobHandler”必须和代码中
@XxlJob(“xxx”)里的“xxx”完全一致,包括大小写。
- 检查执行器状态:去“执行器管理”看看你的
-
任务执行失败,日志显示“job thread is running, has been killed”:
- 这通常是任务执行时间太长,超过了配置的“任务超时时间”。在调度中心任务配置里,适当调大“任务超时时间”,或者优化你的任务代码,避免长时间运行。
-
执行器日志正常,但调度中心“执行日志”看不到
XxlJobHelper.log的内容:- 确保你在任务代码中使用了
XxlJobHelper.log()来记录关键信息,而不是只用logger.info()。只有前者才会被发送回调度中心。 - 检查执行器的
logpath配置的目录是否存在且有写权限。
- 确保你在任务代码中使用了
-
如何优雅停止和重启任务:
- 在调度中心任务列表,可以点击“停止”来暂停任务调度。修改任务配置后,需要先“停止”,再“启动”才能生效。
- 重启执行器(你的SpringBoot应用)时,正在运行的任务会被中断。对于重要任务,建议实现幂等性,或者选择“阻塞处理策略”为“丢弃后续调度”,避免重复执行。
-
数据库连接池耗尽:
- 如果你的任务大量并发操作数据库,可能会占满连接池,影响主业务。强烈建议为XXL-Job任务使用独立的数据库连接池(在任务代码中注入一个专用的
DataSource),与主业务隔离。
- 如果你的任务大量并发操作数据库,可能会占满连接池,影响主业务。强烈建议为XXL-Job任务使用独立的数据库连接池(在任务代码中注入一个专用的
把XXL-Job整合进SpringBoot项目,绝不是简单的配置完就了事。理解其调度原理,根据业务场景选择合适的路由和分片策略,做好监控和异常处理,才能让它真正成为你系统中稳定可靠的“任务管家”。从简单的日志打印到复杂的数据批处理,这套组合拳都能应对自如。
432



被折叠的 条评论
为什么被折叠?



