简介本资源是面向Java开发工程师与流程自动化实践者的Activiti 6.0工作流引擎入门与实操指南聚焦业务流程建模、任务类型配置与流程控制逻辑落地。文档系统梳理模型设计器核心能力涵盖用户任务、服务任务、脚本任务、邮件任务等10类任务的适用场景与配置要点并详解子流程、并行/排他分支、事件子流程等关键构造机制助力开发者快速掌握流程定义、部署与调试全流程。资源为单文件PDF格式共1个1.72MB文档内容结构清晰含37页完整目录与分章节技术说明便于按需查阅与实践对照。目前已有1168人学习下载适合初接触Activiti的工作流开发人员、企业OA/审批系统改造工程师及Spring Boot集成流程引擎的学习者系统入门与快速上手。1. 这不是一份“翻完就扔”的 PDFActiviti 6.0 工作流使用说明文档 v1.0 是你落地 BPMN 流程的实操黑匣子如果你正在用 Spring Boot 集成工作流却卡在「画完流程图一部署就报错Invalid BPMN model」或者调试时发现「定时器没触发、信号收不到、邮件发不出」翻遍官网文档和 Stack Overflow 还是找不到对应配置项在哪——那你手头这份《Activiti6.0工作流使用说明文档v1.0.pdf》不是过时资料而是当年某高校实验室在真实产线项目中沉淀下来的「避坑型操作手册」。它不讲抽象理论37 页里有 28 页是设计器界面截图属性面板填空式说明连「log4j.logger.org.activiti.engine.impl.persistence.entityDEBUG」这种打开 SQL 日志的开关都标在第 4 页脚注里。它专为两类人存在一是刚接手遗留 Activiti 6 项目的维护工程师需要快速定位Camel 任务怎么配 Spring Bean、决策表变量为空导致后续${riskCheckfalse}报错的根因二是想绕过官方 User Guide 的冗长描述直接抄参数、粘配置、复现 zip 示例包的实战派。它不承诺兼容 7.x但能让你在 JDK8 Spring 4.x Tomcat 8 的老环境中把「用户审批 → 调用风控服务 → 自动发邮件 → 超时自动升级」这条链路真正跑通。2. 模型设计器不是画布是流程逻辑的编译器从拖拽元素到生成可执行 BPMN 文件的完整闭环Activiti 6 的模型设计器qqdznyyglpt-workflow-designer本质是一个 BPMN 2.0 编译前端你拖进去的每个图标最终都会被翻译成userTask、serviceTask等 XML 元素并注入具体属性值。它的输出不是图片而是.bpmn20.xml文件——这才是引擎真正加载的对象。理解这一点才能避开「界面看着对运行就报错」的玄学现场。2.1 任务节点10 类任务的本质差异与选型铁律任务是流程的原子单元但不同任务的执行机制天差地别。选错类型轻则功能失效重则流程卡死。2.1.1 用户任务必须人工介入的强制关卡用户任务userTask是唯一要求「人」参与的节点。关键配置项不是名称或描述而是assignee处理人和candidateGroups候选组assignee填admin表示固定分配给 admin 用户candidateGroups填hr,finance表示 HR 和财务组所有成员都能拾取该任务若两者都为空任务将处于unclaimed状态需调用taskService.claim(taskId, userId)手动认领。提示生产环境严禁硬编码assigneeadmin。应使用表达式${initiator}发起人或${ldapService.getApproverByDept(dept)}动态查LDAP否则流程无法流转。2.1.2 服务任务三种实现方式的边界与血泪经验服务任务serviceTask用于执行 Java 逻辑但类、表达式、委托表达式三者不可混用且依赖注入方式完全不同实现方式配置位置依赖注入要求典型错误场景类Class属性面板Class字段类必须实现JavaDelegate或ActivityBehavior且含Override execute(DelegateExecution)方法忘记在activiti.cfg.xml中注册该类为 bean导致ClassNotFoundException表达式ExpressionField→Name: resultVar,String value: ${myService.doSomething()}方法必须返回值且resultVar名称需全局唯一在resultVar中用了${}表达式导致解析失败委托表达式Delegate ExpressionDelegate expression字段填#{myServiceBean}myServiceBean必须在 Spring 容器中声明为Bean且实现JavaDelegateSpring 上下文未加载#{myServiceBean}解析为空实际项目中我一般会强制走委托表达式路线在SpringConfig.java中声明Bean public MyOrderService myOrderService() { return new MyOrderService(); }设计器中Delegate expression填#{myOrderService}Field中添加orderNo${execution.getVariable(orderNo)}传参。这样既保证 Spring 管理生命周期又避免类路径硬编码。2.1.3 脚本任务JavaScript 引擎的隐形依赖与变量陷阱脚本任务scriptTask默认用 NashornJDK8 内置 JS 引擎但必须显式声明脚本格式属性面板Script format填javascript不能写js或留空脚本内容中禁止使用out,context,elcontext等保留字作为变量名文档第 6 页明确警告设置流程变量必须用execution.setVariable(key, value)不能用var key value。一个典型翻车案例// ❌ 错误用 var 声明变量仅在脚本作用域内 var amount execution.getVariable(loanAmount); if (amount 10000) { execution.setVariable(riskLevel, high); // 此处设值有效 } else { execution.setVariable(riskLevel, low); // 此处设值有效 } // 但下面这行无效因为 amount 是局部变量无法被后续节点引用 execution.setVariable(amount, amount); // ✅ 必须显式 set2.1.4 业务规则任务Drools 规则文件的打包与加载规范业务规则任务businessRuleTask依赖 Drools 引擎但规则文件.drl必须和 BPMN 文件同级打包正确结构process.bpmn20.xmlrules.drl同一 ZIP 包内设计器中Rule files字段填rules.drl若多个用逗号分隔规则中input变量名必须与流程变量名完全一致大小写敏感output只能有一个变量名如decisionResult。若规则中定义rule CheckLoan when $l: Loan(amount 10000) then $l.setRisk(high); end则流程中必须存在名为Loan的变量对象且含amount属性。否则规则不触发且无任何日志提示——这是最隐蔽的坑。2.2 分支与网关排他、并行、包容、事件四类网关的执行逻辑拆解网关控制流程走向但每种网关的「条件判断时机」和「实例生成策略」完全不同直接决定流程是否按预期并发或串行。2.2.1 排他网关Exclusive Gateway单选题但默认选第一个排他网关exclusiveGateway像一道单选题每条出线可配置conditionExpression如${loanAmount 5000}引擎从上到下扫描遇到第一个为true的条件即执行其余忽略若所有条件为false抛出ActivitiException: No outgoing sequence flow of the exclusive gateway ...。注意条件表达式必须返回布尔值。${status APPROVED}合法${status}不合法返回字符串非布尔。2.2.2 并行网关Parallel Gateway强制并发条件失效并行网关parallelGateway的分叉Fork和聚合Join是强绑定的分叉后所有出线任务必定同时启动无论是否配置条件聚合时必须等待所有入线任务完成才继续若某条线任务失败整个流程卡在聚合点除非配置async或异常处理。典型误用想让「审核A」和「审核B」并行但希望「审核B」只在dept finance时执行。此时不能在并行网关出线上写条件而应改用包容网关。2.2.3 包容网关Inclusive Gateway带条件的并行但聚合逻辑更严苛包容网关inclusiveGateway是排他与并行的混合体分叉时只启动条件为true的出线任务聚合时必须等待所有「已启动」的任务完成才继续不是所有出线而是所有满足条件的出线若无一条出线条件为true流程直接卡死同排他网关。配置要点分叉前必须有inclusiveGateway标签每条出线conditionExpression必须明确不能留空聚合点也必须是inclusiveGateway且default属性无效。2.2.4 事件网关Event Gateway挂起等待非抢占式分支事件网关eventGateway不基于条件而是等待事件发生出线只能连接中间捕获事件如messageEvent,signalEvent,timerEvent流程执行到此即挂起订阅所有出线事件任一事件触发其他事件订阅自动取消流程沿该事件线继续。关键限制至少连接2 个中间捕获事件文档第 13 页强调否则部署失败每个事件只能有一个输入流不能从其他节点连入定时器事件需配置timeDuration如PT10M表示 10 分钟否则不生效。2.3 事件捕获与抛出的生命周期管理事件是流程的「神经末梢」但捕获Catch和抛出Throw行为严格分离且生命周期由引擎托管。2.3.1 定时器事件三种配置格式的语法细节定时器事件timerEventDefinition必须配置timeDate、timeDuration或timeCycle之一否则发布失败。常见错误配置类型正确示例常见错误原因timeDate2023-12-25T09:00:0008:002023/12/25 09:00:00必须 ISO-8601 格式T和时区08:00不可省略timeDurationPT30M30分钟P30M30个月P后跟T表示时间不跟T表示周期年月日timeCycleR3/PT1H循环3次间隔1小时R/PT1H无限循环R后必须跟数字否则引擎无法解析提示timeCycle的 cron 表达式需用0 0/5 * * * ?格式秒 分 时 日 月 周 年且jobExecutorActivatetrue必须在activiti.cfg.xml中开启。2.3.2 信号事件全局与实例作用域的隔离机制信号事件signalEventDefinition分两种作用域全局信号RuntimeService.signalEventReceived(alert)所有订阅该信号的流程实例均接收实例信号RuntimeService.signalEventReceived(alert, executionId)仅指定实例接收。关键约束捕获信号只能捕获「信号抛出之后」的事件文档第 14 页即流程必须先到达信号捕获节点再抛出信号若流程尚未到达捕获节点就抛出信号该信号丢失无日志查询订阅runtimeService.createExecutionQuery().signalEventSubscriptionName(alert).list()返回当前所有等待该信号的执行实例。2.3.3 消息事件点对点通信的协议约定消息事件messageEventDefinition与信号核心区别是一对一每个消息名messageName唯一对应一个接收方抛出消息必须指定executionId不能全局消息内容通过HashMapString, Object传递如MapString, Object vars new HashMap(); vars.put(orderId, ORD-2023-001); runtimeService.messageEventReceived(orderConfirmed, executionId, vars);接收方在messageEvent节点中通过${orderId}获取变量。3. workflow-service 模块流程服务层的配置与方法调用契约workflow-service是连接设计器与业务系统的胶水层其核心是ProcessEngineConfiguration的定制化。它不提供新功能但决定了「流程如何与你的代码对话」。3.1 数据更新逻辑流程变量与业务数据的双向同步流程变量execution.setVariable()默认存储在 Activiti 自身数据库中但业务系统通常有自己的数据表。workflow-service通过监听器实现同步3.1.1 执行监听器Execution Listener流程节点级别的钩子在 BPMN 文件中为节点添加userTask idapproveTask name审批 extensionElements activiti:executionListener eventstart classcom.example.listener.ApproveStartListener/ activiti:executionListener eventend delegateExpression${approveEndListener}/ /extensionElements /userTaskeventstart节点开始执行前触发eventend节点执行完成后触发无论成功或失败class方式需实现ExecutionListener接口delegateExpression方式需 Spring Bean 实现ExecutionListener。典型用途start时校验前置条件如检查申请人是否有权限end时更新业务表状态如UPDATE order SET statusAPPROVED WHERE id#{orderId}。3.1.2 任务监听器Task Listener任务生命周期的精细控制任务监听器activiti:taskListener作用于任务状态变更eventcreate任务创建时taskService.newTask()后eventassign任务被分配时taskService.claim()后eventcomplete任务完成时taskService.complete()后。注意assign事件在claim时触发但create事件在流程启动时即触发即使任务未被领取。因此发送待办通知应在create事件中而非assign。3.2 方法表达式配置让流程调用你的 Service 方法方法表达式是服务任务的简化版但需严格遵循 SpEL 语法3.2.1 方法调用的参数传递规范在服务任务属性中Expression字段填#{orderService.confirmOrder(execution.getVariable(orderId), execution.getVariable(userId))}Result variable字段填confirmResult接收返回值。关键约束方法参数必须是流程变量不能直接写字符串字面量如#{orderService.confirmOrder(ORD-001, admin)}会报错若方法返回对象confirmResult将存入流程变量后续节点可用${confirmResult.status}访问。3.2.2 外置表单External Form的集成路径外置表单HTML/JS需通过formKey关联BPMN 中用户任务设置formKeyorderFormworkflow-service需提供/form/orderForm接口返回表单 HTML表单提交时POST /runtime/tasks/{taskId}/variables提交变量。提示表单中字段名必须与流程变量名一致如input nameamount对应${amount}否则变量无法注入。3.3 事件监听器配置全局事件的捕获与响应全局事件监听器org.activiti.engine.delegate.event.ActivitiEventListener可监听所有流程事件3.3.1 监听器注册方式在activiti.cfg.xml中bean idprocessEngineConfiguration classorg.activiti.spring.SpringProcessEngineConfiguration property nameeventListeners list bean classcom.example.listener.GlobalProcessListener/ /list /property /bean3.3.2 关键事件类型与处理建议事件类型触发时机推荐处理动作避坑点EVENTTYPE_PROCESS_STARTED流程实例启动记录日志、初始化监控指标避免在此处调用耗时 DB 操作阻塞流程启动EVENTTYPE_TASK_ASSIGNED任务分配发送站内信、邮件提醒event.getTask().getAssignee()可能为 null未分配EVENTTYPE_ACTIVITY_COMPLETED节点完成更新业务状态、触发下游流程event.getActivityId()返回节点 ID非任务 ID4. 避坑指南Activiti 6.0 设计器与引擎的 5 个高频翻车现场这些坑我在三个项目中反复踩过每次排查都耗掉半天。列在这里帮你省下 15 小时 debug 时间。4.1 现象流程部署成功但启动时报Invalid BPMN model: no start event found原因BPMN 文件中确实没有startEvent节点或开始事件未正确连接到第一个任务。设计器有时会因拖拽失误导致开始事件「悬浮」在画布外XML 中startEvent存在但无outgoing连接。解决打开.bpmn20.xml文件搜索startEvent确认其id是否在sequenceFlow sourceRefxxx targetRefyyy/中作为sourceRef出现。若无手动添加sequenceFlow sourceRefstartEventId targetReffirstTaskId/。4.2 现象定时器事件Timer Event始终不触发日志无任何报错原因jobExecutorActivate或asyncExecutorActivate未启用。Activiti 6 默认关闭异步执行器定时器、邮件等异步任务全部失效。解决在activiti.cfg.xml中添加property namejobExecutorActivate valuetrue/ !-- 或 -- property nameasyncExecutorActivate valuetrue/并确保activiti-app.properties中mail.server.host等配置正确影响邮件任务但定时器依赖执行器本身。4.3 现象信号事件Signal Event抛出后流程无响应createExecutionQuery().signalEventSubscriptionName(...).list()返回空列表原因流程未执行到信号捕获节点就抛出了信号。信号是「广播」但捕获是「订阅」必须先订阅后广播。解决在流程中插入一个User Task或Service Task确保流程至少执行一步后再到达信号捕获节点。例如Start → Dummy Task空服务任务仅 sleep(100)→ Signal Catch → Next Node然后在Dummy Task的end监听器中抛出信号。4.4 现象决策任务Business Rule Task中${riskCheckfalse}报错Cannot resolve identifier riskCheck原因决策表.drl中未为riskCheck输出变量赋值或规则未匹配导致变量未创建。Activiti 不会为未命中的规则创建输出变量。解决在.drl文件末尾添加兜底规则rule Default Risk Check when // 无条件 then $decision.setRiskCheck(false); end确保所有路径都有输出。4.5 现象邮件任务Mail Task配置了activiti-app.properties但启动时抛javax.mail.AuthenticationFailedException原因activiti-app.properties中mail.server.password是明文但某些邮件服务器如 QQ 邮箱要求使用「授权码」而非登录密码且授权码需 URL 编码。解决将授权码进行 URL 编码如abc123!#编码为abc123%21%40%23再填入配置mail.server.passwordabc123%21%40%23并在log4j.properties中开启DEBUG级日志确认org.activiti.engine.impl.bpmn.behavior.MailActivityBehavior是否正常加载。5. 验证与调试用三步法把「流程跑起来」变成「流程稳得住」部署一个流程不难难的是确保它在高并发、异常网络、数据库抖动下依然可靠。我总结了一套验证闭环从单点测试到混沌压测覆盖 95% 的线上问题。5.1 第一步SQL 日志 流程实例快照定位执行断点Activiti 的最大优势是全程可追溯。开启 SQL 日志是诊断的第一步修改log4j.propertieslog4j.logger.org.activiti.engine.impl.persistence.entityDEBUG log4j.logger.org.activiti.engine.impl.jobexecutorDEBUG启动应用执行一次流程查看日志中INSERT INTO ACT_RU_EXECUTION和UPDATE ACT_RU_TASK的 SQL确认流程实例 IDID_是否生成当前执行节点ACT_ID_是否指向预期任务任务表ACT_RU_TASK中ASSIGNEE_是否为空未分配或有值已分配。提示若ACT_RU_EXECUTION中IS_ACTIVE_0且END_TIME_为空说明流程卡在某个节点需检查该节点的异步配置或监听器是否抛异常。5.2 第二步用 REST API 模拟全流程绕过前端干扰前端页面可能隐藏表单校验或 JS 错误直接调用 Activiti REST API 可排除干扰启动流程实例curl -X POST http://localhost:8080/activiti-rest/service/runtime/process-instances \ -H Content-Type: application/json \ -u admin:test \ -d {processDefinitionKey:orderProcess,variables:[{name:orderNo,value:ORD-001},{name:amount,value:9999}]}查询待办任务curl http://localhost:8080/activiti-rest/service/runtime/tasks?assigneeadmin \ -u admin:test完成任务curl -X POST http://localhost:8080/activiti-rest/service/runtime/tasks/ taskId/complete \ -H Content-Type: application/json \ -u admin:test \ -d {variables:[{name:approved,value:true}]}若 API 能跑通而前端不行问题一定在前端 JS 或表单渲染逻辑。5.3 第三步混沌测试主动制造故障验证补偿与重试生产环境不会总是一帆风顺。我习惯在预发环境做三类主动故障测试数据库连接中断停掉 MySQL观察流程是否卡在ACT_RU_EXECUTION恢复后是否自动重试需配置asyncExecutor服务任务超时在MyOrderService.confirmOrder()中加Thread.sleep(60000)确认asynctrue的节点是否挂起而主线程继续补偿事件触发在事务子流程中故意让服务任务抛BpmnError(PAYMENT_FAILED)检查边界补偿事件是否执行refund()方法。从那以后我每次上线新流程都强制走一遍这三步SQL 日志确认执行路径 → REST API 验证接口契约 → 混沌测试验证容错能力。少一次就可能多一个凌晨三点的告警电话。希望帮到你。本文还有配套的精品资源点击获取
