1. 項(xiàng)目概述為什么需要自己動(dòng)手集成釘釘審批如果你在企業(yè)里負(fù)責(zé)過內(nèi)部系統(tǒng)開發(fā)尤其是OA、ERP或者任何需要流程流轉(zhuǎn)的系統(tǒng)大概率會(huì)遇到一個(gè)需求把審批流從系統(tǒng)內(nèi)部“搬”到釘釘上去。幾年前我們可能還需要自己畫流程圖、設(shè)計(jì)狀態(tài)機(jī)、寫催辦提醒現(xiàn)在直接用釘釘?shù)膶徟媛犉饋硎莻€(gè)省事的方案。但真到動(dòng)手的時(shí)候你會(huì)發(fā)現(xiàn)官方文檔雖然齊全但場景碎片化一個(gè)完整的、健壯的、能直接抄作業(yè)的Java集成例子卻不好找。我最近剛做完一個(gè)采購申請同步到釘釘審批的項(xiàng)目從最初的“不就是調(diào)個(gè)API”的天真想法到后面處理各種回調(diào)、狀態(tài)同步和異常恢復(fù)踩的坑不少。這篇文章我就以一個(gè)“提交假條審批”作為例子把Java調(diào)用釘釘審批API的完整流程、核心代碼和那些文檔里不會(huì)寫的“坑”給你拆解明白。無論你是要集成請假、報(bào)銷、物品領(lǐng)用還是任何自定義審批流這里的思路和代碼都能直接復(fù)用。核心就三件事第一如何在Java里構(gòu)造請求成功發(fā)起一個(gè)釘釘審批實(shí)例第二釘釘審批完成后如何可靠地通知我們的業(yè)務(wù)系統(tǒng)第三過程中各種網(wǎng)絡(luò)超時(shí)、數(shù)據(jù)不一致的問題怎么處理。下面我們直接進(jìn)入實(shí)戰(zhàn)。2. 環(huán)境準(zhǔn)備與核心依賴梳理在開始寫代碼之前我們需要把“戰(zhàn)場”布置好。釘釘開放平臺的操作、企業(yè)內(nèi)部應(yīng)用的創(chuàng)建是后續(xù)所有API調(diào)用的基礎(chǔ)一步錯(cuò)步步錯(cuò)。2.1 釘釘開放平臺應(yīng)用創(chuàng)建與配置首先你需要有一個(gè)釘釘企業(yè)。登錄 釘釘開放平臺 在“應(yīng)用開發(fā)” - “企業(yè)內(nèi)部開發(fā)”中創(chuàng)建一個(gè)小程序或H5微應(yīng)用。這里的關(guān)鍵不是應(yīng)用類型而是獲取幾個(gè)核心憑證AppKey AppSecret這是你應(yīng)用的身份標(biāo)識和密鑰所有獲取access_token的請求都靠它。務(wù)必在代碼里妥善保管不要前端暴露。AgentId應(yīng)用代理ID在發(fā)起審批時(shí)需要。審批流程模板Code這是最容易卡住的一步。你需要先在釘釘管理后臺oa.dingtalk.com手動(dòng)創(chuàng)建一個(gè)審批模板。比如創(chuàng)建一個(gè)“員工請假審批單”里面有請假類型、開始結(jié)束時(shí)間、事由等字段。創(chuàng)建成功后你需要通過開放平臺的API/topapi/process/get_by_name或更簡單點(diǎn)在審批實(shí)例詳情頁的URL里找到這個(gè)模板唯一的processCode。這個(gè)code是后續(xù)發(fā)起審批的“模具ID”。注意這里有個(gè)大坑。釘釘管理后臺的“審批”模塊和開放平臺的“智能人事”或“審批”API模塊有時(shí)模板數(shù)據(jù)并不同步。強(qiáng)烈建議統(tǒng)一使用開放平臺提供的“創(chuàng)建審批模板”API來生成模板以保證processCode的可用性。如果使用后臺手動(dòng)創(chuàng)建的務(wù)必用API驗(yàn)證一下能否查到。2.2 項(xiàng)目依賴與基礎(chǔ)配置我們以一個(gè)標(biāo)準(zhǔn)的Spring Boot項(xiàng)目為例。主要依賴就是釘釘官方提供的Java SDK它封裝了大部分API的調(diào)用和簽名邏輯能省不少事。Maven依賴dependency groupIdcom.aliyun/groupId artifactIddingtalk/artifactId version2.0.14/version !-- 請注意使用最新版本 -- /dependency dependency groupIdorg.springframework.boot/groupId artifactIdspring-boot-starter-web/artifactId /dependency dependency groupIdorg.projectlombok/groupId artifactIdlombok/artifactId optionaltrue/optional /dependencyapplication.yml 配置dingtalk: app: app-key: your_app_key app-secret: your_app_secret agent-id: your_agent_id # 審批模板Code 根據(jù)你的實(shí)際模板填寫 process: leave-process-code: PROC-XXXXXX-YYYY-ZZZZ-ABCDEFGHIJKL這里配置了最基本的憑證。agent-id在發(fā)起審批單時(shí)用于指定應(yīng)用審批單消息會(huì)通過該應(yīng)用發(fā)送。process-code就是我們上面提到的審批模板唯一碼。3. 核心流程一發(fā)起釘釘審批實(shí)例這是流程的起點(diǎn)目標(biāo)是在Java代碼中構(gòu)造一個(gè)符合釘釘要求的請求讓釘釘為我們生成一個(gè)待審批的單據(jù)。3.1 獲取Access Token調(diào)用任何釘釘開放平臺API幾乎都需要在請求頭中攜帶access_token。這個(gè)token有有效期通常2小時(shí)需要緩存并定期刷新。我們通常會(huì)寫一個(gè)工具類來管理它。import com.dingtalk.api.DefaultDingTalkClient; import com.dingtalk.api.request.OapiGettokenRequest; import com.dingtalk.api.response.OapiGettokenResponse; import com.taobao.api.ApiException; import lombok.extern.slf4j.Slf4j; import org.springframework.beans.factory.annotation.Value; import org.springframework.stereotype.Component; import java.util.concurrent.TimeUnit; Component Slf4j public class DingTalkTokenManager { Value(${dingtalk.app.app-key}) private String appKey; Value(${dingtalk.app.app-secret}) private String appSecret; private String accessToken; private long expireTime; public String getAccessToken() throws ApiException { // 簡單的內(nèi)存緩存生產(chǎn)環(huán)境建議用Redis if (accessToken null || System.currentTimeMillis() expireTime) { refreshToken(); } return accessToken; } private synchronized void refreshToken() throws ApiException { // 雙重檢查鎖避免并發(fā)重復(fù)刷新 if (accessToken ! null System.currentTimeMillis() expireTime) { return; } DefaultDingTalkClient client new DefaultDingTalkClient(https://oapi.dingtalk.com/gettoken); OapiGettokenRequest request new OapiGettokenRequest(); request.setAppkey(appKey); request.setAppsecret(appSecret); request.setHttpMethod(GET); OapiGettokenResponse response client.execute(request); if (response.isSuccess()) { this.accessToken response.getAccessToken(); // 提前5分鐘過期避免臨界點(diǎn)請求失敗 this.expireTime System.currentTimeMillis() TimeUnit.SECONDS.toMillis(response.getExpiresIn() - 300); log.info(釘釘AccessToken刷新成功有效期至: {}, new Date(expireTime)); } else { log.error(釘釘AccessToken獲取失敗errcode:{}, errmsg:{}, response.getErrcode(), response.getErrmsg()); throw new RuntimeException(獲取釘釘Token失敗: response.getErrmsg()); } } }實(shí)操心得access_token的緩存策略至關(guān)重要。我遇到過因?yàn)楸镜貢r(shí)間不準(zhǔn)導(dǎo)致計(jì)算過期時(shí)間錯(cuò)誤所有API突然集體失效的問題。更穩(wěn)健的做法是使用Redis等分布式緩存并設(shè)置過期時(shí)間比token實(shí)際有效期少5-10分鐘。另外釘釘對access_token的調(diào)用頻率有限制頻繁獲取會(huì)觸發(fā)限流緩存是必須的。3.2 構(gòu)造并提交審批請求現(xiàn)在我們以提交一個(gè)請假審批為例看看如何構(gòu)造請求體。釘釘審批的發(fā)起API是/topapi/processinstance/create。首先定義前端提交過來的請假表單數(shù)據(jù)DTO和我們的服務(wù)層請求對象。// 1. 前端傳入的請假數(shù)據(jù) Data public class LeaveApplyDTO { private String applicantUserId; // 申請人釘釘U(kuò)serId private String leaveType; // 請假類型年假、病假、事假 private Date startTime; // 開始時(shí)間 private Date endTime; // 結(jié)束時(shí)間 private Double duration; // 時(shí)長天 private String reason; // 事由 } // 2. 釘釘表單組件值對象 (內(nèi)部使用) Data public class FormComponentValue { private String name; // 表單組件名稱需與模板內(nèi)組件名一致 private String value; // 組件的值 private String extValue; // 擴(kuò)展值如圖片/附件URL }關(guān)鍵點(diǎn)在于釘釘審批表單的數(shù)據(jù)是以一個(gè)ListFormComponentValue的格式傳遞的每個(gè)name必須和你審批模板里設(shè)計(jì)的組件id或name完全對應(yīng)。這個(gè)對應(yīng)關(guān)系最容易出錯(cuò)。接下來是服務(wù)層的核心方法Service Slf4j public class DingTalkApprovalService { Value(${dingtalk.app.agent-id}) private Long agentId; Value(${dingtalk.process.leave-process-code}) private String leaveProcessCode; Autowired private DingTalkTokenManager tokenManager; public String createLeaveApproval(LeaveApplyDTO leaveApply) throws ApiException { // 1. 獲取Token String accessToken tokenManager.getAccessToken(); // 2. 創(chuàng)建API客戶端 DefaultDingTalkClient client new DefaultDingTalkClient(https://oapi.dingtalk.com/topapi/processinstance/create); // 3. 構(gòu)建請求 OapiProcessinstanceCreateRequest request new OapiProcessinstanceCreateRequest(); request.setAgentId(agentId); // 指定應(yīng)用 request.setProcessCode(leaveProcessCode); // 指定模板 // 3.1 設(shè)置審批人這里使用審批模板默認(rèn)流程也可指定 // request.setApprovers(userIdList); // request.setCcList(ccUserIdList); // request.setCcPosition(FINISH); // 抄送時(shí)機(jī) // 3.2 構(gòu)建表單數(shù)據(jù) ListOapiProcessinstanceCreateRequest.FormComponentValueVo formList new ArrayList(); // 映射關(guān)系模板組件名 - 申請數(shù)據(jù) formList.add(buildFormComponent(請假類型, leaveApply.getLeaveType())); formList.add(buildFormComponent(開始時(shí)間, formatDate(leaveApply.getStartTime()))); formList.add(buildFormComponent(結(jié)束時(shí)間, formatDate(leaveApply.getEndTime()))); formList.add(buildFormComponent(請假時(shí)長, String.valueOf(leaveApply.getDuration()))); formList.add(buildFormComponent(請假事由, leaveApply.getReason())); // 假設(shè)模板里還有一個(gè)“申請人”組件也需要填充 formList.add(buildFormComponent(申請人, getUserName(leaveApply.getApplicantUserId()))); request.setFormComponentValues(formList); // 3.3 設(shè)置其他參數(shù) request.setOriginatorUserId(leaveApply.getApplicantUserId()); // 發(fā)起人 request.setDeptId(getUserDeptId(leaveApply.getApplicantUserId())); // 發(fā)起人部門 // request.setApproversV2(...); // 更復(fù)雜的審批人設(shè)置 // 4. 執(zhí)行請求 OapiProcessinstanceCreateResponse response client.execute(request, accessToken); if (response.isSuccess() response.getResult() ! null) { String instanceId response.getResult().getProcessInstanceId(); log.info(釘釘審批創(chuàng)建成功實(shí)例ID: {}, instanceId); // 這里要將 instanceId 保存到你的業(yè)務(wù)數(shù)據(jù)庫與你的請假單關(guān)聯(lián) return instanceId; } else { log.error(釘釘審批創(chuàng)建失敗errcode:{}, errmsg:{}, response.getErrcode(), response.getErrmsg()); throw new RuntimeException(發(fā)起釘釘審批失敗: response.getErrmsg()); } } private OapiProcessinstanceCreateRequest.FormComponentValueVo buildFormComponent(String name, String value) { OapiProcessinstanceCreateRequest.FormComponentValueVo vo new OapiProcessinstanceCreateRequest.FormComponentValueVo(); vo.setName(name); vo.setValue(value); return vo; } // ... 省略 formatDate, getUserName, getUserDeptId 等輔助方法 }注意事項(xiàng)表單組件映射setFormComponentValues中的name必須與釘釘審批模板里你拖入的每一個(gè)表單字段的“組件名稱”或“ID”一字不差地匹配。最佳實(shí)踐是在創(chuàng)建審批模板后立即通過/topapi/process/form/get接口獲取該模板的詳細(xì)表單結(jié)構(gòu)解析出每個(gè)組件的id和name在代碼里用常量定義而不是硬編碼字符串。實(shí)例ID保存返回的process_instance_id是釘釘側(cè)審批實(shí)例的唯一標(biāo)識。你必須將它和你業(yè)務(wù)系統(tǒng)的請假單ID或業(yè)務(wù)主鍵建立關(guān)聯(lián)并存入數(shù)據(jù)庫。這是后續(xù)狀態(tài)同步和回調(diào)處理的唯一依據(jù)。我見過有人忘了存結(jié)果審批完了都不知道是哪張單子只能人工去查。異常處理API調(diào)用可能因?yàn)榫W(wǎng)絡(luò)、token失效、參數(shù)錯(cuò)誤失敗。必須有重試機(jī)制特別是獲取token和清晰的錯(cuò)誤日志。釘釘?shù)腻e(cuò)誤碼errcode比較規(guī)范可以根據(jù)不同錯(cuò)誤碼進(jìn)行不同策略的重試或告警。4. 核心流程二處理審批回調(diào)通知審批提交成功只是開始。審批通過、拒絕、轉(zhuǎn)交、撤銷時(shí)我們的業(yè)務(wù)系統(tǒng)需要知道結(jié)果并更新內(nèi)部單據(jù)狀態(tài)。釘釘通過“回調(diào)”機(jī)制主動(dòng)通知我們。4.1 配置回調(diào)地址與加密密鑰在釘釘開放平臺后臺進(jìn)入你的應(yīng)用找到“事件與回調(diào)”配置。啟用回調(diào)點(diǎn)擊“設(shè)置回調(diào)地址”。填寫URL填入你服務(wù)端提供的API地址如https://your-domain.com/api/dingtalk/callback。這個(gè)地址必須能被公網(wǎng)訪問且是HTTPS正式環(huán)境。生成加密信息系統(tǒng)會(huì)生成一個(gè)aes_key和token。請務(wù)必保存好它們用于解密和驗(yàn)證釘釘發(fā)送過來的消息。訂閱事件在事件訂閱里找到“審批事件”勾選“審批任務(wù)開始、完成、轉(zhuǎn)交”等你需要的事件類型。4.2 實(shí)現(xiàn)回調(diào)接口回調(diào)接口需要做兩件事第一響應(yīng)釘釘?shù)腢RL驗(yàn)證第一次配置時(shí)第二解密并處理審批狀態(tài)變更事件。我們先添加回調(diào)處理相關(guān)的依賴SDK已包含import com.dingtalk.open.app.api.callback.DingTalkCallbackListener; import com.dingtalk.open.app.api.callback.DingTalkCallbackResponse; import com.dingtalk.open.app.api.models.business.Callback; // ... 其他import RestController RequestMapping(/api/dingtalk) Slf4j public class DingTalkCallbackController { Value(${dingtalk.callback.aes-key}) private String aesKey; Value(${dingtalk.callback.token}) private String token; Autowired private ApprovalCallbackService approvalCallbackService; /** * 釘釘事件回調(diào)入口 */ PostMapping(/callback) public MapString, String callback(RequestParam(value signature, required false) String signature, RequestParam(value timestamp, required false) String timestamp, RequestParam(value nonce, required false) String nonce, RequestBody(required false) String body) { try { // 1. 使用SDK提供的工具類解密并處理回調(diào) DingTalkCallbackListener callbackListener new DingTalkCallbackListener(token, aesKey); Callback callback callbackListener.listen(body, signature, timestamp, nonce); // 2. 判斷回調(diào)類型 if (check_url.equals(callback.getType())) { // URL驗(yàn)證回調(diào)直接返回success log.info(釘釘回調(diào)URL驗(yàn)證成功); return Collections.singletonMap(msg, success); } else if (event_callback.equals(callback.getType())) { // 事件回調(diào) handleEventCallback(callback); return Collections.singletonMap(msg, success); } } catch (Exception e) { log.error(處理釘釘回調(diào)異常, e); // 返回失敗釘釘會(huì)重試 throw new RuntimeException(處理回調(diào)失敗); } return Collections.singletonMap(msg, success); } private void handleEventCallback(Callback callback) { String eventType callback.getEventType(); Object eventData callback.getData(); log.info(收到釘釘回調(diào)事件類型: {}, 數(shù)據(jù): {}, eventType, JSON.toJSONString(eventData)); if (bpms_instance_change.equals(eventType)) { // 審批實(shí)例狀態(tài)變更 approvalCallbackService.handleInstanceChange(eventData); } else if (bpms_task_change.equals(eventType)) { // 審批任務(wù)狀態(tài)變更如轉(zhuǎn)交 approvalCallbackService.handleTaskChange(eventData); } // ... 處理其他事件類型 } }4.3 解析事件并更新業(yè)務(wù)狀態(tài)ApprovalCallbackService是業(yè)務(wù)處理的核心。我們需要解析釘釘傳過來的復(fù)雜JSON找到關(guān)鍵的實(shí)例ID和結(jié)果。Service Slf4j public class ApprovalCallbackService { Autowired private YourBusinessOrderService orderService; // 你的業(yè)務(wù)單據(jù)服務(wù) public void handleInstanceChange(Object eventData) { // 1. 解析事件數(shù)據(jù) (這里需要根據(jù)釘釘回調(diào)格式定義DTO) String jsonStr JSON.toJSONString(eventData); BpmsInstanceChangeEvent event JSON.parseObject(jsonStr, BpmsInstanceChangeEvent.class); // 2. 獲取關(guān)鍵信息 String instanceId event.getProcessInstanceId(); String businessId event.getBusinessId(); // 即我們發(fā)起時(shí)傳入的“第三方業(yè)務(wù)ID”可選 String type event.getType(); // 事件類型start, finish, terminate(終止) String result event.getResult(); // 當(dāng)typefinish時(shí)才有agree, refuse log.info(審批實(shí)例變更 - instanceId:{}, type:{}, result:{}, instanceId, type, result); // 3. 根據(jù)實(shí)例ID查詢我們本地存儲(chǔ)的關(guān)聯(lián)業(yè)務(wù)單 // 這里假設(shè)我們有一個(gè) approval_record 表存儲(chǔ)了 instance_id 和 business_order_id 的映射 String orderId findOrderIdByInstanceId(instanceId); if (orderId null) { log.warn(未找到與釘釘審批實(shí)例[{}]關(guān)聯(lián)的業(yè)務(wù)單可能數(shù)據(jù)不同步, instanceId); // 觸發(fā)告警或人工介入 return; } // 4. 更新業(yè)務(wù)單狀態(tài) if (finish.equals(type)) { if (agree.equals(result)) { orderService.approveOrder(orderId, 釘釘審批通過); } else if (refuse.equals(result)) { orderService.rejectOrder(orderId, 釘釘審批拒絕 - event.getRemark()); } } else if (terminate.equals(type)) { orderService.cancelOrder(orderId, 釘釘審批被撤銷); } // start 事件通常用于記錄流程開始可不更新主狀態(tài) } // 根據(jù)釘釘實(shí)例ID查找本地業(yè)務(wù)單ID private String findOrderIdByInstanceId(String instanceId) { // 實(shí)現(xiàn)你的數(shù)據(jù)庫查詢邏輯 // return approvalRecordRepository.findByInstanceId(instanceId).getOrderId(); return query_from_db_logic_here; } } // 釘釘審批實(shí)例變更事件DTO (簡化版需根據(jù)實(shí)際回調(diào)JSON結(jié)構(gòu)定義完整字段) Data class BpmsInstanceChangeEvent { private String processInstanceId; private String businessId; private String type; // start, finish, terminate private String result; // agree, refuse private String remark; private Long createTime; private Long finishTime; }踩坑實(shí)錄回調(diào)重復(fù)與冪等釘釘為了確保消息必達(dá)可能會(huì)在短時(shí)間內(nèi)發(fā)送重復(fù)的回調(diào)。你的handleInstanceChange方法必須是冪等的。也就是說即使收到同一個(gè)instanceId的finish事件兩次你的業(yè)務(wù)邏輯如更新訂單狀態(tài)也只能成功執(zhí)行一次。實(shí)現(xiàn)方法在處理前先檢查本地該單據(jù)是否已處于目標(biāo)狀態(tài)或者利用數(shù)據(jù)庫唯一約束/樂觀鎖。網(wǎng)絡(luò)超時(shí)與重試你的回調(diào)接口必須在1500ms內(nèi)響應(yīng)成功否則釘釘會(huì)認(rèn)為失敗并進(jìn)行重試。因此復(fù)雜的數(shù)據(jù)庫操作或同步調(diào)用應(yīng)該放入消息隊(duì)列或線程池異步處理接口先快速返回“success”。我吃過虧因?yàn)橥桨l(fā)郵件導(dǎo)致接口超時(shí)釘釘瘋狂重試刷爆了日志。數(shù)據(jù)一致性回調(diào)處理時(shí)可能因?yàn)榫W(wǎng)絡(luò)分區(qū)或服務(wù)重啟導(dǎo)致instanceId查不到本地關(guān)聯(lián)單。這時(shí)要有補(bǔ)償機(jī)制比如定期如每小時(shí)調(diào)用釘釘?shù)?topapi/processinstance/get接口拉取狀態(tài)為“運(yùn)行中”的審批單與本地單據(jù)比對修復(fù)缺失的關(guān)聯(lián)或狀態(tài)。5. 核心流程三狀態(tài)主動(dòng)查詢與補(bǔ)償機(jī)制不能完全依賴回調(diào)。網(wǎng)絡(luò)抖動(dòng)、你的服務(wù)短暫不可用、回調(diào)配置錯(cuò)誤等都可能導(dǎo)致狀態(tài)不同步。一個(gè)健壯的系統(tǒng)必須有主動(dòng)拉取Pull的補(bǔ)償機(jī)制。5.1 定時(shí)任務(wù)同步審批狀態(tài)我們可以創(chuàng)建一個(gè)定時(shí)任務(wù)比如每10分鐘運(yùn)行一次掃描本地所有“審批中”狀態(tài)的業(yè)務(wù)單去釘釘查詢最新狀態(tài)。Component Slf4j public class ApprovalStatusSyncTask { Autowired private DingTalkApprovalService dingTalkService; Autowired private YourBusinessOrderService orderService; Scheduled(cron 0 */10 * * * ?) // 每10分鐘一次 public void syncPendingApprovals() { log.info(開始執(zhí)行釘釘審批狀態(tài)同步任務(wù)); // 1. 從數(shù)據(jù)庫查詢所有狀態(tài)為“審批中”且關(guān)聯(lián)了釘釘instanceId的單據(jù) ListPendingApprovalOrder pendingOrders orderService.findPendingOrdersWithInstanceId(); for (PendingApprovalOrder order : pendingOrders) { try { // 2. 調(diào)用釘釘API查詢實(shí)例詳情 ProcessInstanceDetail detail dingTalkService.getProcessInstanceDetail(order.getInstanceId()); if (detail null) { log.warn(釘釘審批實(shí)例[{}]查詢無結(jié)果可能已被刪除, order.getInstanceId()); orderService.markOrderAsException(order.getId(), 審批實(shí)例不存在); continue; } // 3. 判斷狀態(tài)并更新 String status detail.getStatus(); // NEW, RUNNING, TERMINATED, COMPLETED, CANCELED if (COMPLETED.equals(status)) { String result detail.getResult(); // agree, refuse if (agree.equals(result)) { orderService.approveOrder(order.getId(), 定時(shí)同步-審批通過); } else { orderService.rejectOrder(order.getId(), 定時(shí)同步-審批拒絕); } } else if (TERMINATED.equals(status) || CANCELED.equals(status)) { orderService.cancelOrder(order.getId(), 定時(shí)同步-審批已終止); } // RUNNING 狀態(tài)無需處理等待回調(diào)或下次同步 } catch (ApiException e) { // 釘釘API調(diào)用異常記錄日志單條失敗不影響其他任務(wù) log.error(同步審批單[{}]狀態(tài)失敗instanceId:{}, order.getId(), order.getInstanceId(), e); // 可以根據(jù)錯(cuò)誤碼判斷如果是實(shí)例不存在等錯(cuò)誤更新本地狀態(tài) if (e.getErrCode() ! null e.getErrCode().equals(400)) { // 具體判斷錯(cuò)誤信息可能是“審批實(shí)例不存在” orderService.markOrderAsException(order.getId(), 審批實(shí)例查詢異常); } } catch (Exception e) { log.error(處理審批單[{}]同步時(shí)發(fā)生未知異常, order.getId(), e); } } log.info(釘釘審批狀態(tài)同步任務(wù)結(jié)束); } }5.2 查詢審批實(shí)例詳情的實(shí)現(xiàn)DingTalkApprovalService中需要補(bǔ)充查詢實(shí)例詳情的方法public ProcessInstanceDetail getProcessInstanceDetail(String instanceId) throws ApiException { String accessToken tokenManager.getAccessToken(); DefaultDingTalkClient client new DefaultDingTalkClient(https://oapi.dingtalk.com/topapi/processinstance/get); OapiProcessinstanceGetRequest req new OapiProcessinstanceGetRequest(); req.setProcessInstanceId(instanceId); OapiProcessinstanceGetResponse rsp client.execute(req, accessToken); if (rsp.isSuccess() rsp.getProcessInstance() ! null) { // 將釘釘返回的復(fù)雜對象轉(zhuǎn)換為我們自定義的簡化DTO return convertToDetail(rsp.getProcessInstance()); } else if (400.equals(rsp.getErrcode()) rsp.getErrmsg().contains(不存在)) { // 實(shí)例不存在 return null; } else { log.error(查詢審批實(shí)例詳情失敗instanceId:{}, errcode:{}, errmsg:{}, instanceId, rsp.getErrcode(), rsp.getErrmsg()); throw new ApiException(rsp.getErrcode(), rsp.getErrmsg()); } }經(jīng)驗(yàn)技巧頻率控制主動(dòng)查詢API有調(diào)用頻率限制企業(yè)維度。定時(shí)任務(wù)的間隔不宜過短10-30分鐘是比較安全的選擇。對于單據(jù)量大的系統(tǒng)可以按時(shí)間分片查詢避免集中調(diào)用。異常處理精細(xì)化查詢API可能返回“審批實(shí)例不存在”可能被手動(dòng)刪除。這時(shí)應(yīng)該更新本地單據(jù)狀態(tài)為“異常終止”并觸發(fā)告警通知管理員檢查。數(shù)據(jù)兜底這個(gè)補(bǔ)償機(jī)制是數(shù)據(jù)最終一致性的重要保障。即使回調(diào)完全失效最遲在下一個(gè)同步周期業(yè)務(wù)狀態(tài)也能被修正。6. 進(jìn)階話題與性能優(yōu)化當(dāng)你的審批集成跑起來后隨著業(yè)務(wù)量增長可能會(huì)遇到性能和擴(kuò)展性問題。6.1 審批人動(dòng)態(tài)指定與或簽/會(huì)簽上面的例子使用了審批模板的默認(rèn)流程。更復(fù)雜的場景需要?jiǎng)討B(tài)指定審批人甚至設(shè)置或簽任一通過、會(huì)簽全部通過。在發(fā)起審批請求 (OapiProcessinstanceCreateRequest) 時(shí)可以使用approvers_v2字段進(jìn)行更精細(xì)的控制。// 構(gòu)建審批人節(jié)點(diǎn)列表 ListOapiProcessinstanceCreateRequest.ApproversV2 approversV2List new ArrayList(); // 第一個(gè)審批節(jié)點(diǎn)部門經(jīng)理或簽多個(gè)人選一個(gè) OapiProcessinstanceCreateRequest.ApproversV2 node1 new OapiProcessinstanceCreateRequest.ApproversV2(); node1.setUserIds(Arrays.asList(manager_userid_1, manager_userid_2)); // 備選審批人 node1.setTaskActionType(OR); // OR表示或簽AND表示會(huì)簽 approversV2List.add(node1); // 第二個(gè)審批節(jié)點(diǎn)財(cái)務(wù)單人 OapiProcessinstanceCreateRequest.ApproversV2 node2 new OapiProcessinstanceCreateRequest.ApproversV2(); node2.setUserIds(Collections.singletonList(finance_userid)); node2.setTaskActionType(AND); // 單人時(shí)AND或OR均可 approversV2List.add(node2); request.setApproversV2(approversV2List);注意動(dòng)態(tài)指定審批人需要你的應(yīng)用擁有相應(yīng)的通訊錄權(quán)限并且能獲取到審批人的userid。同時(shí)審批模板的流程設(shè)置需要支持“由發(fā)起人指定”或“接口指定”否則動(dòng)態(tài)設(shè)置可能不生效。6.2 高并發(fā)下的Token管理與API調(diào)用當(dāng)你的系統(tǒng)有多個(gè)服務(wù)節(jié)點(diǎn)或者審批提交量很大時(shí)內(nèi)存緩存的Token就不夠用了。分布式Token緩存將Token存入Redis并設(shè)置合理的過期時(shí)間。所有服務(wù)節(jié)點(diǎn)都從Redis讀取。刷新Token時(shí)需要使用分布式鎖如Redis的SETNX確保只有一個(gè)節(jié)點(diǎn)去調(diào)用釘釘API刷新刷新成功后更新Redis。API調(diào)用熔斷與降級使用Resilience4j或Sentinel等工具對釘釘API調(diào)用特別是create和get配置熔斷器。當(dāng)釘釘服務(wù)不穩(wěn)定或達(dá)到限流閾值時(shí)快速失敗避免線程池被拖垮。降級策略可以是將審批請求暫存到本地隊(duì)列記錄日志并提示用戶“審批系統(tǒng)繁忙已提交后臺處理”。異步化提交對于提交審批這個(gè)動(dòng)作如果對實(shí)時(shí)性要求不是極高可以采用“異步提交”模式。用戶提交申請后立即返回成功實(shí)際發(fā)起釘釘審批的操作放入消息隊(duì)列如RocketMQ、RabbitMQ由消費(fèi)者異步執(zhí)行。這樣可以削峰填谷提高系統(tǒng)整體吞吐量也便于失敗重試。6.3 審批表單數(shù)據(jù)回傳與業(yè)務(wù)關(guān)聯(lián)有時(shí)審批人在釘釘審批時(shí)修改了表單內(nèi)容如調(diào)整了金額我們需要把這些修改同步回業(yè)務(wù)系統(tǒng)。這需要在審批模板設(shè)計(jì)時(shí)為需要回傳的字段勾選“允許修改”。在審批完成的回調(diào)事件 (bpms_instance_changewithtypefinish) 中釘釘會(huì)返回完整的表單數(shù)據(jù) (form_component_values)。你需要解析這個(gè)列表找到被修改的字段更新到你的業(yè)務(wù)數(shù)據(jù)中。解析回調(diào)數(shù)據(jù)中的表單值示例// 在 BpmsInstanceChangeEvent 中增加表單數(shù)據(jù)字段 private ListFormValue formComponentValues; // 解析并查找特定字段 public void updateBusinessData(BpmsInstanceChangeEvent event) { String newAmount event.getFormComponentValues().stream() .filter(f - 報(bào)銷金額.equals(f.getName())) .map(FormValue::getValue) .findFirst() .orElse(null); if (newAmount ! null) { // 更新業(yè)務(wù)單據(jù)的金額 orderService.updateOrderAmount(event.getBusinessId(), new BigDecimal(newAmount)); } }這個(gè)過程比單純同步狀態(tài)要復(fù)雜需要仔細(xì)設(shè)計(jì)數(shù)據(jù)映射和更新策略確保數(shù)據(jù)一致性。7. 常見問題排查與調(diào)試技巧在實(shí)際開發(fā)和運(yùn)維中你會(huì)遇到各種各樣的問題。這里列幾個(gè)我印象最深的。7.1 問題排查清單問題現(xiàn)象可能原因排查步驟發(fā)起審批返回400錯(cuò)誤信息含糊1. 表單組件名稱不匹配。2. 必填字段未傳值。3. 字段值格式錯(cuò)誤如日期格式。1. 用/topapi/process/form/get接口核對模板表單結(jié)構(gòu)。2. 檢查請求體JSON確保所有模板中標(biāo)記為必填的組件都已傳值。3. 日期時(shí)間字段需轉(zhuǎn)為“yyyy-MM-dd HH:mm:ss”字符串。收不到回調(diào)通知1. 回調(diào)URL配置錯(cuò)誤或網(wǎng)絡(luò)不通。2. 回調(diào)服務(wù)響應(yīng)超時(shí)1500ms。3. 加解密失敗。1. 在釘釘后臺重新保存回調(diào)配置觸發(fā)URL驗(yàn)證檢查服務(wù)端日志。2. 優(yōu)化回調(diào)接口性能異步處理業(yè)務(wù)邏輯。3. 確認(rèn)aes_key和token與后臺配置完全一致注意首尾空格。回調(diào)重復(fù)接收釘釘?shù)南⒈Ｕ蠙C(jī)制。實(shí)現(xiàn)回調(diào)處理邏輯的冪等性。根據(jù)processInstanceId和eventType、createTime判斷是否已處理過。查詢審批詳情返回“審批實(shí)例不存在”1.instanceId錯(cuò)誤或未保存。2. 審批實(shí)例已被徹底刪除。3. 應(yīng)用權(quán)限不足。1. 檢查數(shù)據(jù)庫關(guān)聯(lián)記錄。2. 確認(rèn)是否有人在釘釘后臺刪除了該審批單。3. 檢查應(yīng)用是否有“審批實(shí)例讀取”權(quán)限。審批人收不到待辦通知1. 發(fā)起請求中未設(shè)置agent_id或設(shè)置錯(cuò)誤。2. 審批人不在應(yīng)用的可見范圍。3. 審批人未安裝該應(yīng)用。1. 確認(rèn)發(fā)起請求的agent_id是發(fā)送通知的應(yīng)用。2. 在釘釘后臺檢查應(yīng)用的可使用范圍部門/人員。3. 通知審批人在工作臺添加該應(yīng)用。7.2 調(diào)試技巧使用釘釘開發(fā)者工具釘釘開放平臺后臺提供了“接口調(diào)試工具”你可以在這里手動(dòng)填入?yún)?shù)發(fā)起調(diào)用快速驗(yàn)證API功能和參數(shù)格式比寫代碼測試更快。日志記錄完整請求響應(yīng)在開發(fā)階段將DefaultDingTalkClient執(zhí)行的完整請求URL、Header、Body和響應(yīng)Body打印到日志中。釘釘SDK通常有日志開關(guān)或者你可以通過設(shè)置HTTP代理如Charles來抓包分析。模擬回調(diào)釘釘后臺提供了“事件推送測試”功能可以手動(dòng)模擬發(fā)送各種事件到你的回調(diào)地址這是測試回調(diào)邏輯最直接的方法。關(guān)注錯(cuò)誤碼釘釘?shù)腻e(cuò)誤碼如400通常附帶一個(gè)中文的errmsg信息比較明確。將其記錄到告警系統(tǒng)便于快速定位問題。整個(gè)集成過程從簡單的API調(diào)用到構(gòu)建一個(gè)穩(wěn)定、可靠的生產(chǎn)級系統(tǒng)需要考慮的細(xì)節(jié)非常多。核心思路就是發(fā)起時(shí)關(guān)聯(lián)好回調(diào)時(shí)處理快丟掉了能找回來。把這三個(gè)環(huán)節(jié)做扎實(shí)釘釘審批集成就能成為你業(yè)務(wù)系統(tǒng)中一個(gè)穩(wěn)定可靠的流程引擎而不是一個(gè)時(shí)不時(shí)需要人工干預(yù)的“坑”。