用途:整理 XXL-JOB 在 Spring Boot 项目中的最佳实践模式,基于 hiwepy/xxljob-spring-boot-starter 封装,覆盖任务定义、注册、管理与监控。
主要能力:@XxlJobCron 注解可替代原生 @XxlJob,将 cron、desc、author、selfStarting 等配置写在代码中;selfStarting=true 时执行器启动自动注册到 Admin,无需在 UI 手动创建;XxlJobTemplate 支持编程式添加、更新、删除、启动、停止、触发任务,并自动续期 session;兼容 Admin v2/v3 参数差异(v2 用 id,v3 用 ids[]);Micrometer 自动采集执行次数、成功、失败、耗时并对接 Prometheus;Unirest HTTP 客户端自动配置 SSL(trust-all)、Cookie 管理与超时。
使用方式:在方法上使用 @XxlJobCron 声明任务,配合 @Slf4j、@Component、@RequiredArgsConstructor 构造器注入;通过 XxlJobTemplate.addUniqueJob 幂等注册任务,triggerJob 手动触发,stopJob/startJob 暂停恢复;配置项包括 accessToken、admin.version、admin.addresses、executor.appname、executor.ip、executor.port(0 自动探测,-1 不启动)、log-path、log-retention-days 等。
适用场景:需要代码即配置、自动注册、集中管理定时任务的 Spring Boot 项目。
限制:不适用于简单单机定时任务(可用 @Scheduled),替代方案有 PowerJob、ElasticJob;@XxlJobCron 与 MetricMethodJobHandler 存在反射冲突,可能抛 NullPointerException,可禁用 Micrometer、添加空 @XxlJob 或升级 starter 解决;多网卡环境需指定 executor.ip;XxlJobHelper.handleFail 需显式调用,否则默认视为成功。本技能不收集、存储或传输任何用户数据。