← 课程目录 🚀 从零到一
📐 学习维度 阶段7 · 第28章 开源项目源码精读 🚀 从零到一 📚 课程目录 🏠 首页 🛤️ 学习路径

28.6.3 XXL-JOB:执行器注册回调与分片广播

审校 2026-09-26 · 素材来源:zcode会话《分析XXL-Job项目架构与集群使用》(项目源码分析)
📑 本篇章节导航 (共6节,点击直达)
场景:执行器是怎么被调度中心发现的类比:外卖骑手接单可跑示例:分片任务原理:分片与重试的源码细节踩坑清单面试怎么问

一千万用户的数据要每天凌晨清洗一遍,一台机器跑六小时。加机器容易,可数据怎么切?切不均怎么办?机器临时挂一台,少处理的那份谁补?XXL-JOB 的答案:执行器集群 + 分片广播。

场景:执行器是怎么被调度中心发现的

你的业务应用引入 xxl-job-core,写了个 @XxlJob 方法。它凭什么知道 admin 在哪、admin 又凭什么知道它在哪?这靠一套自注册 + 心跳续约机制。

启动流程(XxlJobSpringExecutor,Spring 容器初始化完成后触发):

1. 扫描所有 @XxlJob 注解方法,注册进内存 jobHandlerRepository

2. 启动内置 Netty HTTP 服务(高性能网络框架,默认端口 9999)

3. ExecutorRegistryThreadHelper 每 30 秒向 admin 发一次 registry 心跳,登记自己的地址

4. TriggerCallbackThreadHelper 负责把执行结果回调给 admin

admin 侧的 JobRegistryHelper 维护注册表:90 秒收不到心跳就判定死亡,剔除该地址。新机器上线自动纳入,下线自动摘除——这就是执行器集群的动态扩缩容。

类比:外卖骑手接单

执行器像骑手:上岗先报到(注册),每 30 秒发一次定位(心跳),超时没消息平台就当你下线了(剔除)。平台派单时按策略挑一个骑手(路由策略),骑手送完必须点「已送达」(回调)。

分片广播则是:这单太大,会拆成十份,所有骑手每人一份,各自送各自的。谁的车坏了(某片失败),平台只给他重派那一单。

可跑示例:分片任务


@Component
public class ShardingJobHandler {

    @XxlJob("shardingJobHandler")
    public void execute() {
        int index = XxlJobHelper.getShardIndex();  // 我是第几片,从0开始
        int total = XxlJobHelper.getShardTotal();  // 总共几片

        XxlJobHelper.log("第{}/{}片开始", index + 1, total);

        // 数据按分片取模切分:1000万用户,3台机器各处理自己的1/3
        List<User> users = userDao.findByMod(total, index);
        for (User u : users) {
            // 清洗逻辑 ...
        }
        XxlJobHelper.handleSuccess("本片完成");
    }
}

-- 分片取模的典型 SQL:每台只扫自己那片
SELECT * FROM user WHERE MOD(id, #{total}) = #{index}

admin 页面上把该任务的路由策略选成「分片广播 (SHARDING_BROADCAST)」,失败重试次数填 1。三台执行器收到请求时,各自被塞入不同的 shardIndex(0、1、2),互不重叠地处理完全量数据。

注意一个细节:路由策略选了分片广播,阻塞策略仍然生效。如果某片执行慢,下一次触发到来时按该任务的阻塞策略处理(排队、丢弃或覆盖),和其他路由没有区别。

原理:分片与重试的源码细节

触发与 JobThread

admin 对分片广播的处理:遍历 addressList 里所有注册地址,逐个调用执行器的 /trigger 接口,每个请求带上 shardIndex/shardTotal 参数。非分片路由则只挑一个地址。

执行器侧 ExecutorBizImpl.trigger() 先按阻塞策略处理(串行排队/丢弃/覆盖),再把请求塞进该 jobId 独享的 JobThread 队列。每个任务一个独立线程 + 队列,任务之间互不干扰,这也解释了为什么默认串行策略不会并发执行同一个任务。

回调链路

JobThread 执行完 handler.execute() 后把结果放进回调队列,TriggerCallbackThreadHelper 批量回调 admin。admin 更新执行日志、统计成功率;失败则按配置的重试次数重新触发。

分片粒度的失败重试

这是分片广播最贴心的设计:三片中第 2 片失败,重试时只重试 shardIndex=2 这一片,第 1、3 牄不重复执行。重试请求携带原分片参数,由 admin 的重试逻辑保证。

生命周期与超时

@XxlJob(value="x", init="initMethod", destroy="destroyMethod"):init 在 JobThread 创建时调一次(初始化连接池等资源),destroy 在线程销毁时调一次(释放)。任务配了超时时间,超时后 admin 调执行器的 kill 接口中断 JobThread。

3.x 的新能力

新版还加了 AI 任务执行器(集成 Spring AI / Ollama / Dify)、优雅停机(停机时等时间轮任务跑完、执行器等运行中任务完成)、线程池隔离与审计日志。分片广播的玩法不变,是大数据处理的主力姿势。

优雅停机:分片任务的收尾难题

分片任务跑一半时执行器要发版,直接 kill 会丢掉正在处理的那一片。3.x 的优雅停机(进程退出前先处理完在途任务的机制)解决这个:执行器收到停机信号后不再接受新触发,等运行中的 JobThread 跑完、回调发完才退出。配合「失败重试」,即便某片真的被中断,admin 也会补跑那一片,数据最终不丢。

旧版本没这能力时的土办法:发版前先把 admin 上该任务停掉,跑完再发,发完再启用——本质是人工版优雅停机。

跨语言接入

执行器协议是简单的 HTTP + JSON,官方提供跨语言 OpenAPI(RESTful),Go、Python 等任何语言都能实现执行器:起一个 HTTP 服务响应 /trigger、/beat、/idleBeat、/kill 几个接口,再按 30 秒节奏调 admin 的注册接口即可。Java 生态外的系统想被统一调度,走这条路。

踩坑清单

面试怎么问

「分片广播和消息队列分片消费有什么区别?」——答:分片广播是调度侧主动按执行器数量切分,任务跑完即止,适合批处理;MQ 分片是消费侧被动拉取,实时流式处理。XXL-JOB 分片失败可按片粒度重试,只重跑失败那片。

「执行器怎么实现动态扩缩容?」——答:执行器每 30 秒向 admin 心跳注册,admin 90 秒收不到即剔除;下次触发时按最新 addressList 分配分片,无需重启任何一方。