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