1. 從零到一為什么我們需要一個獨(dú)立的定時(shí)任務(wù)調(diào)度器在任何一個稍具規(guī)模的后端應(yīng)用里定時(shí)任務(wù)都是一個繞不開的話題。你可能需要每天凌晨三點(diǎn)同步一次用戶數(shù)據(jù)或者每隔五分鐘檢查一次訂單狀態(tài)又或者在每周一早上九點(diǎn)給所有用戶發(fā)送一封周報(bào)郵件。最開始我們可能會圖省事直接用Scheduled注解或者在application.yml里配個cron表達(dá)式項(xiàng)目小的時(shí)候這確實(shí)沒問題。但項(xiàng)目一旦跑起來問題就接踵而至了。最頭疼的就是“單點(diǎn)故障”任務(wù)都跑在一臺機(jī)器上這臺機(jī)器一掛所有定時(shí)任務(wù)全停擺業(yè)務(wù)直接受影響。其次是“任務(wù)雪崩”某個任務(wù)執(zhí)行時(shí)間過長或者卡死可能會拖垮整個線程池導(dǎo)致其他輕量級任務(wù)也無法執(zhí)行。再者就是“管理困難”任務(wù)散落在各個服務(wù)的代碼里想統(tǒng)一查看執(zhí)行日志、手動觸發(fā)一次或者調(diào)整調(diào)度時(shí)間都得去翻代碼、改配置、重啟服務(wù)運(yùn)維成本極高。這時(shí)候一個中心化的、可視化的、支持高可用的任務(wù)調(diào)度平臺就成了剛需。XXL-JOB 正是在這種背景下脫穎而出的一款輕量級分布式任務(wù)調(diào)度框架。它的核心設(shè)計(jì)思想是“調(diào)度中心”與“執(zhí)行器”分離。調(diào)度中心負(fù)責(zé)管理所有任務(wù)的調(diào)度邏輯發(fā)出觸發(fā)指令而執(zhí)行器就是我們的業(yè)務(wù)應(yīng)用它負(fù)責(zé)接收調(diào)度中心的指令執(zhí)行具體的業(yè)務(wù)代碼。這種架構(gòu)天然就支持了分布式部署和水平擴(kuò)展一個任務(wù)可以被路由到集群中的任何一個健康實(shí)例上執(zhí)行完美解決了單點(diǎn)問題。今天我們不談復(fù)雜的生產(chǎn)集群就從最基礎(chǔ)、也是最關(guān)鍵的第一步開始如何在一臺機(jī)器上快速搭建起一個可用的 XXL-JOB 調(diào)度中心并且掌握最核心的編程技能——如何用代碼動態(tài)地管理任務(wù)。這對于前期技術(shù)驗(yàn)證、開發(fā)測試環(huán)境搭建乃至一些對可用性要求不是極高的內(nèi)部應(yīng)用都極具價(jià)值。畢竟不是所有場景都需要一開始就上集群。2. 調(diào)度中心的單機(jī)部署避開那些“看起來對”的坑部署 XXL-JOB 調(diào)度中心本質(zhì)上就是運(yùn)行一個 Spring Boot 應(yīng)用。官方提供了非常便捷的兩種方式下載發(fā)行包直接運(yùn)行或者下載源碼自己編譯。對于學(xué)習(xí)和測試我強(qiáng)烈建議選擇前者能幫你避開不少環(huán)境依賴的坑。2.1 環(huán)境準(zhǔn)備與源碼獲取首先確保你的機(jī)器上已經(jīng)安裝了 JDK1.8和 Maven3.0。這是編譯和運(yùn)行的基礎(chǔ)。接下來是獲取代碼。不要想當(dāng)然地去 GitHub 搜一個看起來像的倉庫最穩(wěn)妥的方式永遠(yuǎn)是訪問官方文檔。XXL-JOB 的官方倉庫在 GitHub 上項(xiàng)目地址是xuxueli/xxl-job。你可以通過git clone命令拉取或者直接下載 ZIP 壓縮包。這里有個小技巧直接下載最新 Release 版本的源碼包通常比拉取主分支master更穩(wěn)定因?yàn)?Release 版本是經(jīng)過測試的。# 方式一克隆倉庫網(wǎng)絡(luò)需穩(wěn)定 git clone https://github.com/xuxueli/xxl-job.git # 方式二更推薦訪問 https://github.com/xuxueli/xxl-job/releases # 下載最新版本的 Source code (zip) 文件比如 xxl-job-2.4.0.zip解壓后目錄結(jié)構(gòu)清晰可見。我們重點(diǎn)關(guān)注xxl-job-admin模塊這就是調(diào)度中心的管理后臺。2.2 數(shù)據(jù)庫初始化字符集與驅(qū)動版本的隱秘陷阱XXL-JOB 的所有調(diào)度數(shù)據(jù)任務(wù)、日志、執(zhí)行器等都需要存儲在關(guān)系型數(shù)據(jù)庫中它支持 MySQL 等主流數(shù)據(jù)庫。執(zhí)行目錄/doc/db/tables_xxl_job.sql下的腳本就能創(chuàng)建所需的表。這個過程看似簡單卻有兩個高頻踩坑點(diǎn)數(shù)據(jù)庫字符集務(wù)必使用utf8mb4字符集。utf8在 MySQL 中是一個“閹割版”最大只支持3字節(jié)字符無法存儲完整的 Emoji 或某些生僻字。如果建表時(shí)沒指定默認(rèn)可能是latin1或utf8未來任務(wù)描述等信息一旦包含4字節(jié)字符就會報(bào)錯。安全的做法是在連接數(shù)據(jù)庫后先執(zhí)行SET NAMES utf8mb4;然后再運(yùn)行建表 SQL。MySQL 驅(qū)動版本項(xiàng)目pom.xml中默認(rèn)引用的 MySQL 驅(qū)動版本可能較老如mysql-connector-java5.x。如果你本地安裝的是 MySQL 8.0高版本驅(qū)動在連接 URL 和身份驗(yàn)證插件上都有變化直接運(yùn)行會導(dǎo)致Public Key Retrieval is not allowed或Authentication plugin ‘caching_sha2_password‘ cannot be loaded這類錯誤。解決方案是在xxl-job-admin的pom.xml中顯式地將驅(qū)動依賴升級到 8.0.x 版本并調(diào)整連接字符串。!-- 在 xxl-job-admin 的 pom.xml 中修改 -- dependency groupIdmysql/groupId artifactIdmysql-connector-java/artifactId version8.0.33/version !-- 版本號根據(jù)你的MySQL調(diào)整 -- /dependency同時(shí)在配置文件中連接 URL 需要添加時(shí)區(qū)和允許公鑰檢索的參數(shù)spring.datasource.urljdbc:mysql://localhost:3306/xxl_job?useUnicodetruecharacterEncodingUTF-8autoReconnecttrueserverTimezoneAsia/ShanghaiallowPublicKeyRetrievaltrue spring.datasource.usernameroot spring.datasource.passwordyour_password2.3 核心配置修改不止是改個數(shù)據(jù)庫地址數(shù)據(jù)庫準(zhǔn)備好后需要修改調(diào)度中心的配置文件。配置文件位于xxl-job-admin/src/main/resources/application.properties或application.yml。你需要修改的遠(yuǎn)不止數(shù)據(jù)庫連接。以下幾個配置項(xiàng)關(guān)乎調(diào)度中心能否正常啟動和工作server.port調(diào)度中心服務(wù)端口默認(rèn) 8080按需修改。spring.datasource.*如上所述配置你的數(shù)據(jù)庫連接。xxl.job.accessToken可選但重要調(diào)度中心和執(zhí)行器之間的通信令牌。如果為空表示不進(jìn)行鑒權(quán)。在生產(chǎn)環(huán)境或任何有安全顧慮的環(huán)境務(wù)必設(shè)置一個強(qiáng)令牌。否則任何知道調(diào)度中心地址的程序都可以偽裝成執(zhí)行器來注冊或觸發(fā)任務(wù)存在安全風(fēng)險(xiǎn)。xxl.job.i18n默認(rèn)是zh_CN中文如果你需要英文界面可以改為en。logging.level.com.xxl.job調(diào)試時(shí)可以設(shè)置為DEBUG能看到更詳細(xì)的調(diào)度日志方便排查問題。2.4 編譯與啟動區(qū)分“編譯環(huán)境”與“運(yùn)行環(huán)境”配置修改完成后在項(xiàng)目根目錄執(zhí)行mvn clean package -DskipTests進(jìn)行編譯打包。打包成功后在xxl-job-admin/target/目錄下會生成xxl-job-admin-2.4.0.jar版本號可能不同。這里有一個關(guān)鍵認(rèn)知編譯環(huán)境和運(yùn)行環(huán)境是分離的。你完全可以在 A 機(jī)器上編譯好這個 JAR 包然后復(fù)制到 B 機(jī)器甚至是沒有 Maven、沒有源碼的機(jī)器上去運(yùn)行。運(yùn)行命令非常簡單java -jar xxl-job-admin-2.4.0.jar啟動后訪問http://localhost:8080/xxl-job-admin端口根據(jù)你的配置就能看到登錄界面。默認(rèn)賬號密碼是admin/123456。登錄成功后一個功能完整的調(diào)度中心管理后臺就展現(xiàn)在你面前了。至此調(diào)度中心單機(jī)部署完成。但我們的目標(biāo)不止于此我們要讓這個調(diào)度中心能指揮我們的業(yè)務(wù)代碼干活。3. 執(zhí)行器集成你的業(yè)務(wù)應(yīng)用如何“被調(diào)度”調(diào)度中心是“大腦”執(zhí)行器就是“手腳”。我們需要在自己的 Spring Boot 業(yè)務(wù)應(yīng)用中集成 XXL-JOB 的執(zhí)行器客戶端讓它能夠接收大腦的指令。3.1 依賴引入與基礎(chǔ)配置首先在你的業(yè)務(wù)項(xiàng)目的pom.xml中添加 XXL-JOB 執(zhí)行器客戶端的依賴。同樣請注意版本與調(diào)度中心保持一致。dependency groupIdcom.xuxueli/groupId artifactIdxxl-job-core/artifactId version2.4.0/version /dependency接著在application.yml中配置執(zhí)行器的核心參數(shù)。這些參數(shù)決定了執(zhí)行器是誰、在哪、如何聯(lián)系調(diào)度中心。xxl: job: admin: addresses: http://localhost:8080/xxl-job-admin # 調(diào)度中心地址集群用逗號分隔 accessToken: # 與調(diào)度中心配置的accessToken一致若無則留空 executor: appname: xxl-job-executor-sample # 執(zhí)行器AppName是調(diào)度中心識別該集群的唯一標(biāo)識 address: # 執(zhí)行器地址默認(rèn)自動注冊時(shí)留空 ip: # 執(zhí)行器IP自動注冊時(shí)留空調(diào)度中心會自動獲取 port: 9999 # 執(zhí)行器端口默認(rèn)9999內(nèi)置Jetty服務(wù)器用于接收調(diào)度請求 logpath: /data/applogs/xxl-job/jobhandler # 任務(wù)日志文件存儲路徑 logretentiondays: 30 # 日志保留天數(shù)重點(diǎn)解析appname和addressappname這是一個邏輯名稱代表一組執(zhí)行器實(shí)例。比如你的“訂單服務(wù)”部署了3臺機(jī)器它們都應(yīng)該配置相同的appname如order-service-executor。調(diào)度中心會根據(jù)這個名稱來找到這一組執(zhí)行器進(jìn)行任務(wù)的路由和故障轉(zhuǎn)移。address這是執(zhí)行器的網(wǎng)絡(luò)地址格式為IP:PORT。這里有個非常重要的模式選擇自動注冊vs手動錄入。自動注冊推薦將address留空。執(zhí)行器啟動后會主動向調(diào)度中心admin.addresses發(fā)起注冊上報(bào)自己的ip:port。調(diào)度中心會動態(tài)維護(hù)這個執(zhí)行器地址列表。這種方式適合動態(tài)伸縮的云環(huán)境。手動錄入在配置文件中寫死address: 192.168.1.100:9999。同時(shí)你還需要提前到調(diào)度中心管理后臺的“執(zhí)行器管理”頁面手動添加一個AppName為xxl-job-executor-sample的執(zhí)行器并在其下“手動錄入”這個地址。這種方式更靜態(tài)常用于網(wǎng)絡(luò)隔離嚴(yán)格的環(huán)境。3.2 配置類與執(zhí)行器Bean聲明光有配置還不夠需要在 Spring 的上下文中聲明執(zhí)行器組件。創(chuàng)建一個配置類例如XxlJobConfigimport 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 Logger logger LoggerFactory.getLogger(XxlJobConfig.class); Value(${xxl.job.admin.addresses}) private String adminAddresses; Value(${xxl.job.accessToken}) private String accessToken; Value(${xxl.job.executor.appname}) private String appname; Value(${xxl.job.executor.address}) private String address; Value(${xxl.job.executor.ip}) private String ip; Value(${xxl.job.executor.port}) private int port; Value(${xxl.job.executor.logpath}) private String logPath; Value(${xxl.job.executor.logretentiondays}) private int logRetentionDays; Bean public XxlJobSpringExecutor xxlJobExecutor() { logger.info( xxl-job config init.); XxlJobSpringExecutor xxlJobSpringExecutor new XxlJobSpringExecutor(); xxlJobSpringExecutor.setAdminAddresses(adminAddresses); xxlJobSpringExecutor.setAppname(appname); xxlJobSpringExecutor.setAddress(address); xxlJobSpringExecutor.setIp(ip); xxlJobSpringExecutor.setPort(port); xxlJobSpringExecutor.setAccessToken(accessToken); xxlJobSpringExecutor.setLogPath(logPath); xxlJobSpringExecutor.setLogRetentionDays(logRetentionDays); return xxlJobSpringExecutor; } }這個XxlJobSpringExecutorBean 在初始化時(shí)會完成與調(diào)度中心的連接和注冊。看到控制臺打印出 xxl-job config init.以及后續(xù)的注冊成功日志就說明執(zhí)行器集成成功了。3.3 定義你的第一個任務(wù)處理器JobHandler執(zhí)行器準(zhǔn)備好了接下來要定義它具體能執(zhí)行什么任務(wù)。XXL-JOB 的任務(wù)以“JobHandler”為單位一個 Handler 對應(yīng)一種業(yè)務(wù)邏輯。創(chuàng)建任務(wù)處理器非常簡單只需在方法上添加XxlJob注解。import com.xxl.job.core.handler.annotation.XxlJob; import org.slf4j.Logger; import org.slf4j.LoggerFactory; import org.springframework.stereotype.Component; Component public class SampleXxlJob { private static Logger logger LoggerFactory.getLogger(SampleXxlJob.class); /** * 一個簡單的示例任務(wù) * 1. 在調(diào)度中心新增一個任務(wù)JobHandler 填寫此處注解的值 “demoJobHandler” * 2. 調(diào)度中心觸發(fā)調(diào)度時(shí)會自動調(diào)用此方法 */ XxlJob(demoJobHandler) public void demoJobHandler() throws Exception { logger.info(XXL-JOB, Hello World.); // 這里編寫你的業(yè)務(wù)邏輯比如調(diào)用某個Service // 任務(wù)執(zhí)行結(jié)果默認(rèn)返回 ReturnT.SUCCESS 即表示成功 // 可以通過 ReturnT.FAIL 返回失敗并可在管理后臺查看失敗日志 } /** * 一個帶參數(shù)的任務(wù)示例 * 調(diào)度中心觸發(fā)時(shí)可以將參數(shù)傳遞過來 */ XxlJob(paramJobHandler) public ReturnTString paramJobHandler(String param) throws Exception { logger.info(XXL-JOB, 接收到的參數(shù)是{}, param); if (error.equals(param)) { // 模擬任務(wù)失敗 return new ReturnT(ReturnT.FAIL_CODE, 任務(wù)執(zhí)行失敗參數(shù)為error); } // 模擬一些處理 String result 處理成功參數(shù)是 param; return new ReturnT(result); } }關(guān)鍵點(diǎn)說明XxlJob注解的 value 是JobHandler 的名稱這個名稱必須在整個執(zhí)行器應(yīng)用內(nèi)唯一。它是調(diào)度中心調(diào)用任務(wù)時(shí)的“鑰匙”。方法返回值可以是void或ReturnTString。返回ReturnT.SUCCESS或void默認(rèn)成功表示任務(wù)執(zhí)行成功返回ReturnT.FAIL表示失敗調(diào)度中心會記錄失敗次數(shù)并根據(jù)任務(wù)配置的重試策略決定是否重試。方法可以接收一個String param參數(shù)這個參數(shù)來自于調(diào)度中心任務(wù)配置里的“任務(wù)參數(shù)”字段。你可以用它來動態(tài)控制任務(wù)行為。啟動你的業(yè)務(wù)應(yīng)用如果配置正確在調(diào)度中心管理后臺的“執(zhí)行器管理”頁面應(yīng)該能看到你配置的appname對應(yīng)的執(zhí)行器并且其地址列表里已經(jīng)自動注冊上了你的應(yīng)用地址IP:9999。至此執(zhí)行器就緒任務(wù)處理器就緒就差最后一步在調(diào)度中心創(chuàng)建任務(wù)將它們關(guān)聯(lián)起來。4. 在調(diào)度中心手動創(chuàng)建與管理任務(wù)在能夠用代碼操控一切之前我們先通過管理后臺熟悉一下任務(wù)的核心屬性。登錄調(diào)度中心進(jìn)入“任務(wù)管理”頁面點(diǎn)擊“新增”。一個任務(wù)的核心配置包括執(zhí)行器選擇你剛剛注冊上來的那個執(zhí)行器 AppName。任務(wù)描述給人看的任務(wù)說明。路由策略當(dāng)執(zhí)行器有多個實(shí)例時(shí)調(diào)度請求發(fā)給誰常用“第一個”、“輪詢”、“隨機(jī)”等。Cron任務(wù)的調(diào)度時(shí)間表達(dá)式如0 0 3 * * ?表示每天凌晨3點(diǎn)執(zhí)行。運(yùn)行模式最常用的是 “BEAN”對應(yīng)我們代碼中用XxlJob注解定義的方法。JobHandler填寫你的任務(wù)處理器方法上XxlJob注解里定義的名稱如demoJobHandler。任務(wù)參數(shù)傳遞給任務(wù)處理器的字符串參數(shù)。阻塞處理策略如果上一次調(diào)度還沒執(zhí)行完下一次調(diào)度時(shí)間又到了怎么辦“單機(jī)串行”會排隊(duì)“丟棄后續(xù)調(diào)度”會忽略“覆蓋之前調(diào)度”會終止上一次運(yùn)行慎用。失敗重試次數(shù)任務(wù)執(zhí)行失敗后自動重試的次數(shù)。報(bào)警郵箱任務(wù)失敗后通知誰的郵箱。填寫完畢保存后任務(wù)處于“停止”狀態(tài)。你需要點(diǎn)擊操作欄的“啟動”按鈕調(diào)度中心才會開始按照 Cron 表達(dá)式進(jìn)行調(diào)度。點(diǎn)擊“執(zhí)行一次”可以手動立即觸發(fā)一次用于測試。在“調(diào)度日志”里可以查看每一次觸發(fā)的詳細(xì)記錄、執(zhí)行結(jié)果和耗時(shí)。手動操作雖然直觀但在實(shí)際開發(fā)中我們常常需要更靈活的控制比如根據(jù)系統(tǒng)條件動態(tài)創(chuàng)建臨時(shí)任務(wù)或者在應(yīng)用啟動時(shí)自動初始化一批任務(wù)。這就需要我們通過 XXL-JOB 提供的 API 來編程式地操作任務(wù)。5. 編程式任務(wù)管理深入調(diào)度中心API的調(diào)用細(xì)節(jié)XXL-JOB 調(diào)度中心提供了一套 RESTful 風(fēng)格的 HTTP API允許我們遠(yuǎn)程進(jìn)行任務(wù)的管理操作。官方源碼中的xxl-job-admin模塊其實(shí)就包含了這些 API 的調(diào)用示例XxlJobInfoController我們可以從中學(xué)習(xí)并封裝自己的客戶端。5.1 API調(diào)用原理與認(rèn)證所有對調(diào)度中心的操作本質(zhì)上都是向特定的 URL 發(fā)送 HTTP 請求。這些 API 接口位于調(diào)度中心項(xiàng)目內(nèi)通常以/jobinfo、/jobgroup等為路徑。最重要的安全環(huán)節(jié)是認(rèn)證。調(diào)度中心默認(rèn)開啟了登錄攔截。這意味著你直接調(diào)用/jobinfo/add接口會返回登錄頁面。因此你的調(diào)用程序必須首先模擬登錄獲取到有效的 CookieSession并在后續(xù)的請求中攜帶這個 Cookie。模擬登錄的流程是POST請求到/login接口攜帶表單數(shù)據(jù)userNameadminpassword123456ifRememberon。從響應(yīng)頭中提取Set-Cookie字段的值通常是XXL_JOB_LOGIN_IDENTITYxxxxxxxx。將這個 Cookie 字符串設(shè)置為后續(xù)所有 API 請求的Cookie請求頭。這是一個非常關(guān)鍵且容易被忽略的步驟。很多同學(xué)調(diào)用 API 失敗第一個要檢查的就是登錄狀態(tài)和 Cookie 是否正確傳遞。5.2 封裝一個簡易的Java客戶端為了方便我們可以封裝一個簡單的工具類。這里使用 Spring 的RestTemplate作為 HTTP 客戶端。import org.springframework.http.*; import org.springframework.util.LinkedMultiValueMap; import org.springframework.util.MultiValueMap; import org.springframework.web.client.RestTemplate; import java.util.List; public class XxlJobClient { private String adminAddresses; // 調(diào)度中心地址如 http://localhost:8080/xxl-job-admin private String cookie; // 登錄后的Cookie private RestTemplate restTemplate; public XxlJobClient(String adminAddresses, String username, String password) { this.adminAddresses adminAddresses.endsWith(/) ? adminAddresses : adminAddresses /; this.restTemplate new RestTemplate(); login(username, password); } private void login(String username, String password) { String loginUrl adminAddresses login; HttpHeaders headers new HttpHeaders(); headers.setContentType(MediaType.APPLICATION_FORM_URLENCODED); MultiValueMapString, String params new LinkedMultiValueMap(); params.add(userName, username); params.add(password, password); params.add(ifRemember, on); HttpEntityMultiValueMapString, String request new HttpEntity(params, headers); ResponseEntityString response restTemplate.postForEntity(loginUrl, request, String.class); ListString cookies response.getHeaders().get(HttpHeaders.SET_COOKIE); if (cookies ! null !cookies.isEmpty()) { // 通常我們只需要 XXL_JOB_LOGIN_IDENTITY 這個Cookie for (String c : cookies) { if (c.startsWith(XXL_JOB_LOGIN_IDENTITY)) { this.cookie c.split(;)[0]; // 取分號前的部分 break; } } } if (this.cookie null) { throw new RuntimeException(XXL-JOB Admin 登錄失敗無法獲取Cookie); } } private HttpHeaders createHeadersWithCookie() { HttpHeaders headers new HttpHeaders(); headers.add(HttpHeaders.COOKIE, this.cookie); headers.setContentType(MediaType.APPLICATION_FORM_URLENCODED); return headers; } // 后續(xù)的增刪改查方法都將使用 createHeadersWithCookie() 來構(gòu)建請求頭 }這個客戶端在構(gòu)造時(shí)自動完成登錄并保存了有效的 Cookie。接下來我們基于它來實(shí)現(xiàn)核心的增、刪、啟、停操作。5.3 核心操作一添加任務(wù)Add添加任務(wù)對應(yīng)調(diào)度中心的“新增”操作。我們需要構(gòu)建一個包含所有任務(wù)參數(shù)的請求體。import com.alibaba.fastjson.JSON; import org.springframework.util.LinkedMultiValueMap; import org.springframework.util.MultiValueMap; import java.util.HashMap; import java.util.Map; public class XxlJobClient { // ... 之前的 login 和 createHeadersWithCookie 方法 /** * 添加一個調(diào)度任務(wù) * param jobInfo 任務(wù)信息Map * return 操作結(jié)果 */ public String addJob(MapString, String jobInfo) { String url adminAddresses jobinfo/add; HttpHeaders headers createHeadersWithCookie(); // 注意調(diào)度中心接收的是 form-data 格式 MultiValueMapString, String params new LinkedMultiValueMap(); // 將Map中的所有鍵值對放入MultiValueMap jobInfo.forEach(params::add); HttpEntityMultiValueMapString, String request new HttpEntity(params, headers); ResponseEntityString response restTemplate.postForEntity(url, request, String.class); return response.getBody(); // 返回的通常是JSON包含code和msg } // 使用示例 public void testAddJob() { MapString, String job new HashMap(); job.put(jobGroup, 2); // 執(zhí)行器ID需要在“執(zhí)行器管理”頁面查看對應(yīng)執(zhí)行器的ID job.put(jobDesc, 動態(tài)創(chuàng)建的測試任務(wù)); job.put(author, 開發(fā)者); job.put(scheduleType, CRON); // 調(diào)度類型CRON 或 FIX_RATE job.put(scheduleConf, 0/30 * * * * ?); // Cron表達(dá)式每30秒一次 job.put(glueType, BEAN); // 運(yùn)行模式 job.put(executorHandler, demoJobHandler); // JobHandler名稱 job.put(executorParam, testParam123); // 任務(wù)參數(shù) job.put(executorRouteStrategy, FIRST); // 路由策略 job.put(misfireStrategy, DO_NOTHING); // 調(diào)度過期策略 job.put(executorBlockStrategy, SERIAL_EXECUTION); // 阻塞處理策略 job.put(executorTimeout, 0); // 任務(wù)執(zhí)行超時(shí)時(shí)間(秒)0為不限制 job.put(executorFailRetryCount, 0); // 失敗重試次數(shù) String result addJob(job); System.out.println(添加任務(wù)結(jié)果 result); // 成功結(jié)果示例{code:200, msg:success, content:null} // 失敗結(jié)果示例{code:500, msg:執(zhí)行器不存在, content:null} } }關(guān)鍵參數(shù)解析jobGroup這是執(zhí)行器ID一個數(shù)字。它不是你配置的appname而是調(diào)度中心數(shù)據(jù)庫xxl_job_group表的主鍵 ID。你必須在調(diào)用 API 前通過管理后臺或查詢數(shù)據(jù)庫找到你目標(biāo)執(zhí)行器對應(yīng)的id。這是 API 調(diào)用中最容易出錯的地方之一。scheduleConf當(dāng)scheduleType為CRON時(shí)這里填 Cron 表達(dá)式為FIX_RATE時(shí)這里填一個整數(shù)秒表示固定速率。glueType我們使用代碼定義 Handler所以固定填BEAN。如果是“GLUE”模式在線編輯腳本則填其他類型。5.4 核心操作二啟動與停止任務(wù)Start/Stop啟動和停止任務(wù)實(shí)際上是更新任務(wù)的“狀態(tài)”字段。在 XXL-JOB 中任務(wù)狀態(tài)triggerStatus為 0 表示停止1 表示啟動。public class XxlJobClient { // ... /** * 啟動任務(wù) * param jobId 任務(wù)ID添加任務(wù)成功后返回的ID或從列表查詢得到 * return 操作結(jié)果 */ public String startJob(int jobId) { return updateJobStatus(jobId, 1); // 1 代表啟動 } /** * 停止任務(wù) * param jobId 任務(wù)ID * return 操作結(jié)果 */ public String stopJob(int jobId) { return updateJobStatus(jobId, 0); // 0 代表停止 } private String updateJobStatus(int jobId, int status) { String url adminAddresses jobinfo/start; // 啟動和停止是同一個接口通過參數(shù)控制 HttpHeaders headers createHeadersWithCookie(); MultiValueMapString, String params new LinkedMultiValueMap(); params.add(id, String.valueOf(jobId)); // 接口根據(jù)傳入的 status 值判斷是啟動還是停止 // 但查看源碼發(fā)現(xiàn)/start 接口內(nèi)部是固定將狀態(tài)改為1/stop 接口改為0 // 因此更準(zhǔn)確的做法是調(diào)用不同的端點(diǎn) if (status 1) { url adminAddresses jobinfo/start; } else { url adminAddresses jobinfo/stop; } HttpEntityMultiValueMapString, String request new HttpEntity(params, headers); ResponseEntityString response restTemplate.postForEntity(url, request, String.class); return response.getBody(); } }注意啟動/停止接口需要的是任務(wù)的id。這個id在你調(diào)用addJob成功后的返回值里content字段可能會包含但官方接口返回的content通常是null。更通用的做法是在添加任務(wù)后通過“任務(wù)描述”等字段調(diào)用查詢接口獲取到新創(chuàng)建任務(wù)的完整信息其中就包含id。5.5 核心操作三刪除任務(wù)Remove刪除任務(wù)的 API 相對簡單。public class XxlJobClient { // ... /** * 刪除任務(wù) * param jobId 任務(wù)ID * return 操作結(jié)果 */ public String removeJob(int jobId) { String url adminAddresses jobinfo/remove; HttpHeaders headers createHeadersWithCookie(); MultiValueMapString, String params new LinkedMultiValueMap(); params.add(id, String.valueOf(jobId)); HttpEntityMultiValueMapString, String request new HttpEntity(params, headers); ResponseEntityString response restTemplate.postForEntity(url, request, String.class); return response.getBody(); } }5.6 核心操作四觸發(fā)執(zhí)行一次Trigger除了定時(shí)調(diào)度我們經(jīng)常需要手動觸發(fā)一次任務(wù)執(zhí)行用于測試或應(yīng)急處理。public class XxlJobClient { // ... /** * 觸發(fā)執(zhí)行一次任務(wù) * param jobId 任務(wù)ID * param executorParam 本次觸發(fā)執(zhí)行的參數(shù)可覆蓋任務(wù)默認(rèn)參數(shù) * return 操作結(jié)果 */ public String triggerJob(int jobId, String executorParam) { String url adminAddresses jobinfo/trigger; HttpHeaders headers createHeadersWithCookie(); MultiValueMapString, String params new LinkedMultiValueMap(); params.add(id, String.valueOf(jobId)); params.add(executorParam, executorParam); // 可選參數(shù) HttpEntityMultiValueMapString, String request new HttpEntity(params, headers); ResponseEntityString response restTemplate.postForEntity(url, request, String.class); return response.getBody(); } }這個調(diào)用會立即向執(zhí)行器發(fā)送一次調(diào)度請求并在“調(diào)度日志”中生成一條記錄。executorParam參數(shù)是可選的如果傳遞了會臨時(shí)覆蓋任務(wù)配置中的默認(rèn)參數(shù)。6. 實(shí)戰(zhàn)中的避坑指南與進(jìn)階思考將上述代碼片段組合起來你就能在自己的業(yè)務(wù)系統(tǒng)中通過編程的方式動態(tài)管理 XXL-JOB 的任務(wù)了。但在實(shí)際集成和使用中還有一些細(xì)節(jié)需要特別注意。6.1 Cookie 過期與會話管理通過模擬登錄獲取的 CookieSession是有有效期的。調(diào)度中心默認(rèn)的會話超時(shí)時(shí)間可以在其配置文件中設(shè)置。如果你的客戶端程序是長時(shí)間運(yùn)行的服務(wù)比如一個常駐的后臺管理服務(wù)就需要處理 Cookie 過期的問題。有兩種思路被動刷新在每次 API 調(diào)用后檢查返回值。如果返回的 HTTP 狀態(tài)碼是 302 跳轉(zhuǎn)到登錄頁或者返回的 JSON 中code是特定的未登錄錯誤碼則重新調(diào)用login方法獲取新的 Cookie并重試失敗的請求。主動刷新啟動一個定時(shí)任務(wù)每隔一段時(shí)間比如會話超時(shí)時(shí)間的一半重新登錄一次刷新本地的 Cookie 緩存。6.2 執(zhí)行器IDjobGroup的動態(tài)獲取如前所述jobGroup是數(shù)字 ID 而非appname。硬編碼顯然不可取。更優(yōu)雅的方式是在程序初始化時(shí)通過調(diào)用調(diào)度中心的“執(zhí)行器管理”相關(guān) API如查詢接口根據(jù)appname查詢到對應(yīng)的id并緩存起來。調(diào)度中心提供了/jobgroup/pageList等接口可以查詢執(zhí)行器列表。6.3 錯誤處理與重試機(jī)制網(wǎng)絡(luò)調(diào)用總是不穩(wěn)定的。你的客戶端需要對 HTTP 超時(shí)、連接拒絕、服務(wù)端返回錯誤等情況進(jìn)行妥善處理。對于非冪等的操作如添加任務(wù)重試需要謹(jǐn)慎最好結(jié)合唯一性校驗(yàn)比如通過“任務(wù)描述”先查詢是否已存在。對于啟動、停止、觸發(fā)等操作可以加入簡單的重試邏輯。6.4 任務(wù)配置的版本管理與回滾當(dāng)你通過代碼批量創(chuàng)建或修改了大量任務(wù)后如何管理這些配置一種好的實(shí)踐是將任務(wù)的核心配置如jobDesc,scheduleConf,executorHandler等以配置文件或數(shù)據(jù)庫表的形式進(jìn)行管理。你的客戶端程序在啟動時(shí)讀取這份“期望狀態(tài)”的配置與調(diào)度中心現(xiàn)有的任務(wù)進(jìn)行對比通過查詢 API然后進(jìn)行同步增、刪、改。這類似于 Infrastructure as Code (IaC) 的思想便于版本控制和回滾。6.5 面向生產(chǎn)環(huán)境的考量本文聚焦于單機(jī)部署和代碼集成這是理解和上手 XXL-JOB 的絕佳起點(diǎn)。但一旦邁向生產(chǎn)環(huán)境你需要考慮更多調(diào)度中心高可用部署多個調(diào)度中心實(shí)例通過 Nginx 等負(fù)載均衡器做代理并共享同一個數(shù)據(jù)庫。這樣即使一個調(diào)度中心宕機(jī)其他的可以立刻接管。執(zhí)行器彈性伸縮在 Kubernetes 或云平臺上執(zhí)行器實(shí)例可以動態(tài)擴(kuò)縮容。只要它們配置相同的appname并正確注冊調(diào)度中心就能自動感知。任務(wù)分片廣播XXL-JOB 支持“分片廣播”任務(wù)這對于處理海量數(shù)據(jù)非常有用。一個任務(wù)可以被所有執(zhí)行器實(shí)例同時(shí)執(zhí)行每個實(shí)例通過分片參數(shù)知道自己該處理哪一部分?jǐn)?shù)據(jù)。任務(wù)依賴復(fù)雜的工作流可以通過“子任務(wù)”功能實(shí)現(xiàn)依賴一個任務(wù)成功執(zhí)行后會自動觸發(fā)下一個任務(wù)。從單機(jī)安裝到代碼集成再到思考生產(chǎn)實(shí)踐這條路徑清晰地展示了一個工具如何從一個簡單的需求點(diǎn)逐步演變?yōu)橹侮P(guān)鍵業(yè)務(wù)的基礎(chǔ)設(shè)施。XXL-JOB 的魅力在于它的簡潔與強(qiáng)大并存通過清晰的架構(gòu)設(shè)計(jì)它讓復(fù)雜的分布式任務(wù)調(diào)度變得易于理解和掌控。當(dāng)你親手通過代碼讓一個任務(wù)在遠(yuǎn)程服務(wù)器上按時(shí)跑起來時(shí)那種對系統(tǒng)掌控感的確立正是后端工程師成長的樂趣所在。