微信機(jī)器人報警實戰(zhàn)：自定義 JobAlarm 實現(xiàn)與避坑指南)
1. 任務(wù)調(diào)度報警的痛點(diǎn)與破局思路做過分布式任務(wù)調(diào)度的同行大概都有過這種體驗凌晨兩點(diǎn)某個核心對賬任務(wù)掛了XXL-JOB 的控制臺安安靜靜直到第二天業(yè)務(wù)方打電話來問“昨天的數(shù)據(jù)怎么沒跑出來”你才發(fā)現(xiàn)調(diào)度失敗了一整晚。XXL-JOB 自帶的郵件報警在真實生產(chǎn)環(huán)境里其實挺雞肋的——郵件容易被淹沒在各類通知里而且很多人根本沒有隨時查郵件的習(xí)慣。短信報警又要額外對接運(yùn)營商通道成本高、配置繁瑣。企業(yè)微信機(jī)器人報警就是在這個場景下最順手的一個方案。它的本質(zhì)是把 XXL-JOB 的調(diào)度失敗事件通過企業(yè)微信群的 Webhook 地址以 Markdown 消息的形式推送到運(yùn)維群或者業(yè)務(wù)群。群里的每個人都能第一時間看到還能直接 相關(guān)責(zé)任人。這篇文章我會把整個實現(xiàn)過程拆開講透包括 XXL-JOB 報警機(jī)制的底層原理、企業(yè)微信機(jī)器人的消息格式約束、自定義報警器的代碼實現(xiàn)、以及我在實際接入過程中踩過的那些坑。適合閱讀這篇內(nèi)容的讀者有三類一是正在用 XXL-JOB 做任務(wù)調(diào)度、想升級報警能力的后端開發(fā)二是負(fù)責(zé)運(yùn)維告警體系、需要把調(diào)度告警統(tǒng)一接入企業(yè)微信的運(yùn)維同學(xué)三是對 Java SPI 擴(kuò)展機(jī)制感興趣、想通過一個真實案例理解框架擴(kuò)展點(diǎn)的開發(fā)者。不管你是剛接觸 XXL-JOB 還是已經(jīng)用了兩三年下面這些細(xì)節(jié)應(yīng)該都能給你一些參考。XXL-JOB 的報警能力本身是開放的它預(yù)留了 JobAlarm 接口默認(rèn)提供了郵件報警的實現(xiàn)。很多人不知道這一點(diǎn)以為只能用郵件其實只要實現(xiàn)這個接口并注冊成 Spring Bean就能接入任意報警渠道。企業(yè)微信機(jī)器人恰好提供了一個極簡的 HTTP Webhook 接口不需要申請應(yīng)用、不需要配置回調(diào)地址、不需要處理加解密創(chuàng)建一個群機(jī)器人就能拿到一個 URL往上面 POST JSON 就能發(fā)消息。這兩者結(jié)合起來整個接入成本非常低。但低成本不代表沒有細(xì)節(jié)。企業(yè)微信機(jī)器人的消息有格式要求XXL-JOB 的報警回調(diào)有觸發(fā)時機(jī)的限制多實例部署時還有重復(fù)報警的問題。這些如果不提前想清楚上線之后就會各種翻車。接下來我按照“整體設(shè)計思路 → 核心細(xì)節(jié)解析 → 完整實操過程 → 常見問題排查”的順序把整個方案講清楚。2. 整體設(shè)計與核心思路拆解2.1 為什么選企業(yè)微信機(jī)器人而不是其他渠道報警渠道的選擇本質(zhì)上是在“觸達(dá)率”“接入成本”“信息豐富度”三個維度之間做權(quán)衡。郵件觸達(dá)率低但接入成本幾乎為零短信觸達(dá)率高但需要付費(fèi)通道且內(nèi)容長度受限釘釘/企業(yè)微信/飛書機(jī)器人則處于中間位置——觸達(dá)率取決于群消息的活躍度接入成本很低消息支持 Markdown 格式所以信息豐富度也不錯。企業(yè)微信機(jī)器人相比釘釘機(jī)器人有一個實際使用中的優(yōu)勢很多公司的內(nèi)部溝通主陣地就是企業(yè)微信運(yùn)維群、項目群、值班群都在上面報警消息直接推到這些群里不需要額外讓團(tuán)隊成員再裝一個 App。而且企業(yè)微信機(jī)器人的 Webhook 接口非常穩(wěn)定我用了兩年多沒有遇到過接口本身不可用的情況。從技術(shù)實現(xiàn)角度看企業(yè)微信機(jī)器人只需要一個 HTTP POST 請求請求體是 JSON支持 text 和 markdown 兩種消息類型。markdown 類型支持標(biāo)題、加粗、引用、鏈接、字體顏色等基礎(chǔ)排版對于報警消息來說完全夠用。唯一需要注意的是 markdown 類型不支持 某個人只有 text 類型才支持 mentioned_list 參數(shù)來 人。這個限制后面在消息設(shè)計時會專門處理。2.2 XXL-JOB 報警機(jī)制的底層邏輯XXL-JOB 的報警觸發(fā)鏈路是這樣的調(diào)度中心xxl-job-admin在執(zhí)行器任務(wù)調(diào)度失敗后會調(diào)用 JobFailMonitorHelper 這個失敗監(jiān)控線程。這個線程每隔一段時間掃描一次數(shù)據(jù)庫中的失敗日志記錄對于“報警狀態(tài)為未報警”的記錄遍歷所有注冊的 JobAlarm 實現(xiàn)類逐個調(diào)用 alarm() 方法。如果任意一個報警器返回 true就把該條日志的報警狀態(tài)標(biāo)記為已報警后續(xù)不再重復(fù)報警。這里有幾個關(guān)鍵點(diǎn)需要理解清楚。第一報警是在調(diào)度中心側(cè)觸發(fā)的不是在執(zhí)行器側(cè)所以自定義報警器要放在調(diào)度中心項目里而不是執(zhí)行器項目里。第二報警是異步的失敗監(jiān)控線程獨(dú)立運(yùn)行不會阻塞正常的調(diào)度流程。第三JobAlarm 是一個 SPI 接口XXL-JOB 通過 Spring 的依賴注入把所有實現(xiàn)類收集到一個 List 中遍歷調(diào)用。這意味著你只需要寫一個類實現(xiàn) JobAlarm 接口加上 Component 注解它就會自動生效不需要修改任何框架代碼。JobAlarm 接口的定義非常簡潔只有一個方法public interface JobAlarm { public boolean alarm(XxlJobInfo info, XxlJobLog jobLog); }XxlJobInfo 包含了任務(wù)的基本信息任務(wù) ID、任務(wù)描述、負(fù)責(zé)人、報警郵件等XxlJobLog 包含了本次執(zhí)行的日志信息執(zhí)行器地址、執(zhí)行結(jié)果、執(zhí)行備注等。這兩個對象里的信息足夠我們拼裝一條完整的報警消息。2.3 多實例部署下的報警去重問題如果你的調(diào)度中心是集群部署的生產(chǎn)環(huán)境通常會部署兩個節(jié)點(diǎn)做高可用那么失敗監(jiān)控線程會在每個節(jié)點(diǎn)上各跑一份。這就帶來一個潛在問題同一條失敗日志可能被兩個節(jié)點(diǎn)同時掃描到導(dǎo)致重復(fù)報警。XXL-JOB 本身對這個問題的處理方式是在更新報警狀態(tài)時使用樂觀鎖或者條件更新只有成功將“報警狀態(tài)”從未報警改為已報警的那個節(jié)點(diǎn)才會真正發(fā)送報警。但實際實現(xiàn)中不同版本的 XXL-JOB 處理方式略有差異。比較穩(wěn)妥的做法是在自定義報警器里也做一層冪等控制比如用 Redis 做一個短期的去重 keykey 的過期時間設(shè)置為報警間隔的兩倍左右。這樣即使框架層面有并發(fā)窗口業(yè)務(wù)層面也能兜住。不過話說回來對于報警消息來說偶爾重復(fù)一條并不是什么致命問題反而比漏報要好。所以如果你的環(huán)境里重復(fù)報警并不頻繁也可以不做額外去重接受這個 trade-off。我在實際項目中觀察下來XXL-JOB 2.3.x 及以上版本在集群模式下的報警去重做得已經(jīng)比較好了重復(fù)報警的概率很低。3. 核心細(xì)節(jié)解析與實操要點(diǎn)3.1 企業(yè)微信機(jī)器人 Webhook 的獲取與限制創(chuàng)建企業(yè)微信機(jī)器人的操作路徑是進(jìn)入一個群聊 → 點(diǎn)擊右上角 → 群機(jī)器人 → 添加機(jī)器人 → 選擇“自定義” → 設(shè)置機(jī)器人名稱和頭像 → 獲取 Webhook 地址。這個地址的格式是https://qyapi.weixin.qq.com/cgi-bin/webhook/send?keyxxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx拿到這個 URL 之后往上面 POST 一個 JSON 就能發(fā)消息。但有幾個限制必須提前知道頻率限制每個機(jī)器人每分鐘最多發(fā)送 20 條消息。超過之后會被限流返回錯誤碼 45009。對于任務(wù)調(diào)度報警來說如果短時間內(nèi)大量任務(wù)同時失敗比如數(shù)據(jù)庫掛了導(dǎo)致所有依賴數(shù)據(jù)庫的任務(wù)全部失敗很容易觸發(fā)這個限制。后面我會講怎么處理這種情況。消息長度限制markdown 類型的消息內(nèi)容最長 4096 字節(jié)超出部分會被截斷。所以報警消息里不要塞太多內(nèi)容關(guān)鍵信息點(diǎn)到為止。markdown 語法限制企業(yè)微信的 markdown 不是標(biāo)準(zhǔn) markdown支持的語法比較有限。支持標(biāo)題# 到 ######、加粗**、引用、字體顏色、鏈接、行內(nèi)代碼。不支持表格、不支持圖片圖片需要單獨(dú)用 image 類型消息發(fā)送、不支持有序列表的自動編號。 人限制markdown 類型不支持 成員只有 text 類型支持 mentioned_list 和 mentioned_mobile_list。如果報警需要 到具體負(fù)責(zé)人要么用 text 類型要么在 markdown 里手動寫上負(fù)責(zé)人的名字但沒有 的提醒效果。這些限制看起來多但對于報警場景來說其實夠用。報警消息的核心是“哪個任務(wù)失敗了、什么時候失敗的、失敗原因是什么、誰該去看”這些信息用 markdown 排版完全能表達(dá)清楚。3.2 報警消息的內(nèi)容設(shè)計一條好的報警消息應(yīng)該讓接收者在 3 秒內(nèi)判斷出“這事跟我有沒有關(guān)系、嚴(yán)不嚴(yán)重、要不要馬上處理”。基于這個原則我設(shè)計的報警消息模板包含以下字段字段說明是否必填任務(wù) IDXXL-JOB 中的任務(wù)主鍵是任務(wù)描述任務(wù)的業(yè)務(wù)含義是負(fù)責(zé)人任務(wù)的負(fù)責(zé)人是調(diào)度時間本次觸發(fā)調(diào)度的時間是執(zhí)行器地址實際執(zhí)行任務(wù)的節(jié)點(diǎn)是失敗原因執(zhí)行返回的備注信息是報警時間消息發(fā)送的時間否消息的 markdown 格式大概長這樣## 任務(wù)調(diào)度失敗報警 **任務(wù)ID** 1024 **任務(wù)描述** 每日訂單對賬 **負(fù)責(zé)人** 張三 **調(diào)度時間** 2024-01-15 02:00:00 **執(zhí)行器地址** http://192.168.1.100:9999/ **失敗原因** font colorwarningjava.lang.NullPointerException: .../font **報警時間** 2024-01-15 02:00:15用引用塊把信息包起來視覺上比較緊湊。失敗原因用 warning 顏色標(biāo)紅一眼就能看到。標(biāo)題用 ## 級別在企業(yè)微信里顯示為較大的字體起到醒目的作用。這里有個細(xì)節(jié)失敗原因可能非常長比如完整的異常堆棧直接塞進(jìn)消息里會超過長度限制。我的做法是截取前 200 個字符后面加省略號完整信息讓用戶去 XXL-JOB 控制臺查看。截取的時候要注意按字符而不是按字節(jié)截取避免把中文截成亂碼。3.3 報警器的代碼結(jié)構(gòu)設(shè)計自定義報警器的代碼結(jié)構(gòu)其實很簡單核心就是一個類實現(xiàn) JobAlarm 接口。但為了代碼的可維護(hù)性和可測試性我建議拆成三層報警器層實現(xiàn) JobAlarm 接口負(fù)責(zé)從 XxlJobInfo 和 XxlJobLog 中提取信息組裝成消息內(nèi)容調(diào)用發(fā)送器。消息組裝層負(fù)責(zé)把結(jié)構(gòu)化數(shù)據(jù)渲染成 markdown 文本方便后續(xù)調(diào)整消息模板。HTTP 發(fā)送層負(fù)責(zé)實際的 HTTP POST 請求處理超時、重試、異常。這樣拆的好處是如果以后要換一個報警渠道比如換成飛書機(jī)器人只需要改發(fā)送層消息組裝層可以復(fù)用。如果以后要調(diào)整消息格式只需要改組裝層不影響其他部分。在 Spring 環(huán)境下這個報警器類加上 Component 注解就會被自動掃描到。XXL-JOB 的 JobAlarm 收集邏輯是通過 Autowired 注入一個 List Spring 會自動把所有實現(xiàn)類注入進(jìn)來。所以不需要額外配置加個注解就行。但有一個坑需要注意如果你的調(diào)度中心項目里同時存在多個 JobAlarm 實現(xiàn)比如默認(rèn)的 EmailJobAlarm 加上你的自定義報警器那么每次報警會同時觸發(fā)所有報警器。如果你只想用企業(yè)微信報警、不想發(fā)郵件需要把 EmailJobAlarm 的配置關(guān)掉在 application.properties 里設(shè)置 xxl.job.alarm.email 相關(guān)配置為空或者不配置。不過實際上同時保留郵件和企業(yè)微信報警也不是壞事多一個渠道多一份保障。4. 完整實操過程與核心環(huán)節(jié)實現(xiàn)4.1 環(huán)境準(zhǔn)備與依賴確認(rèn)在開始寫代碼之前先確認(rèn)幾個環(huán)境條件XXL-JOB 版本建議 2.3.0 及以上這些版本的 JobAlarm 接口比較穩(wěn)定失敗監(jiān)控線程的邏輯也比較完善。我實測過 2.3.1 和 2.4.0都能正常工作。調(diào)度中心項目你需要有 xxl-job-admin 的源碼因為自定義報警器要加在這個項目里。如果你是用官方編譯好的 jar 包部署的需要重新拉源碼編譯。HTTP 客戶端調(diào)度中心項目本身依賴了 Spring Boot所以可以直接用 RestTemplate 或者 HttpClient。我習(xí)慣用 Java 11 自帶的 HttpClient不需要額外引入依賴。如果你用的是 Java 8可以用 OkHttp 或者 Apache HttpClient。JSON 庫XXL-JOB 本身依賴了 Gsoncom.google.gson可以直接用來組裝 JSON不需要額外引入 Jackson 或 Fastjson。確認(rèn)好這些之后在 xxl-job-admin 項目的 alarm 包下新建一個類比如叫 WeChatRobotJobAlarm。4.2 核心代碼實現(xiàn)先看消息組裝的部分。我定義了一個簡單的消息模板方法private String buildMarkdownMessage(XxlJobInfo info, XxlJobLog jobLog) { StringBuilder sb new StringBuilder(); sb.append(## 任務(wù)調(diào)度失敗報警\n); sb.append( **任務(wù)ID** ).append(info.getId()).append(\n); sb.append( **任務(wù)描述** ).append(info.getJobDesc()).append(\n); sb.append( **負(fù)責(zé)人** ).append(info.getAuthor()).append(\n); sb.append( **調(diào)度時間** ).append(DateUtil.formatDateTime(jobLog.getTriggerTime())).append(\n); sb.append( **執(zhí)行器地址** ).append(jobLog.getExecutorAddress()).append(\n); String failMsg jobLog.getTriggerMsg(); if (failMsg ! null failMsg.length() 200) { failMsg failMsg.substring(0, 200) ...; } sb.append( **失敗原因** font color\warning\).append(failMsg).append(/font\n); sb.append( **報警時間** ).append(DateUtil.formatDateTime(new Date())).append(\n); return sb.toString(); }這里用了 XXL-JOB 自帶的 DateUtil 工具類來格式化時間避免自己寫 SimpleDateFormat 的線程安全問題。失敗原因做了 200 字符的截斷處理防止消息過長。然后是 HTTP 發(fā)送的部分private boolean sendToWeChatRobot(String content) { try { MapString, Object body new HashMap(); body.put(msgtype, markdown); MapString, String markdown new HashMap(); markdown.put(content, content); body.put(markdown, markdown); String json new Gson().toJson(body); HttpClient client HttpClient.newHttpClient(); HttpRequest request HttpRequest.newBuilder() .uri(URI.create(webhookUrl)) .header(Content-Type, application/json) .POST(HttpRequest.BodyPublishers.ofString(json, StandardCharsets.UTF_8)) .timeout(Duration.ofSeconds(5)) .build(); HttpResponseString response client.send(request, HttpResponse.BodyHandlers.ofString()); if (response.statusCode() 200) { JsonObject result JsonParser.parseString(response.body()).getAsJsonObject(); int errcode result.get(errcode).getAsInt(); if (errcode 0) { return true; } logger.warn(企業(yè)微信機(jī)器人返回錯誤errcode{}, errmsg{}, errcode, result.get(errmsg).getAsString()); } } catch (Exception e) { logger.error(發(fā)送企業(yè)微信報警失敗, e); } return false; }這段代碼有幾個細(xì)節(jié)值得說明。超時時間設(shè)置為 5 秒是因為報警消息不需要等待太久如果企業(yè)微信接口 5 秒還沒響應(yīng)說明網(wǎng)絡(luò)有問題重試也沒有太大意義。返回結(jié)果里要檢查 errcode企業(yè)微信的接口即使 HTTP 狀態(tài)碼是 200也可能在 body 里返回業(yè)務(wù)錯誤碼。常見的錯誤碼有 45009頻率超限、93000機(jī)器人被移出群聊等。最后是 JobAlarm 接口的實現(xiàn)Component public class WeChatRobotJobAlarm implements JobAlarm { private static final Logger logger LoggerFactory.getLogger(WeChatRobotJobAlarm.class); Value(${xxl.job.alarm.wechat.webhook:}) private String webhookUrl; Override public boolean alarm(XxlJobInfo info, XxlJobLog jobLog) { if (webhookUrl null || webhookUrl.trim().isEmpty()) { logger.debug(未配置企業(yè)微信機(jī)器人 Webhook跳過報警); return false; } String content buildMarkdownMessage(info, jobLog); return sendToWeChatRobot(content); } }Webhook 地址通過配置文件注入這樣不同環(huán)境可以用不同的機(jī)器人開發(fā)環(huán)境推到開發(fā)群生產(chǎn)環(huán)境推到運(yùn)維群。如果沒配置 Webhook直接返回 false不影響其他報警器。4.3 配置文件與部署驗證在 application.properties 里加上一行配置xxl.job.alarm.wechat.webhookhttps://qyapi.weixin.qq.com/cgi-bin/webhook/send?key你的key然后重新編譯打包 xxl-job-admin部署到調(diào)度中心。驗證的方式很簡單在 XXL-JOB 控制臺里手動觸發(fā)一個會失敗的任務(wù)比如把一個執(zhí)行器的地址改錯或者讓任務(wù)拋異常觀察企業(yè)微信群里是否收到報警消息。如果沒收到先看調(diào)度中心的日志搜索“企業(yè)微信”相關(guān)的日志輸出。常見的問題包括Webhook 地址配錯了、網(wǎng)絡(luò)不通調(diào)度中心所在服務(wù)器無法訪問企業(yè)微信接口、消息格式不對被企業(yè)微信拒絕。日志里會打印具體的錯誤信息按圖索驥基本都能解決。4.4 頻率限制的應(yīng)對策略前面提到企業(yè)微信機(jī)器人每分鐘最多 20 條消息。如果短時間內(nèi)大量任務(wù)失敗比如數(shù)據(jù)庫連接池耗盡導(dǎo)致所有任務(wù)全部失敗可能會瞬間產(chǎn)生幾十條報警觸發(fā)限流。我的應(yīng)對策略是在發(fā)送層加一個簡單的令牌桶或者計數(shù)器。用 Guava 的 RateLimiter 就可以private final RateLimiter rateLimiter RateLimiter.create(0.3); // 每秒0.3個即每分鐘18個 // 在發(fā)送前調(diào)用 if (!rateLimiter.tryAcquire(1, TimeUnit.SECONDS)) { logger.warn(企業(yè)微信報警頻率超限本條報警被丟棄); return false; }這樣最多每秒發(fā) 0.3 條每分鐘 18 條留一點(diǎn)余量給其他用途。被限流的報警消息會被丟棄但日志里有記錄事后可以追溯。如果你覺得丟棄不可接受也可以改成把消息攢起來批量發(fā)送但實現(xiàn)復(fù)雜度會高不少。對于報警場景來說我傾向于簡單限流加日志記錄因為大量任務(wù)同時失敗時看一條報警和看十條報警的信息量差不多關(guān)鍵是知道“出大事了”。5. 常見問題與排查技巧實錄5.1 報警不觸發(fā)或觸發(fā)異常這是最常見的問題類型。我整理了一個排查速查表現(xiàn)象可能原因排查方法任務(wù)失敗但完全沒報警報警器沒被 Spring 掃描到檢查類上是否有 Component包路徑是否在掃描范圍內(nèi)任務(wù)失敗但完全沒報警Webhook 未配置或配置為空檢查 application.properties 中的配置項任務(wù)失敗但完全沒報警失敗監(jiān)控線程未啟動檢查調(diào)度中心啟動日志中是否有 JobFailMonitorHelper 相關(guān)日志報警消息發(fā)送失敗網(wǎng)絡(luò)不通在調(diào)度中心服務(wù)器上 curl 一下 Webhook 地址報警消息發(fā)送失敗消息格式錯誤查看企業(yè)微信返回的 errcode 和 errmsg報警消息發(fā)送失敗頻率超限查看 errcode 是否為 45009重復(fù)報警集群模式下多節(jié)點(diǎn)同時掃描檢查 XXL-JOB 版本考慮加 Redis 去重報警消息內(nèi)容為空XxlJobLog 字段為 null檢查 jobLog.getTriggerMsg() 是否為空加空值判斷其中“報警器沒被掃描到”是最容易犯的錯誤。很多人把報警器類寫在了執(zhí)行器項目里或者寫在了調(diào)度中心項目但包路徑不在 SpringBootApplication 的掃描范圍內(nèi)。XXL-JOB 的調(diào)度中心啟動類在 com.xxl.job.admin 包下所以你的報警器類要么放在這個包及其子包下要么在啟動類上手動加 ComponentScan。5.2 消息內(nèi)容顯示異常企業(yè)微信的 markdown 渲染和標(biāo)準(zhǔn) markdown 有一些差異我踩過的坑包括換行問題企業(yè)微信 markdown 里單個 \n 不會換行需要兩個 \n 或者用引用塊。我一開始用 \n 拼接結(jié)果所有內(nèi)容擠在一行后來改成每個字段后面加 \n并且用引用塊包裹顯示就正常了。字體顏色只支持 info綠色、warning橙紅色、comment灰色三種顏色寫其他顏色值不會生效會顯示為默認(rèn)顏色。特殊字符任務(wù)描述里如果包含 等字符可能會破壞 markdown 結(jié)構(gòu)。建議在拼接前做一次 HTML 轉(zhuǎn)義或者至少把 和 替換掉。超長內(nèi)容前面說過 4096 字節(jié)限制但實際測試下來超過 2000 字節(jié)左右企業(yè)微信客戶端就可能顯示不全。所以消息內(nèi)容盡量精簡。5.3 集群環(huán)境下的重復(fù)報警如果你的調(diào)度中心部署了兩個節(jié)點(diǎn)理論上同一條失敗日志可能被兩個節(jié)點(diǎn)同時處理。XXL-JOB 在 JobFailMonitorHelper 里通過數(shù)據(jù)庫的樂觀鎖來保證只有一條記錄被更新成功但不同版本的實現(xiàn)細(xì)節(jié)有差異。我在 2.3.1 版本上實測集群模式下重復(fù)報警的概率大概在 5% 左右不算高但確實存在。如果你對重復(fù)報警零容忍可以加一層 Redis 去重String dedupKey xxl:alarm:dedup: jobLog.getId(); Boolean success redisTemplate.opsForValue().setIfAbsent(dedupKey, 1, 5, TimeUnit.MINUTES); if (Boolean.FALSE.equals(success)) { logger.debug(報警已發(fā)送過跳過重復(fù)報警logId{}, jobLog.getId()); return true; }用 jobLog 的主鍵作為去重 key5 分鐘內(nèi)不重復(fù)發(fā)送。這樣即使框架層面有并發(fā)窗口業(yè)務(wù)層面也能兜住。返回 true 是為了告訴框架“報警已處理”避免框架反復(fù)重試。5.4 報警消息的負(fù)責(zé)人 提醒前面提到 markdown 類型不支持 人。如果你確實需要 到具體負(fù)責(zé)人有兩個方案方案一改用 text 類型消息用 mentioned_mobile_list 參數(shù) 負(fù)責(zé)人的手機(jī)號。但 text 類型不支持 markdown 排版消息看起來比較樸素。方案二在 markdown 消息里手動寫上負(fù)責(zé)人的名字雖然沒有 的強(qiáng)提醒效果但群里的人看到自己的名字自然會關(guān)注。我傾向于方案二因為報警消息的排版清晰比 提醒更重要而且企業(yè)微信群里 太多也容易引起反感。如果一定要 可以發(fā)兩條消息一條 markdown 類型的詳細(xì)報警一條 text 類型的 提醒。但這樣會消耗兩倍的頻率配額需要權(quán)衡。5.5 報警消息的靜默與降噪上線一段時間后你可能會發(fā)現(xiàn)某些任務(wù)的報警特別頻繁比如一個每分鐘執(zhí)行一次的任務(wù)偶爾失敗一次就報警一天下來幾十條消息群里的人都麻木了。這時候需要做報警降噪。我的做法是在報警器里加一個簡單的靜默邏輯同一個任務(wù)在 N 分鐘內(nèi)只報警一次。用 Redis 記錄每個任務(wù)的上次報警時間如果距離上次報警不足 N 分鐘就跳過。N 可以根據(jù)任務(wù)的執(zhí)行頻率來設(shè)置比如每分鐘執(zhí)行的任務(wù)設(shè)置 10 分鐘靜默每天執(zhí)行的任務(wù)設(shè)置 0 分鐘每次都報。String silenceKey xxl:alarm:silence: info.getId(); Boolean canAlarm redisTemplate.opsForValue().setIfAbsent(silenceKey, 1, silenceMinutes, TimeUnit.MINUTES); if (Boolean.FALSE.equals(canAlarm)) { logger.debug(任務(wù){(diào)}處于靜默期跳過報警, info.getId()); return true; }這個邏輯和前面的去重邏輯可以合并用同一個 Redis key 同時實現(xiàn)去重和靜默。靜默時間可以通過任務(wù)的執(zhí)行頻率動態(tài)計算也可以做成可配置的。5.6 測試環(huán)境與生產(chǎn)環(huán)境的隔離開發(fā)測試環(huán)境的任務(wù)失敗頻率通常比生產(chǎn)環(huán)境高很多如果測試環(huán)境的報警也推到生產(chǎn)運(yùn)維群會造成大量噪音。我的做法是通過配置文件區(qū)分不同環(huán)境的 Webhook 地址開發(fā)環(huán)境推送到開發(fā)群測試環(huán)境推送到測試群生產(chǎn)環(huán)境推送到運(yùn)維群。Spring Boot 的多環(huán)境配置application-dev.properties、application-prod.properties天然支持這一點(diǎn)。另外測試環(huán)境的報警可以設(shè)置更長的靜默時間或者干脆只在特定時間段比如工作時間發(fā)送報警避免半夜吵醒人。這些都可以通過配置項來控制不需要改代碼。6. 一些實操后的個人體會這套方案我在三個不同的項目里落地過從最初的簡單版本迭代到現(xiàn)在帶限流、去重、靜默的完整版本前后大概改了五六次。最大的體會是報警系統(tǒng)的核心不是“發(fā)出去”而是“發(fā)得對”。發(fā)得太多大家會麻木發(fā)得太少又會漏掉關(guān)鍵問題。找到這個平衡點(diǎn)需要根據(jù)團(tuán)隊的實際情況不斷調(diào)整。另外一個容易被忽視的點(diǎn)是報警消息的可操作性。一條好的報警消息應(yīng)該讓接收者能直接點(diǎn)擊鏈接跳到 XXL-JOB 控制臺查看詳情而不是自己去翻控制臺找任務(wù)。企業(yè)微信 markdown 支持鏈接語法可以在消息里加上控制臺的任務(wù)詳情頁鏈接點(diǎn)擊直接跳轉(zhuǎn)。這個小小的改進(jìn)能顯著提升處理效率。最后分享一個小技巧企業(yè)微信機(jī)器人的 Webhook 地址里那個 key 是敏感信息不要直接硬編碼在代碼里提交到代碼倉庫。用環(huán)境變量或者配置中心來管理避免泄露后被惡意利用。雖然機(jī)器人只能發(fā)消息不能讀消息但被人惡意刷消息也是挺煩的。 XXL-JOB 企業(yè)微信機(jī)器人報警實戰(zhàn)：自定義 JobAlarm 實現(xiàn)與避坑指南
1. 任務(wù)調(diào)度報警的痛點(diǎn)與破局思路做過分布式任務(wù)調(diào)度的同行大概都有過這種體驗凌晨兩點(diǎn)某個核心對賬任務(wù)掛了XXL-JOB 的控制臺安安靜靜直到第二天業(yè)務(wù)方打電話來問“昨天的數(shù)據(jù)怎么沒跑出來”你才發(fā)現(xiàn)調(diào)度失敗了一整晚。XXL-JOB 自帶的郵件報警在真實生產(chǎn)環(huán)境里其實挺雞肋的——郵件容易被淹沒在各類通知里而且很多人根本沒有隨時查郵件的習(xí)慣。短信報警又要額外對接運(yùn)營商通道成本高、配置繁瑣。企業(yè)微信機(jī)器人報警就是在這個場景下最順手的一個方案。它的本質(zhì)是把 XXL-JOB 的調(diào)度失敗事件通過企業(yè)微信群的 Webhook 地址以 Markdown 消息的形式推送到運(yùn)維群或者業(yè)務(wù)群。群里的每個人都能第一時間看到還能直接 相關(guān)責(zé)任人。這篇文章我會把整個實現(xiàn)過程拆開講透包括 XXL-JOB 報警機(jī)制的底層原理、企業(yè)微信機(jī)器人的消息格式約束、自定義報警器的代碼實現(xiàn)、以及我在實際接入過程中踩過的那些坑。適合閱讀這篇內(nèi)容的讀者有三類一是正在用 XXL-JOB 做任務(wù)調(diào)度、想升級報警能力的后端開發(fā)二是負(fù)責(zé)運(yùn)維告警體系、需要把調(diào)度告警統(tǒng)一接入企業(yè)微信的運(yùn)維同學(xué)三是對 Java SPI 擴(kuò)展機(jī)制感興趣、想通過一個真實案例理解框架擴(kuò)展點(diǎn)的開發(fā)者。不管你是剛接觸 XXL-JOB 還是已經(jīng)用了兩三年下面這些細(xì)節(jié)應(yīng)該都能給你一些參考。XXL-JOB 的報警能力本身是開放的它預(yù)留了 JobAlarm 接口默認(rèn)提供了郵件報警的實現(xiàn)。很多人不知道這一點(diǎn)以為只能用郵件其實只要實現(xiàn)這個接口并注冊成 Spring Bean就能接入任意報警渠道。企業(yè)微信機(jī)器人恰好提供了一個極簡的 HTTP Webhook 接口不需要申請應(yīng)用、不需要配置回調(diào)地址、不需要處理加解密創(chuàng)建一個群機(jī)器人就能拿到一個 URL往上面 POST JSON 就能發(fā)消息。這兩者結(jié)合起來整個接入成本非常低。但低成本不代表沒有細(xì)節(jié)。企業(yè)微信機(jī)器人的消息有格式要求XXL-JOB 的報警回調(diào)有觸發(fā)時機(jī)的限制多實例部署時還有重復(fù)報警的問題。這些如果不提前想清楚上線之后就會各種翻車。接下來我按照“整體設(shè)計思路 → 核心細(xì)節(jié)解析 → 完整實操過程 → 常見問題排查”的順序把整個方案講清楚。2. 整體設(shè)計與核心思路拆解2.1 為什么選企業(yè)微信機(jī)器人而不是其他渠道報警渠道的選擇本質(zhì)上是在“觸達(dá)率”“接入成本”“信息豐富度”三個維度之間做權(quán)衡。郵件觸達(dá)率低但接入成本幾乎為零短信觸達(dá)率高但需要付費(fèi)通道且內(nèi)容長度受限釘釘/企業(yè)微信/飛書機(jī)器人則處于中間位置——觸達(dá)率取決于群消息的活躍度接入成本很低消息支持 Markdown 格式所以信息豐富度也不錯。企業(yè)微信機(jī)器人相比釘釘機(jī)器人有一個實際使用中的優(yōu)勢很多公司的內(nèi)部溝通主陣地就是企業(yè)微信運(yùn)維群、項目群、值班群都在上面報警消息直接推到這些群里不需要額外讓團(tuán)隊成員再裝一個 App。而且企業(yè)微信機(jī)器人的 Webhook 接口非常穩(wěn)定我用了兩年多沒有遇到過接口本身不可用的情況。從技術(shù)實現(xiàn)角度看企業(yè)微信機(jī)器人只需要一個 HTTP POST 請求請求體是 JSON支持 text 和 markdown 兩種消息類型。markdown 類型支持標(biāo)題、加粗、引用、鏈接、字體顏色等基礎(chǔ)排版對于報警消息來說完全夠用。唯一需要注意的是 markdown 類型不支持 某個人只有 text 類型才支持 mentioned_list 參數(shù)來 人。這個限制后面在消息設(shè)計時會專門處理。2.2 XXL-JOB 報警機(jī)制的底層邏輯XXL-JOB 的報警觸發(fā)鏈路是這樣的調(diào)度中心xxl-job-admin在執(zhí)行器任務(wù)調(diào)度失敗后會調(diào)用 JobFailMonitorHelper 這個失敗監(jiān)控線程。這個線程每隔一段時間掃描一次數(shù)據(jù)庫中的失敗日志記錄對于“報警狀態(tài)為未報警”的記錄遍歷所有注冊的 JobAlarm 實現(xiàn)類逐個調(diào)用 alarm() 方法。如果任意一個報警器返回 true就把該條日志的報警狀態(tài)標(biāo)記為已報警后續(xù)不再重復(fù)報警。這里有幾個關(guān)鍵點(diǎn)需要理解清楚。第一報警是在調(diào)度中心側(cè)觸發(fā)的不是在執(zhí)行器側(cè)所以自定義報警器要放在調(diào)度中心項目里而不是執(zhí)行器項目里。第二報警是異步的失敗監(jiān)控線程獨(dú)立運(yùn)行不會阻塞正常的調(diào)度流程。第三JobAlarm 是一個 SPI 接口XXL-JOB 通過 Spring 的依賴注入把所有實現(xiàn)類收集到一個 List 中遍歷調(diào)用。這意味著你只需要寫一個類實現(xiàn) JobAlarm 接口加上 Component 注解它就會自動生效不需要修改任何框架代碼。JobAlarm 接口的定義非常簡潔只有一個方法public interface JobAlarm { public boolean alarm(XxlJobInfo info, XxlJobLog jobLog); }XxlJobInfo 包含了任務(wù)的基本信息任務(wù) ID、任務(wù)描述、負(fù)責(zé)人、報警郵件等XxlJobLog 包含了本次執(zhí)行的日志信息執(zhí)行器地址、執(zhí)行結(jié)果、執(zhí)行備注等。這兩個對象里的信息足夠我們拼裝一條完整的報警消息。2.3 多實例部署下的報警去重問題如果你的調(diào)度中心是集群部署的生產(chǎn)環(huán)境通常會部署兩個節(jié)點(diǎn)做高可用那么失敗監(jiān)控線程會在每個節(jié)點(diǎn)上各跑一份。這就帶來一個潛在問題同一條失敗日志可能被兩個節(jié)點(diǎn)同時掃描到導(dǎo)致重復(fù)報警。XXL-JOB 本身對這個問題的處理方式是在更新報警狀態(tài)時使用樂觀鎖或者條件更新只有成功將“報警狀態(tài)”從未報警改為已報警的那個節(jié)點(diǎn)才會真正發(fā)送報警。但實際實現(xiàn)中不同版本的 XXL-JOB 處理方式略有差異。比較穩(wěn)妥的做法是在自定義報警器里也做一層冪等控制比如用 Redis 做一個短期的去重 keykey 的過期時間設(shè)置為報警間隔的兩倍左右。這樣即使框架層面有并發(fā)窗口業(yè)務(wù)層面也能兜住。不過話說回來對于報警消息來說偶爾重復(fù)一條并不是什么致命問題反而比漏報要好。所以如果你的環(huán)境里重復(fù)報警并不頻繁也可以不做額外去重接受這個 trade-off。我在實際項目中觀察下來XXL-JOB 2.3.x 及以上版本在集群模式下的報警去重做得已經(jīng)比較好了重復(fù)報警的概率很低。3. 核心細(xì)節(jié)解析與實操要點(diǎn)3.1 企業(yè)微信機(jī)器人 Webhook 的獲取與限制創(chuàng)建企業(yè)微信機(jī)器人的操作路徑是進(jìn)入一個群聊 → 點(diǎn)擊右上角 → 群機(jī)器人 → 添加機(jī)器人 → 選擇“自定義” → 設(shè)置機(jī)器人名稱和頭像 → 獲取 Webhook 地址。這個地址的格式是https://qyapi.weixin.qq.com/cgi-bin/webhook/send?keyxxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx拿到這個 URL 之后往上面 POST 一個 JSON 就能發(fā)消息。但有幾個限制必須提前知道頻率限制每個機(jī)器人每分鐘最多發(fā)送 20 條消息。超過之后會被限流返回錯誤碼 45009。對于任務(wù)調(diào)度報警來說如果短時間內(nèi)大量任務(wù)同時失敗比如數(shù)據(jù)庫掛了導(dǎo)致所有依賴數(shù)據(jù)庫的任務(wù)全部失敗很容易觸發(fā)這個限制。后面我會講怎么處理這種情況。消息長度限制markdown 類型的消息內(nèi)容最長 4096 字節(jié)超出部分會被截斷。所以報警消息里不要塞太多內(nèi)容關(guān)鍵信息點(diǎn)到為止。markdown 語法限制企業(yè)微信的 markdown 不是標(biāo)準(zhǔn) markdown支持的語法比較有限。支持標(biāo)題# 到 ######、加粗**、引用、字體顏色、鏈接、行內(nèi)代碼。不支持表格、不支持圖片圖片需要單獨(dú)用 image 類型消息發(fā)送、不支持有序列表的自動編號。 人限制markdown 類型不支持 成員只有 text 類型支持 mentioned_list 和 mentioned_mobile_list。如果報警需要 到具體負(fù)責(zé)人要么用 text 類型要么在 markdown 里手動寫上負(fù)責(zé)人的名字但沒有 的提醒效果。這些限制看起來多但對于報警場景來說其實夠用。報警消息的核心是“哪個任務(wù)失敗了、什么時候失敗的、失敗原因是什么、誰該去看”這些信息用 markdown 排版完全能表達(dá)清楚。3.2 報警消息的內(nèi)容設(shè)計一條好的報警消息應(yīng)該讓接收者在 3 秒內(nèi)判斷出“這事跟我有沒有關(guān)系、嚴(yán)不嚴(yán)重、要不要馬上處理”。基于這個原則我設(shè)計的報警消息模板包含以下字段字段說明是否必填任務(wù) IDXXL-JOB 中的任務(wù)主鍵是任務(wù)描述任務(wù)的業(yè)務(wù)含義是負(fù)責(zé)人任務(wù)的負(fù)責(zé)人是調(diào)度時間本次觸發(fā)調(diào)度的時間是執(zhí)行器地址實際執(zhí)行任務(wù)的節(jié)點(diǎn)是失敗原因執(zhí)行返回的備注信息是報警時間消息發(fā)送的時間否消息的 markdown 格式大概長這樣## 任務(wù)調(diào)度失敗報警 **任務(wù)ID** 1024 **任務(wù)描述** 每日訂單對賬 **負(fù)責(zé)人** 張三 **調(diào)度時間** 2024-01-15 02:00:00 **執(zhí)行器地址** http://192.168.1.100:9999/ **失敗原因** font colorwarningjava.lang.NullPointerException: .../font **報警時間** 2024-01-15 02:00:15用引用塊把信息包起來視覺上比較緊湊。失敗原因用 warning 顏色標(biāo)紅一眼就能看到。標(biāo)題用 ## 級別在企業(yè)微信里顯示為較大的字體起到醒目的作用。這里有個細(xì)節(jié)失敗原因可能非常長比如完整的異常堆棧直接塞進(jìn)消息里會超過長度限制。我的做法是截取前 200 個字符后面加省略號完整信息讓用戶去 XXL-JOB 控制臺查看。截取的時候要注意按字符而不是按字節(jié)截取避免把中文截成亂碼。3.3 報警器的代碼結(jié)構(gòu)設(shè)計自定義報警器的代碼結(jié)構(gòu)其實很簡單核心就是一個類實現(xiàn) JobAlarm 接口。但為了代碼的可維護(hù)性和可測試性我建議拆成三層報警器層實現(xiàn) JobAlarm 接口負(fù)責(zé)從 XxlJobInfo 和 XxlJobLog 中提取信息組裝成消息內(nèi)容調(diào)用發(fā)送器。消息組裝層負(fù)責(zé)把結(jié)構(gòu)化數(shù)據(jù)渲染成 markdown 文本方便后續(xù)調(diào)整消息模板。HTTP 發(fā)送層負(fù)責(zé)實際的 HTTP POST 請求處理超時、重試、異常。這樣拆的好處是如果以后要換一個報警渠道比如換成飛書機(jī)器人只需要改發(fā)送層消息組裝層可以復(fù)用。如果以后要調(diào)整消息格式只需要改組裝層不影響其他部分。在 Spring 環(huán)境下這個報警器類加上 Component 注解就會被自動掃描到。XXL-JOB 的 JobAlarm 收集邏輯是通過 Autowired 注入一個 List Spring 會自動把所有實現(xiàn)類注入進(jìn)來。所以不需要額外配置加個注解就行。但有一個坑需要注意如果你的調(diào)度中心項目里同時存在多個 JobAlarm 實現(xiàn)比如默認(rèn)的 EmailJobAlarm 加上你的自定義報警器那么每次報警會同時觸發(fā)所有報警器。如果你只想用企業(yè)微信報警、不想發(fā)郵件需要把 EmailJobAlarm 的配置關(guān)掉在 application.properties 里設(shè)置 xxl.job.alarm.email 相關(guān)配置為空或者不配置。不過實際上同時保留郵件和企業(yè)微信報警也不是壞事多一個渠道多一份保障。4. 完整實操過程與核心環(huán)節(jié)實現(xiàn)4.1 環(huán)境準(zhǔn)備與依賴確認(rèn)在開始寫代碼之前先確認(rèn)幾個環(huán)境條件XXL-JOB 版本建議 2.3.0 及以上這些版本的 JobAlarm 接口比較穩(wěn)定失敗監(jiān)控線程的邏輯也比較完善。我實測過 2.3.1 和 2.4.0都能正常工作。調(diào)度中心項目你需要有 xxl-job-admin 的源碼因為自定義報警器要加在這個項目里。如果你是用官方編譯好的 jar 包部署的需要重新拉源碼編譯。HTTP 客戶端調(diào)度中心項目本身依賴了 Spring Boot所以可以直接用 RestTemplate 或者 HttpClient。我習(xí)慣用 Java 11 自帶的 HttpClient不需要額外引入依賴。如果你用的是 Java 8可以用 OkHttp 或者 Apache HttpClient。JSON 庫XXL-JOB 本身依賴了 Gsoncom.google.gson可以直接用來組裝 JSON不需要額外引入 Jackson 或 Fastjson。確認(rèn)好這些之后在 xxl-job-admin 項目的 alarm 包下新建一個類比如叫 WeChatRobotJobAlarm。4.2 核心代碼實現(xiàn)先看消息組裝的部分。我定義了一個簡單的消息模板方法private String buildMarkdownMessage(XxlJobInfo info, XxlJobLog jobLog) { StringBuilder sb new StringBuilder(); sb.append(## 任務(wù)調(diào)度失敗報警\n); sb.append( **任務(wù)ID** ).append(info.getId()).append(\n); sb.append( **任務(wù)描述** ).append(info.getJobDesc()).append(\n); sb.append( **負(fù)責(zé)人** ).append(info.getAuthor()).append(\n); sb.append( **調(diào)度時間** ).append(DateUtil.formatDateTime(jobLog.getTriggerTime())).append(\n); sb.append( **執(zhí)行器地址** ).append(jobLog.getExecutorAddress()).append(\n); String failMsg jobLog.getTriggerMsg(); if (failMsg ! null failMsg.length() 200) { failMsg failMsg.substring(0, 200) ...; } sb.append( **失敗原因** font color\warning\).append(failMsg).append(/font\n); sb.append( **報警時間** ).append(DateUtil.formatDateTime(new Date())).append(\n); return sb.toString(); }這里用了 XXL-JOB 自帶的 DateUtil 工具類來格式化時間避免自己寫 SimpleDateFormat 的線程安全問題。失敗原因做了 200 字符的截斷處理防止消息過長。然后是 HTTP 發(fā)送的部分private boolean sendToWeChatRobot(String content) { try { MapString, Object body new HashMap(); body.put(msgtype, markdown); MapString, String markdown new HashMap(); markdown.put(content, content); body.put(markdown, markdown); String json new Gson().toJson(body); HttpClient client HttpClient.newHttpClient(); HttpRequest request HttpRequest.newBuilder() .uri(URI.create(webhookUrl)) .header(Content-Type, application/json) .POST(HttpRequest.BodyPublishers.ofString(json, StandardCharsets.UTF_8)) .timeout(Duration.ofSeconds(5)) .build(); HttpResponseString response client.send(request, HttpResponse.BodyHandlers.ofString()); if (response.statusCode() 200) { JsonObject result JsonParser.parseString(response.body()).getAsJsonObject(); int errcode result.get(errcode).getAsInt(); if (errcode 0) { return true; } logger.warn(企業(yè)微信機(jī)器人返回錯誤errcode{}, errmsg{}, errcode, result.get(errmsg).getAsString()); } } catch (Exception e) { logger.error(發(fā)送企業(yè)微信報警失敗, e); } return false; }這段代碼有幾個細(xì)節(jié)值得說明。超時時間設(shè)置為 5 秒是因為報警消息不需要等待太久如果企業(yè)微信接口 5 秒還沒響應(yīng)說明網(wǎng)絡(luò)有問題重試也沒有太大意義。返回結(jié)果里要檢查 errcode企業(yè)微信的接口即使 HTTP 狀態(tài)碼是 200也可能在 body 里返回業(yè)務(wù)錯誤碼。常見的錯誤碼有 45009頻率超限、93000機(jī)器人被移出群聊等。最后是 JobAlarm 接口的實現(xiàn)Component public class WeChatRobotJobAlarm implements JobAlarm { private static final Logger logger LoggerFactory.getLogger(WeChatRobotJobAlarm.class); Value(${xxl.job.alarm.wechat.webhook:}) private String webhookUrl; Override public boolean alarm(XxlJobInfo info, XxlJobLog jobLog) { if (webhookUrl null || webhookUrl.trim().isEmpty()) { logger.debug(未配置企業(yè)微信機(jī)器人 Webhook跳過報警); return false; } String content buildMarkdownMessage(info, jobLog); return sendToWeChatRobot(content); } }Webhook 地址通過配置文件注入這樣不同環(huán)境可以用不同的機(jī)器人開發(fā)環(huán)境推到開發(fā)群生產(chǎn)環(huán)境推到運(yùn)維群。如果沒配置 Webhook直接返回 false不影響其他報警器。4.3 配置文件與部署驗證在 application.properties 里加上一行配置xxl.job.alarm.wechat.webhookhttps://qyapi.weixin.qq.com/cgi-bin/webhook/send?key你的key然后重新編譯打包 xxl-job-admin部署到調(diào)度中心。驗證的方式很簡單在 XXL-JOB 控制臺里手動觸發(fā)一個會失敗的任務(wù)比如把一個執(zhí)行器的地址改錯或者讓任務(wù)拋異常觀察企業(yè)微信群里是否收到報警消息。如果沒收到先看調(diào)度中心的日志搜索“企業(yè)微信”相關(guān)的日志輸出。常見的問題包括Webhook 地址配錯了、網(wǎng)絡(luò)不通調(diào)度中心所在服務(wù)器無法訪問企業(yè)微信接口、消息格式不對被企業(yè)微信拒絕。日志里會打印具體的錯誤信息按圖索驥基本都能解決。4.4 頻率限制的應(yīng)對策略前面提到企業(yè)微信機(jī)器人每分鐘最多 20 條消息。如果短時間內(nèi)大量任務(wù)失敗比如數(shù)據(jù)庫連接池耗盡導(dǎo)致所有任務(wù)全部失敗可能會瞬間產(chǎn)生幾十條報警觸發(fā)限流。我的應(yīng)對策略是在發(fā)送層加一個簡單的令牌桶或者計數(shù)器。用 Guava 的 RateLimiter 就可以private final RateLimiter rateLimiter RateLimiter.create(0.3); // 每秒0.3個即每分鐘18個 // 在發(fā)送前調(diào)用 if (!rateLimiter.tryAcquire(1, TimeUnit.SECONDS)) { logger.warn(企業(yè)微信報警頻率超限本條報警被丟棄); return false; }這樣最多每秒發(fā) 0.3 條每分鐘 18 條留一點(diǎn)余量給其他用途。被限流的報警消息會被丟棄但日志里有記錄事后可以追溯。如果你覺得丟棄不可接受也可以改成把消息攢起來批量發(fā)送但實現(xiàn)復(fù)雜度會高不少。對于報警場景來說我傾向于簡單限流加日志記錄因為大量任務(wù)同時失敗時看一條報警和看十條報警的信息量差不多關(guān)鍵是知道“出大事了”。5. 常見問題與排查技巧實錄5.1 報警不觸發(fā)或觸發(fā)異常這是最常見的問題類型。我整理了一個排查速查表現(xiàn)象可能原因排查方法任務(wù)失敗但完全沒報警報警器沒被 Spring 掃描到檢查類上是否有 Component包路徑是否在掃描范圍內(nèi)任務(wù)失敗但完全沒報警Webhook 未配置或配置為空檢查 application.properties 中的配置項任務(wù)失敗但完全沒報警失敗監(jiān)控線程未啟動檢查調(diào)度中心啟動日志中是否有 JobFailMonitorHelper 相關(guān)日志報警消息發(fā)送失敗網(wǎng)絡(luò)不通在調(diào)度中心服務(wù)器上 curl 一下 Webhook 地址報警消息發(fā)送失敗消息格式錯誤查看企業(yè)微信返回的 errcode 和 errmsg報警消息發(fā)送失敗頻率超限查看 errcode 是否為 45009重復(fù)報警集群模式下多節(jié)點(diǎn)同時掃描檢查 XXL-JOB 版本考慮加 Redis 去重報警消息內(nèi)容為空XxlJobLog 字段為 null檢查 jobLog.getTriggerMsg() 是否為空加空值判斷其中“報警器沒被掃描到”是最容易犯的錯誤。很多人把報警器類寫在了執(zhí)行器項目里或者寫在了調(diào)度中心項目但包路徑不在 SpringBootApplication 的掃描范圍內(nèi)。XXL-JOB 的調(diào)度中心啟動類在 com.xxl.job.admin 包下所以你的報警器類要么放在這個包及其子包下要么在啟動類上手動加 ComponentScan。5.2 消息內(nèi)容顯示異常企業(yè)微信的 markdown 渲染和標(biāo)準(zhǔn) markdown 有一些差異我踩過的坑包括換行問題企業(yè)微信 markdown 里單個 \n 不會換行需要兩個 \n 或者用引用塊。我一開始用 \n 拼接結(jié)果所有內(nèi)容擠在一行后來改成每個字段后面加 \n并且用引用塊包裹顯示就正常了。字體顏色只支持 info綠色、warning橙紅色、comment灰色三種顏色寫其他顏色值不會生效會顯示為默認(rèn)顏色。特殊字符任務(wù)描述里如果包含 等字符可能會破壞 markdown 結(jié)構(gòu)。建議在拼接前做一次 HTML 轉(zhuǎn)義或者至少把 和 替換掉。超長內(nèi)容前面說過 4096 字節(jié)限制但實際測試下來超過 2000 字節(jié)左右企業(yè)微信客戶端就可能顯示不全。所以消息內(nèi)容盡量精簡。5.3 集群環(huán)境下的重復(fù)報警如果你的調(diào)度中心部署了兩個節(jié)點(diǎn)理論上同一條失敗日志可能被兩個節(jié)點(diǎn)同時處理。XXL-JOB 在 JobFailMonitorHelper 里通過數(shù)據(jù)庫的樂觀鎖來保證只有一條記錄被更新成功但不同版本的實現(xiàn)細(xì)節(jié)有差異。我在 2.3.1 版本上實測集群模式下重復(fù)報警的概率大概在 5% 左右不算高但確實存在。如果你對重復(fù)報警零容忍可以加一層 Redis 去重String dedupKey xxl:alarm:dedup: jobLog.getId(); Boolean success redisTemplate.opsForValue().setIfAbsent(dedupKey, 1, 5, TimeUnit.MINUTES); if (Boolean.FALSE.equals(success)) { logger.debug(報警已發(fā)送過跳過重復(fù)報警logId{}, jobLog.getId()); return true; }用 jobLog 的主鍵作為去重 key5 分鐘內(nèi)不重復(fù)發(fā)送。這樣即使框架層面有并發(fā)窗口業(yè)務(wù)層面也能兜住。返回 true 是為了告訴框架“報警已處理”避免框架反復(fù)重試。5.4 報警消息的負(fù)責(zé)人 提醒前面提到 markdown 類型不支持 人。如果你確實需要 到具體負(fù)責(zé)人有兩個方案方案一改用 text 類型消息用 mentioned_mobile_list 參數(shù) 負(fù)責(zé)人的手機(jī)號。但 text 類型不支持 markdown 排版消息看起來比較樸素。方案二在 markdown 消息里手動寫上負(fù)責(zé)人的名字雖然沒有 的強(qiáng)提醒效果但群里的人看到自己的名字自然會關(guān)注。我傾向于方案二因為報警消息的排版清晰比 提醒更重要而且企業(yè)微信群里 太多也容易引起反感。如果一定要 可以發(fā)兩條消息一條 markdown 類型的詳細(xì)報警一條 text 類型的 提醒。但這樣會消耗兩倍的頻率配額需要權(quán)衡。5.5 報警消息的靜默與降噪上線一段時間后你可能會發(fā)現(xiàn)某些任務(wù)的報警特別頻繁比如一個每分鐘執(zhí)行一次的任務(wù)偶爾失敗一次就報警一天下來幾十條消息群里的人都麻木了。這時候需要做報警降噪。我的做法是在報警器里加一個簡單的靜默邏輯同一個任務(wù)在 N 分鐘內(nèi)只報警一次。用 Redis 記錄每個任務(wù)的上次報警時間如果距離上次報警不足 N 分鐘就跳過。N 可以根據(jù)任務(wù)的執(zhí)行頻率來設(shè)置比如每分鐘執(zhí)行的任務(wù)設(shè)置 10 分鐘靜默每天執(zhí)行的任務(wù)設(shè)置 0 分鐘每次都報。String silenceKey xxl:alarm:silence: info.getId(); Boolean canAlarm redisTemplate.opsForValue().setIfAbsent(silenceKey, 1, silenceMinutes, TimeUnit.MINUTES); if (Boolean.FALSE.equals(canAlarm)) { logger.debug(任務(wù){(diào)}處于靜默期跳過報警, info.getId()); return true; }這個邏輯和前面的去重邏輯可以合并用同一個 Redis key 同時實現(xiàn)去重和靜默。靜默時間可以通過任務(wù)的執(zhí)行頻率動態(tài)計算也可以做成可配置的。5.6 測試環(huán)境與生產(chǎn)環(huán)境的隔離開發(fā)測試環(huán)境的任務(wù)失敗頻率通常比生產(chǎn)環(huán)境高很多如果測試環(huán)境的報警也推到生產(chǎn)運(yùn)維群會造成大量噪音。我的做法是通過配置文件區(qū)分不同環(huán)境的 Webhook 地址開發(fā)環(huán)境推送到開發(fā)群測試環(huán)境推送到測試群生產(chǎn)環(huán)境推送到運(yùn)維群。Spring Boot 的多環(huán)境配置application-dev.properties、application-prod.properties天然支持這一點(diǎn)。另外測試環(huán)境的報警可以設(shè)置更長的靜默時間或者干脆只在特定時間段比如工作時間發(fā)送報警避免半夜吵醒人。這些都可以通過配置項來控制不需要改代碼。6. 一些實操后的個人體會這套方案我在三個不同的項目里落地過從最初的簡單版本迭代到現(xiàn)在帶限流、去重、靜默的完整版本前后大概改了五六次。最大的體會是報警系統(tǒng)的核心不是“發(fā)出去”而是“發(fā)得對”。發(fā)得太多大家會麻木發(fā)得太少又會漏掉關(guān)鍵問題。找到這個平衡點(diǎn)需要根據(jù)團(tuán)隊的實際情況不斷調(diào)整。另外一個容易被忽視的點(diǎn)是報警消息的可操作性。一條好的報警消息應(yīng)該讓接收者能直接點(diǎn)擊鏈接跳到 XXL-JOB 控制臺查看詳情而不是自己去翻控制臺找任務(wù)。企業(yè)微信 markdown 支持鏈接語法可以在消息里加上控制臺的任務(wù)詳情頁鏈接點(diǎn)擊直接跳轉(zhuǎn)。這個小小的改進(jìn)能顯著提升處理效率。最后分享一個小技巧企業(yè)微信機(jī)器人的 Webhook 地址里那個 key 是敏感信息不要直接硬編碼在代碼里提交到代碼倉庫。用環(huán)境變量或者配置中心來管理避免泄露后被惡意利用。雖然機(jī)器人只能發(fā)消息不能讀消息但被人惡意刷消息也是挺煩的。