簡(jiǎn)介阿里釘釘集成APIJava是一套面向企業(yè)級(jí)Java開(kāi)發(fā)者的釘釘開(kāi)放平臺(tái)對(duì)接方案覆蓋從OAuth2.0授權(quán)、access_token獲取、消息推送到企業(yè)通訊錄與審批流管理的關(guān)鍵鏈路并附帶可運(yùn)行的Demo與源碼分析適合需要將業(yè)務(wù)系統(tǒng)深度整合進(jìn)釘釘?shù)膱F(tuán)隊(duì)參考。壓縮包共174個(gè)文件大小8.17MB其中包含32個(gè)java源碼、38個(gè)class編譯產(chǎn)物、30個(gè)jar依賴(lài)庫(kù)以及html/jsp頁(yè)面、js/css前端資源、xml配置和png/jpg素材、md說(shuō)明文檔等目錄劃分為src與demo兩大模塊便于按功能查閱。目前已有3452人學(xué)習(xí)瀏覽是一份結(jié)構(gòu)清晰、上手門(mén)檻較低的實(shí)戰(zhàn)資料。通過(guò)閱讀源碼、運(yùn)行Demo并配合調(diào)試日志開(kāi)發(fā)者可快速掌握釘釘API調(diào)用、消息卡片發(fā)送、組織架構(gòu)管理等核心技能減少重復(fù)踩坑。 最近在給公司做一套內(nèi)部自動(dòng)化通知系統(tǒng)需求其實(shí)很簡(jiǎn)單工單狀態(tài)變更、定時(shí)報(bào)表跑完、系統(tǒng)告警這些消息要能第一時(shí)間推到員工的釘釘上。一開(kāi)始我還在糾結(jié)要不要自己寫(xiě)推送服務(wù)后來(lái)發(fā)現(xiàn)釘釘開(kāi)放平臺(tái)的API已經(jīng)覆蓋了消息、審批、通訊錄、機(jī)器人這些核心場(chǎng)景直接用現(xiàn)成的能力比自己造輪子省太多事。這篇文章就把我用Java集成釘釘API的完整過(guò)程、代碼片段和踩過(guò)的坑整理出來(lái)給正準(zhǔn)備接釘釘?shù)耐瑢W(xué)做個(gè)參考。整篇不繞彎子能直接復(fù)制的代碼和配置我都會(huì)貼出來(lái)。1. 集成前的整體思路先搞清楚你要用釘釘?shù)哪牟糠帜芰?.1 釘釘API能做什么以及最常用的三類(lèi)場(chǎng)景釘釘開(kāi)放平臺(tái)的能力比我一開(kāi)始想象的大得多。光是企業(yè)內(nèi)部應(yīng)用能調(diào)用的API就覆蓋了消息通知、審批流、考勤、通訊錄、日程、會(huì)議、群機(jī)器人、工作臺(tái)等等。但落到實(shí)際項(xiàng)目里90%以上的Java后端集成需求其實(shí)集中在三個(gè)方向。第一個(gè)是消息推送就是往指定員工或者整個(gè)部門(mén)發(fā)送工作通知。這類(lèi)需求最常見(jiàn)工單提醒、告警通知、報(bào)表推送、待辦提醒全是這一種。第二個(gè)是審批流集成比如把內(nèi)部業(yè)務(wù)系統(tǒng)的審批申請(qǐng)自動(dòng)提交到釘釘審批或者反過(guò)來(lái)釘釘審批通過(guò)后把結(jié)果回傳給我們自己的系統(tǒng)。第三個(gè)是通訊錄同步很多公司會(huì)把釘釘組織架構(gòu)作為主數(shù)據(jù)源把部門(mén)、員工信息拉取下來(lái)和自己系統(tǒng)的用戶體系做映射。我這次做的主要是第一個(gè)場(chǎng)景順帶用了通訊錄查詢來(lái)根據(jù)手機(jī)號(hào)匹配userid。后面寫(xiě)的內(nèi)容也會(huì)圍繞這三塊展開(kāi)尤其是消息推送因?yàn)樗墙^大多數(shù)集成的第一站。1.2 選型官方SDK還是裸HTTP調(diào)用我為什么推薦先學(xué)會(huì)HTTP調(diào)用釘釘?shù)腏ava接入方式有兩條路一條是用官方提供的SDK一條是直接用HTTP請(qǐng)求調(diào)API。很多新手上來(lái)就依賴(lài)SDK一個(gè)方法調(diào)用搞定但我還是建議先弄懂HTTP調(diào)用的原理再去用SDK。原因很簡(jiǎn)單SDK本質(zhì)上就是對(duì)HTTP接口的封裝你如果不知道底層請(qǐng)求長(zhǎng)什么樣出了問(wèn)題會(huì)非常被動(dòng)。比如返回errcode是40001你都不知道這個(gè)錯(cuò)誤其實(shí)是token失效了。另外公司里很多線上環(huán)境用的還是老舊的JDK8或者受管控的依賴(lài)庫(kù)SDK版本裝不上、拉不下來(lái)是常有的事。學(xué)會(huì)用最基礎(chǔ)的HTTP請(qǐng)求寫(xiě)一次調(diào)用至少能保證在任何環(huán)境下都能把接口跑通。從另一個(gè)角度說(shuō)如果只用SDK遇到SDK版本和JDK不兼容的問(wèn)題網(wǎng)上搜到的解決方案少之又少。而HTTP調(diào)用方案是通用的跟語(yǔ)言無(wú)關(guān)排查思路也透明。我實(shí)際項(xiàng)目里用的是新版SDK但排查問(wèn)題的時(shí)候所有關(guān)鍵API我都會(huì)先用Postman或者命令行curl驗(yàn)證一遍確認(rèn)是接口問(wèn)題還是代碼問(wèn)題再回來(lái)看代碼。2. 前置準(zhǔn)備與工程初始化2.1 開(kāi)發(fā)者后臺(tái)配置企業(yè)內(nèi)部應(yīng)用、權(quán)限申請(qǐng)、發(fā)布在寫(xiě)代碼之前必須先到釘釘開(kāi)放平臺(tái)后臺(tái)把應(yīng)用建好這一步漏了后續(xù)全是白費(fèi)。登錄open.dingtalk.com后進(jìn)入開(kāi)發(fā)者后臺(tái)創(chuàng)建應(yīng)用時(shí)有兩個(gè)選擇企業(yè)內(nèi)部應(yīng)用和第三方應(yīng)用。如果只是給自己公司內(nèi)部用選企業(yè)內(nèi)部應(yīng)用就夠了審批流程短權(quán)限點(diǎn)也好申請(qǐng)。創(chuàng)建應(yīng)用之后你會(huì)拿到幾個(gè)關(guān)鍵參數(shù)這些后面寫(xiě)代碼都要用AppKey、AppSecret、AgentId還有企業(yè)CorpId。這幾個(gè)參數(shù)千萬(wàn)別寫(xiě)死到代碼倉(cāng)庫(kù)里至少要放到配置中心或者環(huán)境變量里管起來(lái)。AppSecret尤其重要它是應(yīng)用的密鑰泄露了等于別人可以冒充你的應(yīng)用調(diào)接口。然后是權(quán)限點(diǎn)申請(qǐng)。很多API不是創(chuàng)建應(yīng)用就能直接調(diào)的需要在權(quán)限管理里申請(qǐng)對(duì)應(yīng)的權(quán)限點(diǎn)。比如發(fā)工作通知就要申請(qǐng)工作通知消息發(fā)送權(quán)限查通訊錄用戶信息要申請(qǐng)通訊錄個(gè)人信息讀權(quán)限。權(quán)限點(diǎn)申請(qǐng)后一般需要一個(gè)審批流程企業(yè)內(nèi)部應(yīng)用通常幾分鐘就能過(guò)。這一步特別容易踩坑權(quán)限沒(méi)申請(qǐng)或者申請(qǐng)了但應(yīng)用沒(méi)發(fā)布調(diào)用接口就會(huì)報(bào)沒(méi)有權(quán)限或者無(wú)權(quán)限之類(lèi)的錯(cuò)誤。最后別忘了把應(yīng)用發(fā)布。在版本管理與發(fā)布里發(fā)布一個(gè)正式版本設(shè)置好可見(jiàn)范圍應(yīng)用才算真正可用。開(kāi)發(fā)階段如果只是在應(yīng)用后臺(tái)點(diǎn)了調(diào)試沒(méi)走發(fā)布流程部分API會(huì)一直返回?zé)o權(quán)限。2.2 Java工程環(huán)境檢查與依賴(lài)引入集成釘釘API并不挑Java版本JDK8以上基本都能跑。不過(guò)因?yàn)橐逪TTPS請(qǐng)求建議直接用JDK 11及以上版本java.net.http.HttpClient用起來(lái)比老舊的HttpURLConnection舒服太多。如果你的機(jī)器還沒(méi)配好JAVA_HOME和環(huán)境變量先花十分鐘把環(huán)境搞定否則后面編譯會(huì)出現(xiàn)找不到或無(wú)法加載主類(lèi)、ClassNotFoundException這類(lèi)問(wèn)題那不是代碼的錯(cuò)是環(huán)境變量沒(méi)配好。Maven工程的話要是用官方新版SDK只需要引入一個(gè)依賴(lài)dependency groupIdcom.aliyun/groupId artifactIddingtalk/artifactId version2.1.42/version /dependency這個(gè)依賴(lài)包很大下載慢是正常的。另外它傳遞依賴(lài)的版本有時(shí)候會(huì)和項(xiàng)目里已有的依賴(lài)沖突尤其是com.google.code.gson這類(lèi)常見(jiàn)庫(kù)如果啟動(dòng)時(shí)發(fā)現(xiàn)類(lèi)沖突或者方法找不到優(yōu)先檢查依賴(lài)樹(shù)把版本統(tǒng)一一下。如果不想用SDK那就簡(jiǎn)單了項(xiàng)目里只要有一個(gè)HTTP客戶端就行。RestTemplate、OkHttp、HttpClient都行甚至不引第三方庫(kù)直接用JDK原生的HttpClient也能做完整集成。我下面的示例大部分會(huì)用JDK原生的HttpClient寫(xiě)法這樣你復(fù)制過(guò)去就能跑不需要額外引依賴(lài)。3. 核心API調(diào)用實(shí)戰(zhàn)從獲取AccessToken到發(fā)送消息3.1 獲取AccessToken的正確姿勢(shì)以及為什么不建議每次都重新獲取釘釘API的鑒權(quán)方式和大多數(shù)開(kāi)放平臺(tái)一樣先用AppKey和AppSecret換一個(gè)AccessToken后續(xù)的業(yè)務(wù)API都帶著這個(gè)Token去調(diào)。這個(gè)Token本質(zhì)上就是一張臨時(shí)通行證有效期默認(rèn)是7200秒也就是兩個(gè)小時(shí)。獲取Token的接口很簡(jiǎn)單import java.net.URI; import java.net.http.HttpClient; import java.net.http.HttpRequest; import java.net.http.HttpResponse; public class DingTalkTokenService { private static final String APP_KEY 你的AppKey; private static final String APP_SECRET 你的AppSecret; public static String getAccessToken() throws Exception { String url https://oapi.dingtalk.com/gettoken?appkey APP_KEY appsecret APP_SECRET; HttpClient client HttpClient.newBuilder().build(); HttpRequest request HttpRequest.newBuilder() .uri(URI.create(url)) .GET() .build(); HttpResponseString response client.send(request, HttpResponse.BodyHandlers.ofString()); // 用你項(xiàng)目里已有的JSON庫(kù)解析即可 return parseAccessTokenFromResponse(response.body()); } }返回的JSON結(jié)構(gòu)長(zhǎng)這樣{ errcode: 0, errmsg: ok, access_token: xxxxx, expires_in: 7200 }有一個(gè)非常關(guān)鍵的細(xì)節(jié)釘釘獲取token的接口有頻率限制官方文檔說(shuō)同一應(yīng)用獲取AccessToken不能過(guò)于頻繁短時(shí)間內(nèi)反復(fù)調(diào)用會(huì)被限流直接返回錯(cuò)誤或者臨時(shí)封禁。所以絕對(duì)不能每次發(fā)消息前都調(diào)一次gettoken正確做法是把token緩存起來(lái)快到過(guò)期時(shí)間再刷新。簡(jiǎn)單點(diǎn)說(shuō)就是用一個(gè)全局變量或者Redis存token加上一個(gè)過(guò)期時(shí)間。在高并發(fā)或者多實(shí)例部署的場(chǎng)景下要注意多臺(tái)機(jī)器同時(shí)刷新token導(dǎo)致的請(qǐng)求風(fēng)暴最好用分布式鎖控制。我見(jiàn)過(guò)有團(tuán)隊(duì)每調(diào)用一次API就重新拿一次token結(jié)果線上被限流了一個(gè)多小時(shí)排查了很久才發(fā)現(xiàn)是這個(gè)原因。3.2 發(fā)送工作通知消息的標(biāo)準(zhǔn)流程與消息體結(jié)構(gòu)拿到token之后發(fā)送工作通知就是一次標(biāo)準(zhǔn)的POST請(qǐng)求。接口地址是POST https://oapi.dingtalk.com/topapi/message/corpconversation/asyncsend_v2?access_tokenACCESS_TOKEN請(qǐng)求體示例{ agent_id: 123456789, userid_list: zhangsan,lisi, msg: { msgtype: text, text: { content: 工單 #20240601 已處理完成請(qǐng)及時(shí)關(guān)注。 } } }對(duì)應(yīng)的Java代碼用JDK原生HttpClient寫(xiě)大概是這樣public class DingTalkMessageSender { public static void sendWorkNotification(String accessToken, Long agentId, String userIds, String content) throws Exception { String url https://oapi.dingtalk.com/topapi/message/corpconversation/asyncsend_v2 ?access_token accessToken; String body { agent_id: %d, userid_list: %s, msg: { msgtype: text, text: { content: %s } } } .formatted(agentId, userIds, content); HttpClient client HttpClient.newHttpClient(); HttpRequest request HttpRequest.newBuilder() .uri(URI.create(url)) .header(Content-Type, application/json) .POST(HttpRequest.BodyPublishers.ofString(body, StandardCharsets.UTF_8)) .build(); HttpResponseString response client.send(request, HttpResponse.BodyHandlers.ofString()); System.out.println(response.body()); } }這里有幾個(gè)點(diǎn)要特別提醒。userid_list是釘釘內(nèi)部的用戶ID不是手機(jī)號(hào)也不是員工的工號(hào)。如果你手上只有手機(jī)號(hào)得先調(diào)用通訊錄查詢接口根據(jù)手機(jī)號(hào)查出userid再拼到userid_list里。還有接收人如果不在應(yīng)用的可見(jiàn)范圍內(nèi)消息也會(huì)發(fā)送失敗。另外agent_id填錯(cuò)了比如填成了AppKey接口會(huì)返回類(lèi)似無(wú)效的agentId的錯(cuò)誤所以這兩個(gè)參數(shù)一定要區(qū)分清楚。消息內(nèi)容msg字段支持很多類(lèi)型text、markdown、link、actionCard、feedCard等等。實(shí)際使用中markdown類(lèi)型特別實(shí)用可以加標(biāo)題、加顏色、加鏈接比純文本直觀很多。構(gòu)建markdown消息的時(shí)候只需要把msgtype改成markdown再填一個(gè)markdown.title和處理好的markdown文本就行。成功發(fā)送后返回結(jié)果里會(huì)帶一個(gè)task_id這是這條消息任務(wù)的唯一標(biāo)識(shí)可以用來(lái)查消息的送達(dá)狀態(tài)。如果返回errcode是0、errmsg是ok基本就說(shuō)明釘釘服務(wù)端接收成功了但接收人有沒(méi)有真正看到那是異步送達(dá)的事查狀態(tài)要調(diào)另一個(gè)查詢接口。3.3 官方新版SDK的使用體驗(yàn)減少造輪子但別依賴(lài)過(guò)度前面說(shuō)推薦先懂HTTP原理但實(shí)際項(xiàng)目里我會(huì)用官方新版SDK因?yàn)樗哪Ｐ投x非常完整響應(yīng)對(duì)象都幫你解析好了開(kāi)發(fā)效率高很多。新版SDK坐標(biāo)就是前面提到的那一個(gè)調(diào)用獲取token的邏輯長(zhǎng)這樣import com.aliyun.dingtalkoauth2_1_0.*; import com.aliyun.teaopenapi.models.Config; public class NewSdkDemo { public static String getToken() throws Exception { Config config new Config(); config.protocol https; config.regionId central; com.aliyun.dingtalkoauth2_1_0.Client client new com.aliyun.dingtalkoauth2_1_0.Client(config); GetAccessTokenRequest request new GetAccessTokenRequest() .setAppKey(你的AppKey) .setAppSecret(你的AppSecret); GetAccessTokenResponse response client.getAccessToken(request); return response.getBody().getAccessToken(); } }新版SDK在包結(jié)構(gòu)上做了很細(xì)的拆分不同模塊是獨(dú)立的包比如dingtalkoauth2_1_0負(fù)責(zé)tokendingtalkmessage_1_0負(fù)責(zé)消息dingtalkhrbot_1_0負(fù)責(zé)機(jī)器人你需要哪個(gè)能力就引哪個(gè)包。這個(gè)設(shè)計(jì)好處是依賴(lài)更清晰壞處是包多API名字有細(xì)微差別第一次用還是要翻文檔。用了一周之后我的感受是SDK適合功能開(kāi)發(fā)階段能省很多時(shí)間線上排查問(wèn)題階段我還是習(xí)慣直接拼HTTP請(qǐng)求復(fù)現(xiàn)。所以建議你兩邊都要會(huì)HTTP是保底方案SDK是效率方案兩者不沖突。4. 其他常用場(chǎng)景機(jī)器人、回調(diào)與通訊錄查詢4.1 自定義機(jī)器人Webhook和加簽機(jī)制除了工作通知還有一類(lèi)非常受歡迎的消息通道群機(jī)器人。在釘釘群里添加一個(gè)自定義機(jī)器人會(huì)得到一個(gè)Webhook地址往這個(gè)地址POST一條JSON消息消息就會(huì)出現(xiàn)在群里。這個(gè)方案最友好的地方在于不需要申請(qǐng)任何API權(quán)限也不需要AppKey和AppSecret只需要一個(gè)Webhook URL。但安全上要留意Webhook地址一旦泄露任何人都能往這個(gè)群里發(fā)消息。所以創(chuàng)建機(jī)器人的時(shí)候強(qiáng)烈建議開(kāi)啟加簽安全設(shè)置。加簽的邏輯是發(fā)起請(qǐng)求時(shí)帶上當(dāng)前時(shí)間戳毫秒把時(shí)間戳和密鑰拼成字符串用HmacSHA256算法簽名再把簽名做URL編碼放到請(qǐng)求里。import javax.crypto.Mac; import javax.crypto.spec.SecretKeySpec; import java.net.URLEncoder; import java.nio.charset.StandardCharsets; import java.util.Base64; public class RobotSign { public static String generateSign(long timestamp, String secret) throws Exception { String stringToSign timestamp \n secret; Mac mac Mac.getInstance(HmacSHA256); mac.init(new SecretKeySpec(secret.getBytes(StandardCharsets.UTF_8), HmacSHA256)); byte[] signData mac.doFinal(stringToSign.getBytes(StandardCharsets.UTF_8)); return URLEncoder.encode(Base64.getEncoder().encodeToString(signData), UTF-8); } }請(qǐng)求Webhook時(shí)的URL要帶上timestamp和sign參數(shù)服務(wù)端會(huì)校驗(yàn)時(shí)間戳與簽名是否匹配時(shí)間戳和當(dāng)前時(shí)間偏差太大會(huì)拒絕。這里最大的坑是服務(wù)器時(shí)鐘漂移如果服務(wù)器時(shí)間不準(zhǔn)確加簽一直會(huì)失敗表現(xiàn)為同樣的代碼本地能跑通線上卻一直401。排查方式很簡(jiǎn)單先date一下服務(wù)器時(shí)間差太多就要同步NTP。4.2 回調(diào)事件訂閱與加解密消息推送是單向的釘釘往外推我們接收。但很多時(shí)候需要雙向聯(lián)動(dòng)比如員工在釘釘上提交了審批我們希望審批通過(guò)后自己的系統(tǒng)能自動(dòng)收到通知。這就需要配置事件訂閱回調(diào)。配置回調(diào)分兩步。第一步在開(kāi)發(fā)者后臺(tái)事件訂閱里填一個(gè)回調(diào)URL和一個(gè)AES密鑰。第二步釘釘會(huì)先發(fā)一個(gè)驗(yàn)證請(qǐng)求來(lái)確認(rèn)URL是你的這個(gè)驗(yàn)證請(qǐng)求非常繞它不是普通JSON而是加過(guò)密的。你需要完成解密、解析出msgSignature、timeStamp、nonce、encrypt等字段算好簽名再按指定格式返回響應(yīng)驗(yàn)證才能通過(guò)。驗(yàn)證的核心是四步用token、timestamp、nonce、encrypt拼字符串算SHA1簽名解base64解碼后的AES密文拿AES密鑰解密出JSON把JSON里的echostr原樣返回。第一次做這個(gè)流程我大概花了半天時(shí)間主要是釘釘文檔里對(duì)密鑰的格式描述得不是很直觀AES密鑰長(zhǎng)度、加解密模式有嚴(yán)格限制。這里送你一個(gè)經(jīng)驗(yàn)回調(diào)URL的處理邏輯單獨(dú)寫(xiě)一個(gè)controller不要把業(yè)務(wù)邏輯混進(jìn)去。因?yàn)榛卣{(diào)是高頻請(qǐng)求而且有超時(shí)要求如果業(yè)務(wù)處理太重被拖到響應(yīng)超時(shí)釘釘會(huì)認(rèn)為回調(diào)失敗然后不停重試。我一般是先返回成功把事件丟到MQ或者線程池里異步處理。4.3 通訊錄查詢與用戶ID映射綁定消息接收人這一步幾乎繞不開(kāi)通訊錄接口。業(yè)務(wù)系統(tǒng)里存的是手機(jī)號(hào)或者工號(hào)而釘釘消息接口要的是userid所以要做一層映射。獲取用戶信息的接口是POST https://oapi.dingtalk.com/topapi/v2/user/getbyunionid實(shí)際上更常用的是先通過(guò)手機(jī)號(hào)查用戶接口是topapi/v2/user/getbymobile。請(qǐng)求體和返回體都是JSON請(qǐng)求只需要傳一個(gè)mobile字段返回里帶出userid、name、unionid這些關(guān)鍵信息。我建議在公司內(nèi)部維護(hù)一個(gè)緩存表把員工手機(jī)號(hào)和釘釘userid的映射關(guān)系定期同步到本地庫(kù)不要每次發(fā)消息都現(xiàn)查釘釘接口。因?yàn)橥ㄓ嶄浗涌谕瑯佑蓄l率限制而且發(fā)一批通知可能涉及幾十上百人實(shí)時(shí)查詢既慢又容易觸發(fā)限流。定時(shí)任務(wù)每天同步一次就好員工入職離職的增量變化再單獨(dú)處理。5. 常見(jiàn)問(wèn)題與排查技巧實(shí)錄5.1 高頻報(bào)錯(cuò)與解決方案速查表我整理了一下集成過(guò)程中最容易遇到的一批報(bào)錯(cuò)按錯(cuò)誤碼和現(xiàn)象分好了類(lèi)你遇到類(lèi)似問(wèn)題可以直接對(duì)著查?，F(xiàn)象/錯(cuò)誤碼可能原因解決辦法40001AccessToken無(wú)效或過(guò)期重新獲取token確認(rèn)AppKey/AppSecret正確檢查token是否被其他環(huán)境覆蓋40002參數(shù)錯(cuò)誤核對(duì)agent_id、userid_list、msg結(jié)構(gòu)是否符合接口文檔40003無(wú)效用戶userid不是當(dāng)前企業(yè)下的或者傳成了手機(jī)號(hào)/郵箱40005無(wú)權(quán)限權(quán)限點(diǎn)未申請(qǐng)或者應(yīng)用未發(fā)布、接收人不在可見(jiàn)范圍內(nèi)40101簽名不匹配機(jī)器人加簽的timestamp和簽名算法有誤檢查服務(wù)器時(shí)間41002企業(yè)不存在corpId填錯(cuò)了確認(rèn)是企業(yè)CorpId而不是應(yīng)用ID46001請(qǐng)求頻率超限觸發(fā)了頻控檢查token是否緩存消息發(fā)送是否做了批量控制回調(diào)查驗(yàn)失敗加密解密不匹配AES密鑰長(zhǎng)度或編碼不對(duì)簽名算法順序錯(cuò)了這里要特別記一下錯(cuò)誤碼40005是最容易被忽略的。很多人代碼邏輯完全正確但忘了在后臺(tái)把權(quán)限點(diǎn)申請(qǐng)走完或者忘了發(fā)布應(yīng)用導(dǎo)致明明本地測(cè)試沒(méi)問(wèn)題一上生產(chǎn)就報(bào)無(wú)權(quán)限。我在預(yù)發(fā)環(huán)境驗(yàn)證時(shí)用的還是測(cè)試應(yīng)用發(fā)到正式環(huán)境前忘了給正式應(yīng)用申請(qǐng)工作通知消息發(fā)送權(quán)限結(jié)果整整排查了一個(gè)下午。5.2 幾個(gè)必須注意的隱形坑第一個(gè)坑是Token緩存的時(shí)間差。官方說(shuō)token有效期7200秒但偶爾在臨近過(guò)期的時(shí)間段調(diào)用會(huì)出現(xiàn)間歇性的401。我采取的做法是緩存時(shí)間設(shè)置成7000秒留出200秒的余量寧可多刷新一次也不要線上大面積失敗。第二個(gè)坑是分布式環(huán)境下Redis緩存token的數(shù)據(jù)類(lèi)型。網(wǎng)上有很多用Redis存token并計(jì)數(shù)防止超限的代碼但如果你用RedisTemplate的increment方法做計(jì)數(shù)返回值一定要用Long接收。我見(jiàn)過(guò)同事在這里踩了個(gè)大坑方法返回的是Integer強(qiáng)轉(zhuǎn)后直接拋不是Integer或out of range異常。原因很簡(jiǎn)單Redis整型自增返回的是64位長(zhǎng)整型你用32位的Integer去接當(dāng)然會(huì)溢出。第三個(gè)坑是Java編譯環(huán)境和Lombok的版本沖突。如果你用的是新版釘釘SDK并且項(xiàng)目里啟用了Lombok啟動(dòng)時(shí)可能會(huì)報(bào)You arent using a compiler supported by lombok, so lombok will not work這類(lèi)警告嚴(yán)重時(shí)會(huì)直接導(dǎo)致類(lèi)加載失敗。這個(gè)問(wèn)題的本質(zhì)是Lombok不認(rèn)當(dāng)前的JDK版本升級(jí)Lombok插件版本到1.18.30以上或者把JDK版本調(diào)整到和Lombok匹配的版本就好。5.3 一次線上消息發(fā)送失敗的完整排查思路最后分享一個(gè)真實(shí)的排查案例希望能幫你形成一套順手的排錯(cuò)順序。當(dāng)時(shí)現(xiàn)象是定時(shí)任務(wù)半夜發(fā)報(bào)表通知部分人收到了部分人沒(méi)收到。我拿到問(wèn)題第一反應(yīng)先去查釘釘?shù)恼{(diào)用日志看看接口返回的task_id是否存在、errcode是否為0。日志顯示發(fā)送都成功了說(shuō)明釘釘服務(wù)端已經(jīng)接收。接下來(lái)按task_id調(diào)消息查詢接口發(fā)現(xiàn)部分消息狀態(tài)是已讀部分消息狀態(tài)是未讀還有幾條狀態(tài)是發(fā)送失敗。查看失敗詳情原因是接收人已經(jīng)離職userid在釘釘里被清理了。這時(shí)候再去查通訊錄果然這些員工的手機(jī)號(hào)已經(jīng)不在組織架構(gòu)里。問(wèn)題根源就清楚了我們的本地映射表同步不及時(shí)離職員工的userid還殘留著導(dǎo)致發(fā)消息時(shí)報(bào)無(wú)效用戶。后續(xù)的修復(fù)方案一個(gè)是同步任務(wù)里增加離職員工標(biāo)記另一個(gè)是發(fā)送接口調(diào)用前先批量校驗(yàn)userid是否有效。排查下來(lái)整個(gè)過(guò)程其實(shí)不復(fù)雜但如果一開(kāi)始不去查日志而是一條條核對(duì)代碼效率會(huì)低很多。說(shuō)實(shí)話釘釘這類(lèi)開(kāi)放平臺(tái)的問(wèn)題絕大多數(shù)都出在配置和參數(shù)上代碼層面的問(wèn)題反而少。所以排查思路一定是配置參數(shù)優(yōu)先代碼邏輯次之最后才是環(huán)境因素。本文還有配套的精品資源點(diǎn)擊獲取