簡(jiǎn)介Activiti 5.17.0 官方工作流引擎資源包面向需要實(shí)現(xiàn)企業(yè)級(jí)流程自動(dòng)化的 Java 開發(fā)人員、流程架構(gòu)師與系統(tǒng)運(yùn)維者可基于 BPMN 2.0 搭建流程模型并借助引擎完成流程實(shí)例調(diào)度、任務(wù)分配與狀態(tài)查詢適用于審批、工單、項(xiàng)目管理等常見場(chǎng)景。壓縮包為 zip 格式整體約 69.35MB內(nèi)容涵蓋官方發(fā)布的 jar 運(yùn)行文件、源代碼與離線手冊(cè)包內(nèi)文件組織清晰便于按需檢索既可直接引入項(xiàng)目運(yùn)行也可對(duì)照源碼研究流程引擎核心機(jī)制。目前已有 202 人學(xué)習(xí)瀏覽有助于從入門到進(jìn)階掌握 Activiti。該版本重點(diǎn)關(guān)注流程定義與模型設(shè)計(jì)、引擎 API 使用、任務(wù)與分支并發(fā)處理、動(dòng)態(tài)表單關(guān)聯(lián)、事件監(jiān)聽與自定義行為等知識(shí)點(diǎn)同時(shí)可學(xué)習(xí)與 Spring、Hibernate 的整合方式以及 REST API、事務(wù)管理、數(shù)據(jù)庫(kù)持久化等工程化能力使開發(fā)者能夠快速將流程引擎融入業(yè)務(wù)系統(tǒng)。借助源碼與手冊(cè)開發(fā)者能深入理解 Activiti 5.17.0 的整體結(jié)構(gòu)為后續(xù)基于該框架的業(yè)務(wù)流程二次開發(fā)提供可靠參考。1. activiti-5.17.0 到底是個(gè)什么版本先給一句判斷如果你所在的團(tuán)隊(duì)接手了一套 2015 年前后的審批系統(tǒng)大概率會(huì)看到一個(gè)老熟人activiti-5.17.0。它沒有 7.x 的云原生概念也不帶 Spring Boot 的自動(dòng)配置但核心能力一個(gè)不少流程部署、任務(wù)流轉(zhuǎn)、會(huì)簽、駁回、條件分支、歷史查詢?nèi)繐蔚米?。真正讓人翻車的地方集中在三處?Spring 版本的配合、數(shù)據(jù)庫(kù)表名大小寫、以及 BPMN 文件里的命名空間細(xì)節(jié)。這篇筆記會(huì)順著“搭環(huán)境 → 跑通一條流程 → 審批流轉(zhuǎn) → 避坑 → 批量處理技巧”的順序講透每一段都給出能直接復(fù)制的代碼和參數(shù)。適合兩類人看剛接手存量系統(tǒng)、被歷史代碼追著跑的新人以及正在評(píng)估“老版本值不值得繼續(xù)投入”的架構(gòu)師。2. 先把引擎跑起來依賴、配置與建表動(dòng)作Activiti 5.17.0 的引擎核心是一個(gè)重量級(jí)對(duì)象 ProcessEngine它負(fù)責(zé)管理所有的 Service部署、運(yùn)行時(shí)、任務(wù)、歷史、身份所有操作都從它身上拿。這一章不碰 Spring先把“裸引擎”跑起來目的是確認(rèn)依賴、數(shù)據(jù)庫(kù)和建表策略這三件事都正確。這一步通了后面接 Spring 還是接別的容器都只是裝配問題。2.1 依賴怎么加兩個(gè)坐標(biāo)別加多先看 Maven 依賴。5.17.0 的坐標(biāo)和 7.x 不一樣核心是這個(gè)dependency groupIdorg.activiti/groupId artifactIdactiviti-engine/artifactId version5.17.0/version /dependency !-- 如果要接 Spring 3/4再加這個(gè)不要重復(fù)引入 engine -- dependency groupIdorg.activiti/groupId artifactIdactiviti-spring/artifactId version5.17.0/version /dependency這里有個(gè)常見誤操作有人為了“保險(xiǎn)”把 activiti-engine、activiti-spring、activiti-bpmn-converter 一次性全引進(jìn)來結(jié)果 classpath 里出現(xiàn)同一類的多個(gè)版本啟動(dòng)時(shí)直接 NoSuchMethodError。5.17.0 的依賴管理沒有 7.x 那么完善engine 自己帶了模型解析、BPMN 轉(zhuǎn)換、MyBatis 映射正常業(yè)務(wù)不需要額外加解析模塊。參數(shù)說明activiti-engine 內(nèi)部會(huì)傳遞依賴 mybatis 和 spring-expression如果你的項(xiàng)目里已經(jīng)用了另一個(gè)版本的 mybatis這里大概率會(huì)沖突。我一般會(huì)在引入后先跑一次mvn dependency:tree -Dincludesorg.activiti看實(shí)際的依賴樹確認(rèn)沒有兩個(gè)版本的 engine 并存。這個(gè)習(xí)慣能省掉后面一小時(shí)的排查時(shí)間。2.2 引擎配置數(shù)據(jù)庫(kù)連接和建表策略5.17.0 提供了獨(dú)立的配置類 ProcessEngineConfiguration可以通過 Java 代碼直接構(gòu)建引擎這是最小化驗(yàn)證的最佳路徑不依賴 web 容器、不依賴 Spring 上下文。import org.activiti.engine.ProcessEngine; import org.activiti.engine.ProcessEngineConfiguration; public class EngineBootstrap { public static void main(String[] args) { ProcessEngineConfiguration config ProcessEngineConfiguration .createStandaloneProcessEngineConfiguration() // MySQL 連接串注意 UTF-8 參數(shù) .setJdbcUrl(jdbc:mysql://localhost:3306/activiti_test?useUnicodetruecharacterEncodingutf8) .setJdbcDriver(com.mysql.jdbc.Driver) .setJdbcUsername(root) .setJdbcPassword(root) // true 沒有表就自動(dòng)創(chuàng)建false 不建表drop-create 每次刪了重建 .setDatabaseSchemaUpdate(ProcessEngineConfiguration.DB_SCHEMA_UPDATE_TRUE) // 歷史級(jí)別full 記錄最全none 完全不記錄 .setHistoryLevel(ProcessEngineConfiguration.HISTORY_FULL); ProcessEngine processEngine config.buildProcessEngine(); System.out.println(Engine name: processEngine.getName()); } }邏輯說明createStandaloneProcessEngineConfiguration()創(chuàng)建的是一個(gè)不依賴事務(wù)管理器、不依賴數(shù)據(jù)源的“獨(dú)立引擎配置”適合工具類、命令行腳本、單元測(cè)試。如果直接接 Spring應(yīng)該換成createProcessEngineConfigurationFromResource(activiti.cfg.xml)或者用 Spring 的SpringProcessEngineConfiguration但這不影響建表邏輯。參數(shù)說明setDatabaseSchemaUpdate有三個(gè)值生產(chǎn)環(huán)境我強(qiáng)烈建議用false并手工執(zhí)行官方 SQL 腳本而不是讓引擎每次啟動(dòng)都去探測(cè)表結(jié)構(gòu)。setHistoryLevel默認(rèn)是HISTORY_AUDIT記錄流程實(shí)例、活動(dòng)實(shí)例、任務(wù)、變量但跳過流程變量更新明細(xì)如果不需要?dú)v史數(shù)據(jù)改成HISTORY_NONE能顯著減少寫入量。這里先保持 FULL方便后面的章節(jié)驗(yàn)證歷史查詢。2.3 驗(yàn)證引擎真的初始化成功引擎啟動(dòng)成功不等于表都建對(duì)了。5.17.0 默認(rèn)會(huì)創(chuàng)建一組以 ACT_ 開頭的表分布在幾個(gè)域里ACT_RE_流程定義和流程模型、ACT_RU_運(yùn)行時(shí)、ACT_HI_歷史、ACT_ID_身份信息、ACT_GE_通用數(shù)據(jù)。驗(yàn)證方式直接查數(shù)據(jù)庫(kù)SELECT table_name FROM information_schema.tables WHERE table_schema activiti_test AND table_name LIKE ACT\_%;正常情況下列表里應(yīng)該同時(shí)出現(xiàn) ACT_RE_PROCDEF、ACT_RU_TASK、ACT_HI_PROCINST、ACT_GE_BYTEARRAY 這些核心表。如果一張表都沒有先確認(rèn)數(shù)據(jù)庫(kù)賬號(hào)有建表權(quán)限如果只建了一半就停下大概率是字符集或表名大小寫問題這部分在第 5 章細(xì)說。這一步還有一個(gè)容易被忽略的點(diǎn)buildProcessEngine()默認(rèn)創(chuàng)建的引擎 id 是default。如果同進(jìn)程里再次調(diào)用同樣代碼會(huì)得到同一個(gè)引擎實(shí)例單例緩存而不是重新建一遍。你可以在跑完代碼后調(diào)用System.out.println(ProcessEngines.getProcessEngines().keySet());看到輸出里有default說明引擎已經(jīng)注冊(cè)到全局緩存。后續(xù)代碼里直接ProcessEngines.getDefaultProcessEngine()就能拿到同一個(gè)實(shí)例不需要重新配置。這也是為什么很多基于 5.17.0 的老項(xiàng)目工具類里到處是ProcessEngines.getDefaultProcessEngine()的原因。3. 讓第一個(gè)流程實(shí)例跑通BPMN、部署與啟動(dòng)參數(shù)引擎起來后下一件事是部署一條真實(shí)流程。這一章用手寫 BPMN 文件的方式走完全流程寫文件 → 部署 → 查詢流程定義 → 啟動(dòng)實(shí)例。整個(gè)過程里最容易出錯(cuò)的不是 Java 代碼而是 XML 文件里的命名空間和表達(dá)式寫法。3.1 一個(gè)能直接用的請(qǐng)假審批流程 BPMN下面這個(gè)文件是略去布局信息的最小 BPMN 2.0 流程包含一個(gè)開始事件、兩個(gè)用戶任務(wù)、一個(gè)排他網(wǎng)關(guān)、一個(gè)結(jié)束事件。注意文件后綴用.bpmn20.xml這是 5.17.0 部署時(shí)識(shí)別最穩(wěn)的命名方式。?xml version1.0 encodingUTF-8? definitions xmlnshttp://www.omg.org/spec/BPMN/20100524/MODEL xmlns:activitihttp://activiti.org/bpmn targetNamespacehttp://example.com/leave process idleaveProcess name請(qǐng)假審批流程 isExecutabletrue startEvent idstart name開始/ sequenceFlow idflow1 sourceRefstart targetRefapply/ userTask idapply name提交請(qǐng)假申請(qǐng) activiti:assignee${submitter}/ sequenceFlow idflow2 sourceRefapply targetRefapprove/ userTask idapprove name審批 activiti:assignee${approver}/ sequenceFlow idflow3 sourceRefapprove targetRefgateway/ exclusiveGateway idgateway name是否通過/ sequenceFlow idflowPass sourceRefgateway targetRefend conditionExpression xsi:typetFormalExpression${approved true}/conditionExpression /sequenceFlow sequenceFlow idflowReject sourceRefgateway targetRefapply conditionExpression xsi:typetFormalExpression${approved false}/conditionExpression /sequenceFlow endEvent idend name結(jié)束/ /process /definitions兩個(gè)新手必踩的點(diǎn)第一activiti:前綴的命名空間聲明不能漏activiti:assignee依賴它漏了會(huì)直接部署失敗第二${approved true}這種表達(dá)式是 JUEL 語(yǔ)法布爾值直接比較就行不用加引號(hào)。字符串比較才需要引號(hào)比如${approved true}。我把這份文件放在src/main/resources/diagrams/leave.bpmn20.xml下接下來用它做部署測(cè)試。3.2 部署流程定義關(guān)鍵在 latestVersion部署動(dòng)作由 RepositoryService 負(fù)責(zé)。部署的本質(zhì)是把 BPMN 文件打包成一個(gè) Deployment 對(duì)象入庫(kù)引擎再?gòu)闹薪馕龀?ProcessDefinition。同一個(gè)流程如果部署兩次會(huì)生成兩個(gè)版本但 key 相同。RepositoryService repositoryService processEngine.getRepositoryService(); // 部署addClasspathResource 可以多次調(diào)用支持一個(gè)包帶多個(gè)文件 Deployment deployment repositoryService.createDeployment() .addClasspathResource(diagrams/leave.bpmn20.xml) .name(請(qǐng)假流程) .deploy(); // 查詢最新版本的流程定義 ProcessDefinition definition repositoryService.createProcessDefinitionQuery() .processDefinitionKey(leaveProcess) .latestVersion() .singleResult(); System.out.println(流程定義ID: definition.getId()); System.out.println(版本號(hào): definition.getVersion());邏輯說明processDefinitionKey對(duì)應(yīng) BPMN 文件里process idleaveProcess這個(gè) id不是文件名。latestVersion()會(huì)按 key 分組取版本號(hào)最大的那個(gè)這個(gè)限定在重復(fù)部署后尤其重要否則singleResult()會(huì)因?yàn)椴榈蕉嘈卸鴴伄惓！eployment.getId()和definition.getId()是兩回事前者是部署包 id后者是流程定義 id格式通常像leaveProcess:1:某個(gè)數(shù)字。啟動(dòng)流程實(shí)例時(shí)用的是 key 或定義 id不是部署 id。3.3 啟動(dòng)流程實(shí)例businessKey 和 variables 的配合流程定義是“圖紙”流程實(shí)例是“按圖紙跑起來的具體業(yè)務(wù)”。啟動(dòng)時(shí)通常要傳兩個(gè)東西業(yè)務(wù)單據(jù)編號(hào)businessKey和流程變量variables。業(yè)務(wù)上最典型的例子是“工單號(hào)或請(qǐng)假單號(hào)”。RuntimeService runtimeService processEngine.getRuntimeService(); IdentityService identityService processEngine.getIdentityService(); MapString, Object variables new HashMap(); variables.put(submitter, user01); variables.put(approver, user02); variables.put(days, 2); ProcessInstance processInstance runtimeService.startProcessInstanceByKey( leaveProcess, LEAVE-2024-001, variables); System.out.println(流程實(shí)例ID: processInstance.getId()); System.out.println(業(yè)務(wù)編號(hào): processInstance.getBusinessKey());參數(shù)說明startProcessInstanceByKey有三個(gè)重載版本第二個(gè)參數(shù)是 businessKey第三個(gè)是 variables。businessKey 建議填業(yè)務(wù)單據(jù)的唯一編號(hào)不要填自增數(shù)字后續(xù)用historicProcessInstanceQuery().processInstanceBusinessKey(LEAVE-2024-001)可以精確找回這個(gè)實(shí)例關(guān)聯(lián)的所有歷史數(shù)據(jù)。這里的 variables 會(huì)直接影響流程走向submitter決定第一個(gè)用戶任務(wù)的辦理人approver決定審批任務(wù)的辦理人。如果漏了這兩個(gè)變量任務(wù)是能創(chuàng)建出來的但 assignee 字段是空的這幫任務(wù)不會(huì)出現(xiàn)在任何人的待辦列表里只能靠taskQuery().taskUnassigned()撈出來——這是第 5 章要展開講的一個(gè)經(jīng)典坑。還有一點(diǎn)要注意identityService.setAuthenticatedUserId(user01)這行在某些團(tuán)隊(duì)代碼里會(huì)出現(xiàn)作用是為歷史記錄里“發(fā)起人”字段賦值不是流程執(zhí)行的必需條件。老系統(tǒng)里常見但無關(guān)流程能否跑通建議把它和業(yè)務(wù)操作解耦。4. 審批流轉(zhuǎn)的三種常用姿勢(shì)任務(wù)、變量、會(huì)簽與駁回流程實(shí)例啟動(dòng)后真正的業(yè)務(wù)量都在“審批”上。這一章覆蓋三個(gè)最常見訴求普通單人審批、條件網(wǎng)關(guān)分支、會(huì)簽和駁回。5.17.0 在 API 上非常直白但表達(dá)式的細(xì)節(jié)決定流程走的對(duì)不對(duì)。4.1 待辦任務(wù)查詢與 complete 的完整鏈路審批人打開待辦列表本質(zhì)是查詢 ACT_RU_TASK 表里 assignee 等于自己或者候選人是自己的任務(wù)。完成審批則有兩條路直接 complete或先 setAssignee 再 complete。代碼如下TaskService taskService processEngine.getTaskService(); // 查詢 user02 的待辦任務(wù) ListTask tasks taskService.createTaskQuery() .taskAssignee(user02) .orderByTaskCreateTime() .desc() .list(); for (Task task : tasks) { System.out.println(task.getId() - task.getName()); } // 完成第一個(gè)任務(wù)并傳遞審批結(jié)果變量 Task task tasks.get(0); MapString, Object taskVars new HashMap(); taskVars.put(approved, true); taskService.complete(task.getId(), taskVars);邏輯說明taskAssignee(user02)查的是辦理人已經(jīng)明確分配給 user02 的任務(wù)。如果團(tuán)隊(duì)用候選人模式比如任務(wù)分配給一個(gè)角色組需要改成taskCandidateUser(user02)并且 complete 時(shí)引擎會(huì)校驗(yàn) user02 是否是候選人。complete方法執(zhí)行時(shí)引擎會(huì)順著當(dāng)前節(jié)點(diǎn)的出口 SequenceFlow 走遇到排他網(wǎng)關(guān)時(shí)用表達(dá)式的值決定走哪個(gè)分支。任務(wù)變量和流程變量是兩套存儲(chǔ)complete(taskId, vars)里傳入的變量寫入的是流程變量ACT_RU_VARIABLE不是任務(wù)本地變量。如果只想給當(dāng)前任務(wù)附加數(shù)據(jù)而不影響流程走向應(yīng)該用taskService.setVariableLocal(taskId, key, value)。我見到的錯(cuò)誤大多是該用 local 的地方用了全局導(dǎo)致后續(xù)流程的表達(dá)式被不該存在的變量影響。4.2 排他網(wǎng)關(guān)的條件表達(dá)式類型決定寫法排他網(wǎng)關(guān)ExclusiveGateway在 5.17.0 里是默認(rèn)網(wǎng)關(guān)遇到多條出口線時(shí)會(huì)從上到下找第一個(gè)條件為 true 的線。上一章的請(qǐng)假流程里網(wǎng)關(guān)的兩條線分別用approved true和approved false判斷。這里是 JUEL 表達(dá)式類型很敏感變量類型正確寫法常見錯(cuò)誤Boolean${approved true}${approvedtrue}Integer${days 3}${days 3}String${auditType PASS}或${auditType eq PASS}${auditType PASS}null 判斷${approver null}或${approver ! null}直接${approver}團(tuán)隊(duì)里最常見的玄學(xué)現(xiàn)場(chǎng)${approved}單獨(dú)作為條件表達(dá)式當(dāng) approved 是 true 時(shí)確實(shí)為真但當(dāng)它只是“存在但值為 null”時(shí)表達(dá)式會(huì)拋異常而不是走 false 分支。所以條件判斷寧可寫完整也不要省略比較對(duì)象。另一個(gè)習(xí)慣是把流程結(jié)果的枚舉值如 “PASS”、“REJECT”用字符串變量傳可讀性比布爾值高但記得在 gateway 兩條線上都寫條件并在最后留一條無條件的默認(rèn)線防止變量缺失時(shí)直接拋異常。4.3 會(huì)簽節(jié)點(diǎn)與“駁回”的常見實(shí)現(xiàn)方式5.17.0 支持 BPMN 2.0 的多實(shí)例活動(dòng)multiInstanceLoopCharacteristics會(huì)簽就是靠它實(shí)現(xiàn)的。下面是一個(gè) 60% 通過即放行的多人會(huì)簽節(jié)點(diǎn)userTask idmultiApprove name多人會(huì)簽 activiti:assignee${currentApprover} multiInstanceLoopCharacteristics isSequentialfalse activiti:collection${approverList} activiti:elementVariablecurrentApprover completionCondition${nrOfCompletedInstances nrOfInstances * 0.6}/completionCondition /multiInstanceLoopCharacteristics /userTask參數(shù)說明approverList是啟動(dòng)流程時(shí)傳入的 List 變量currentApprover是引擎在每次循環(huán)時(shí)自動(dòng)生成的局部變量代表當(dāng)前要處理的審批人isSequentialfalse表示并行會(huì)簽每個(gè)任務(wù)同時(shí)生成而不是排著隊(duì)來。completionCondition 是完成條件表達(dá)式默認(rèn)全部處理完才算完成寫了這個(gè)條件后達(dá)到 60% 就會(huì)提前結(jié)束。注意缺失場(chǎng)景如果啟動(dòng)流程時(shí)沒傳approverList或傳的 List 為空這個(gè)節(jié)點(diǎn)運(yùn)轉(zhuǎn)時(shí)會(huì)報(bào)ActivitiException提示無法解析集合。這屬于啟動(dòng)參數(shù)校驗(yàn)問題我會(huì)在啟動(dòng)流程前先用業(yè)務(wù)代碼校驗(yàn)集合是否為空而不是等引擎運(yùn)行到一半才炸。駁回在 5.17.0 里沒有像 7.x 那樣的專用 API最常見做法是我在第 3 章 BPMN 里展示的回退流審批網(wǎng)關(guān)條件為 false 時(shí)指向“重新申請(qǐng)”任務(wù)讓提交人修改后再提交。簡(jiǎn)單、可追蹤、歷史記錄完整比直接調(diào)用底層 jump 更安全。如果確認(rèn)團(tuán)隊(duì)對(duì)底層 API 有把握也可以走runtimeService.createProcessInstanceModification()但不建議在核心業(yè)務(wù)里冒這個(gè)險(xiǎn)。做出決定前先問自己審批記錄要不要留痕駁回后要不要改表單數(shù)據(jù)網(wǎng)關(guān)回退在這兩點(diǎn)上都占優(yōu)勢(shì)。5. 避坑5.17.0 最常見的五個(gè)翻車現(xiàn)場(chǎng)這一章寫的每個(gè)坑都是真實(shí)會(huì)讓項(xiàng)目半夜響電話的那種。按“現(xiàn)象 → 原因 → 解決”的格式展開順序大致按從環(huán)境到代碼再到運(yùn)維排。5.1 Linux 下表名大小寫導(dǎo)致引擎找不到表現(xiàn)象同一個(gè)應(yīng)用在 Windows 開發(fā)機(jī)上跑得好好的部署到 Linux 測(cè)試環(huán)境后引擎啟動(dòng)報(bào)錯(cuò)提示找不到 ACT_HI_PROCINST 或 ACT_ID_GROUP數(shù)據(jù)源連接正常但建表永遠(yuǎn)不完整。原因MySQL 在 Linux 上默認(rèn)區(qū)分表名大小寫lower_case_table_names0而 5.17.0 的建表 SQL 里表名大小寫混用部分語(yǔ)句用小寫表名部分用大寫。開發(fā)環(huán)境 MySQL 不區(qū)分大小寫所以掩蓋了問題。解決第一時(shí)間檢查 MySQL 配置在[mysqld]段加lower_case_table_names1并重啟數(shù)據(jù)庫(kù)如果數(shù)據(jù)庫(kù)已經(jīng)建好需要先把舊表導(dǎo)出備份刪除庫(kù)后重建。對(duì)已經(jīng)上線的庫(kù)更穩(wěn)妥的方式是手工執(zhí)行官方 SQL 腳本建表然后把setDatabaseSchemaUpdate改成false讓應(yīng)用不再參與建表動(dòng)作從源頭避免大小寫探測(cè)。5.2 中文亂碼流程定義名、任務(wù)名全是問號(hào)現(xiàn)象BPMN 文件里寫了中文名稱部署后查詢流程定義顯示name字段是“???”任務(wù)節(jié)點(diǎn)名字在流程圖里也亂碼。原因串了兩個(gè)環(huán)節(jié)。第一BPMN 文件本身不是 UTF-8 編碼某些 Windows 編輯器會(huì)默認(rèn)存成 GBK第二JDBC 連接沒有顯式聲明字符集MySQL 會(huì)話使用默認(rèn) latin1入庫(kù)時(shí)按單字節(jié)存轉(zhuǎn)義符號(hào)。解決BPMN 文件統(tǒng)一保存為 UTF-8 無 BOM 格式編輯器右下角能看編碼JDBC 連接串帶上useUnicodetruecharacterEncodingutf8兩個(gè)參數(shù)成對(duì)出現(xiàn)缺一個(gè)都不生效。注意 5.17.0 年代用的 MySQL 驅(qū)動(dòng)是 5.1.x參數(shù)名必須這樣寫。改完連接串后已經(jīng)亂碼的數(shù)據(jù)需要重新部署流程歷史數(shù)據(jù)不會(huì)自動(dòng)修復(fù)。5.3 依賴沖突應(yīng)用啟動(dòng)直接 NoSuchMethodError現(xiàn)象Web 應(yīng)用引入 activiti-engine 5.17.0 后Spring 容器啟動(dòng)時(shí)報(bào)NoSuchMethodError或ClassNotFoundException堆棧指向org.springframework.expression或org.apache.ibatis。原因5.17.0 對(duì)傳遞依賴的版本管理很松散尤其 mybatis 和 spring-expression。項(xiàng)目里已有的 mybatis 3.4 與內(nèi)置的 mapper 映射不兼容或者 Spring 4 的 expression 模塊和引擎依賴的版本不一致都會(huì)在運(yùn)行時(shí)爆發(fā)。解決跑mvn dependency:tree -Dincludesorg.activiti,org.mybatis,org.springframework看完整依賴樹找到實(shí)際生效的版本號(hào)。常見做法是在項(xiàng)目的 dependencyManagement 里把 mybatis 鎖定到 3.2.x5.17.0 適配較好的版本同時(shí)確認(rèn) Spring 版本在 3.x 或 4.x 的早期版本區(qū)間避免直接用 Spring 4.3 以上的新特性。如果項(xiàng)目已經(jīng)用了新版本 mybatis且升級(jí)引擎不現(xiàn)實(shí)優(yōu)先級(jí)應(yīng)該是評(píng)估接口隔離而不是繼續(xù)在依賴?yán)镉矇喊姹尽?.4 待辦任務(wù)永遠(yuǎn)查不到assignee 變量缺失現(xiàn)象流程實(shí)例啟動(dòng)了數(shù)據(jù)庫(kù)里 ACT_RU_TASK 也有任務(wù)記錄但taskAssignee(某用戶)查詢結(jié)果為空。再一查原表任務(wù)的 ASSIGNEE_ 字段是 NULL。原因BPMN 里寫的activiti:assignee${submitter}用了表達(dá)式但啟動(dòng)流程時(shí) variables 里沒有 submitter 或 submitter 為 null。引擎不會(huì)在啟動(dòng)時(shí)校驗(yàn)變量是否存在只會(huì)在創(chuàng)建任務(wù)節(jié)點(diǎn)時(shí)把表達(dá)式求值結(jié)果寫入 ASSIGNEE_ 字段求值為 null 時(shí)字段就是 NULL。NULL 的任務(wù)不會(huì)出現(xiàn)在任何人的待辦列表里但流程會(huì)一直停在那個(gè)節(jié)點(diǎn)。解決在startProcessInstanceByKey之前用業(yè)務(wù)代碼對(duì)必填流程變量做校驗(yàn)。我習(xí)慣寫一個(gè)啟動(dòng)前的變量檢查方法手動(dòng)校驗(yàn)submitter、approver、approverList這些 BPMN 里引用到的 key缺一個(gè)就拋業(yè)務(wù)異常寧可在啟動(dòng)時(shí)拒絕也不要讓流程默默停擺。如果線上已經(jīng)出現(xiàn)這種任務(wù)補(bǔ)救方法是taskService.setAssignee(taskId, user02)手動(dòng)補(bǔ)上辦理人再讓用戶繼續(xù)操作。5.5 歷史表無限膨脹沒有歸檔策略現(xiàn)象上線半年后ACT_HI_ACTINST 表數(shù)據(jù)量達(dá)到上千萬行歷史流程查詢接口響應(yīng)從毫秒級(jí)變成秒級(jí)數(shù)據(jù)庫(kù)所在服務(wù)器 IO 頻繁告警。原因5.17.0 引擎默認(rèn)historyLevel是 audit對(duì)流程實(shí)例、活動(dòng)實(shí)例、任務(wù)、變量全量記錄且沒有任何自動(dòng)歸檔清理機(jī)制。很多業(yè)務(wù)系統(tǒng)上線后完全沒處理歷史表導(dǎo)致數(shù)據(jù)量線性增長(zhǎng)。解決分三個(gè)動(dòng)作處理。第一評(píng)估歷史數(shù)據(jù)必要程度把setHistoryLevel調(diào)整到HISTORY_ACTIVITY或HISTORY_NONE減少寫入量注意會(huì)丟失變量歷史降級(jí)前要確認(rèn)業(yè)務(wù)可接受第二定時(shí)清理三個(gè)月前的歷史數(shù)據(jù)直接按時(shí)間刪除 SQL-- 按時(shí)間刪除已完成流程的活動(dòng)實(shí)例記錄 DELETE FROM ACT_HI_ACTINST WHERE END_TIME_ IS NOT NULL AND END_TIME_ 2024-01-01 00:00:00; -- 清理任務(wù)實(shí)例 DELETE FROM ACT_HI_TASKINST WHERE END_TIME_ IS NOT NULL AND END_TIME_ 2024-01-01 00:00:00;第三對(duì)還在運(yùn)行的流程實(shí)例不要?jiǎng)h否則歷史流程視圖會(huì)斷鏈。清理腳本放到定時(shí)任務(wù)里跑建議先備份驗(yàn)證壓測(cè)到目標(biāo)數(shù)據(jù)量后再全量執(zhí)行。我見過因?yàn)闆]備份直接跑刪除結(jié)果誤刪未結(jié)束流程實(shí)例導(dǎo)致流程跳轉(zhuǎn)斷掉的情況這操作沒有后悔藥。6. 收尾技巧批量任務(wù)用事務(wù)隔離別讓一個(gè)失敗拖垮整批老系統(tǒng)發(fā)展到后面一定會(huì)遇到“批量審批”的需求部門主管一次勾選幾十張請(qǐng)假單點(diǎn)一下批量通過。這個(gè)場(chǎng)景用 5.17.0 最直接的寫法是循環(huán)調(diào)用 complete但一不注意就會(huì)出一個(gè)大問題循環(huán)里某個(gè)任務(wù)已被人搶辦complete 拋異常整個(gè)循環(huán)中斷前面已完成的審批跟著回滾。因?yàn)?ProcessEngine 默認(rèn)和 Spring 事務(wù)綁定在同一條事務(wù)鏈里一處失敗全部回滾。我現(xiàn)在的習(xí)慣是批量場(chǎng)景下每個(gè)任務(wù)的 complete 單獨(dú)提交不共用外部事務(wù)。Spring 配置里給批量方法單獨(dú)標(biāo)記Transactional(propagation Propagation.REQUIRES_NEW)或者干脆用編程式事務(wù)讓每個(gè)任務(wù)獨(dú)立 commit。偽代碼如下ListString taskIds getSelectedTaskIds(); for (String taskId : taskIds) { try { taskService.complete(taskId, buildApproveVars()); } catch (Exception e) { // 記錄失敗任務(wù)繼續(xù)處理后續(xù)任務(wù) failedTaskIds.add(taskId); log.error(任務(wù)審批失敗: taskId{}, taskId, e); } } if (!failedTaskIds.isEmpty()) { // 收集失敗原因給用戶明確的失敗清單而不是一句“系統(tǒng)錯(cuò)誤” throw new BizException(部分任務(wù)審批失敗已成功 (taskIds.size() - failedTaskIds.size()) 個(gè)); }另外推薦一個(gè)查詢習(xí)慣歷史流程列表必須帶分頁(yè)不要用list()一把梭。5.17.0 的 HistoryService 分頁(yè)參數(shù)和 7.x 一樣是listPage(firstResult, maxResults)配合orderByProcessInstanceStartTime().desc()能把接口響應(yīng)穩(wěn)定壓在百毫秒內(nèi)。加上 businessKey 過濾條件能讓“按單號(hào)查流程”這種高頻操作直接命中索引而不是全表掃描。這套組合拳打下來一個(gè)基于 activiti-5.17.0 的審批系統(tǒng)還能再健康地跑好幾年。老版本不值得盲目換但值得被認(rèn)真對(duì)待——先把批處理事務(wù)邊界劃清楚把歷史表歸檔做起來剩下的交給時(shí)間驗(yàn)證。希望這篇筆記能幫到你也祝你的流程引擎少一點(diǎn)半夜告警。本文還有配套的精品資源點(diǎn)擊獲取