Activiti 6.0 工作流实战指南：从模型设计到流程跑通

简介：本资源是面向Java开发工程师与流程自动化实践者的Activiti 6.0工作流引擎入门与实操指南，聚焦业务流程建模、任务类型配置与流程控制逻辑落地。文档系统梳理模型设计器核心能力，涵盖用户任务、服务任务、脚本任务、邮件任务等10类任务的适用场景与配置要点，并详解子流程、并行/排他分支、事件子流程等关键构造机制，助力开发者快速掌握流程定义、部署与调试全流程。资源为单文件PDF格式，共1个1.72MB文档，内容结构清晰，含37页完整目录与分章节技术说明，便于按需查阅与实践对照。目前已有1168人学习下载，适合初接触Activiti的工作流开发人员、企业OA/审批系统改造工程师及Spring Boot集成流程引擎的学习者系统掌握6.0版本核心用法。

1. 为什么一个“过时”的 Activiti 6.0 文档，至今仍是工作流毕设/课设最稳的落地支点？

不是所有工作流项目都适合上 Camunda 或 Flowable；也不是所有学生毕设都需要对接 Kubernetes 和分布式事务。我带过三届某高校软件工程方向的课程设计，每年都有至少 7 成同学卡在「流程跑不起来」——画完 BPMN 图，部署报错；配好用户任务，找不到待办；加个定时器，整个引擎停摆。最后翻车点往往不是逻辑，而是对 Activiti 6.0 这套已验证、有闭环、可离线调试、文档即代码的老派工作流体系理解断层。

这份《Activiti 6.0 工作流使用说明文档 v1.0》不是泛泛而谈的 API 手册，它来自一个真实落地的政务类流程平台（代号：模拟项目X），完整覆盖从模型设计器拖拽建模 → workflow-service 接口集成 → 租户级权限隔离 → 外置表单联动 → 事件监听器埋点 → SQL 级调试的全链路。它不讲云原生，不提 Spring Boot 3.x 自动装配，但每一页都写着“这个配置改了，SQL 就会多一条 INSERT”、“这个属性没填，发布时直接抛BpmnModelException”。对需要交一份能演示、能截图、能答辩、能写进论文‘系统实现’章节的学生和初级工程师来说，它比官网 User Guide 更像一本带注释的施工图。

你不需要懂 Drools 规则引擎源码，但得知道.drl文件怎么和流程定义 ZIP 包一起上传；你不用手写 Camel 路由，但得明白camelContext在 Spring XML 里怎么声明才能让 Camel 任务不报NoSuchBeanDefinitionException；你甚至可以跳过 Mule 集成，但必须搞清“边界事件中断任务”勾与不勾，到底影响的是当前节点还是整个子流程实例。这文档的厚度（37 页）不是信息冗余，而是把那些藏在日志堆栈最底层、让新手反复重装 H2 数据库的玄学问题，提前钉死在纸面上。

如果你正为毕设卡在“流程启动后查不到任务”，或课设被导师问“异步任务失败后怎么恢复”，又或者公司老系统要快速补一个审批流——别急着搜“Activiti 教程”，先吃透这份文档里1.6.1 异步、1.5.5 边界事件、2.3 自定义外置表单、3. 常见问题四个模块。它不承诺前沿，但保证你能把第一个流程从“画出来”真正走到“跑通”。

---

2. 模型设计器实战：从拖拽到发布，每个元素背后都是可验证的执行语义

Activiti 6.0 的模型设计器（qqdznyyglpt-workflow-designer）不是 Photoshop 式的绘图工具，而是一个语义编译器：你拖进去的每一个图标，最终都会翻译成bpmn20.xml中特定标签的属性组合，并触发对应的行为契约。本章不罗列所有控件，只聚焦四类高频翻车区——任务、分支、事件、属性——并给出可粘贴验证的配置逻辑和设计依据。

2.1 用户任务：不是“有人点一下”就叫用户任务

用户任务（User Task）常被误认为“只要画个圆角矩形，填个名字就行”。但实际部署后查不到待办？90% 出在分配（Assignee）配置上。文档 1.1.1 明确指出：“分配（任务处理人/处理组配置）”是核心属性，且其值决定流程引擎如何查询ACT_RU_TASK表。

关键设计点：assignee不是字符串字面量，而是表达式上下文变量。若填admin，引擎会尝试查找 ID 为admin的用户；若填${initiator}，则需确保流程启动时传入initiator变量（如runtimeService.startProcessInstanceByKey("leave", Collections.singletonMap("initiator", "zhangsan"))）。

下面是一个生产环境验证过的配置示例（在 designer 中右键用户任务 → Properties → Assignee）：

${userGroup == 'hr' ? 'hr_manager' : (userGroup == 'it' ? 'it_lead' : 'admin')}

• 为什么用三元表达式而非硬编码？
  避免流程定义与具体人员强耦合。userGroup是启动流程时传入的业务变量（如请假单中“所属部门”字段），引擎在解析时自动注入上下文，动态计算出处理人。
• 避坑提示：若表达式语法错误（如少个括号），设计器不会报错，但发布后调用taskService.createTaskQuery().list()返回空列表。此时需打开log4j.logger.org.activiti.engine.impl.persistence.entity=DEBUG，观察 SQL 是否生成了WHERE ASSIGNEE_ = ?条件及参数值。

2.2 排他分支 vs 并行分支：网关不是“画连线”那么简单

分支（Gateway）是流程走向的决策中枢，但学生最容易混淆的是“排他”与“并行”的语义边界。文档 1.4.1–1.4.2 的描述看似简单，实则暗含执行模型差异：

特性	排他分支（Exclusive Gateway）	并行分支（Parallel Gateway）
执行逻辑	仅执行第一个条件为true的出口流；无条件流默认命中	所有出口流同时激活，生成独立执行实例
后续聚合	无需显式聚合节点，多条流可直接汇入同一节点	必须配对使用：分叉网关 → 多个任务 → 聚合网关（否则流程挂起）
典型误用	在并行任务后接排他网关，期望“任一完成即走下一步” → 实际只有第一个完成的任务触发流转	在分支线上加条件（如${status=='approved'}），期望条件过滤 → 实际条件被忽略，所有流均执行

一个经典场景：采购审批需“财务+法务+技术”三方会签，任一驳回即终止流程。正确做法是：

1. 用并行网关分叉出三个用户任务（财务审批、法务审批、技术审批）；
2. 每个任务完成后，用排他网关判断各自结果（${approvalResult=='reject'}）；
3. 所有“驳回”流汇聚到“终止流程”结束事件；
4. 所有“通过”流汇聚到另一个并行网关，等待三者全部完成 → 再用排他网关判断是否全部通过。

设计依据：Activiti 的执行模型要求“并行”与“条件判断”职责分离。混用会导致ACT_RU_EXECUTION表中出现僵尸执行实例（IS_ACTIVE_=false但未结束），最终阻塞整个流程实例。

2.3 定时器事件：时间不是“写个 cron 就完事”

定时器事件（Timer Event）是工作流中最易被低估的复杂模块。文档 1.5.1 明确列出三种配置方式（ISO 时间、时间间隔、Cron 表达式），但未强调一个致命前提：jobExecutorActivate=true或asyncExecutorActivate=true必须启用，否则定时器永不触发。

在activiti-app.properties中，必须显式开启：

# 启用异步执行器（推荐用于开发/测试） activiti.asyncExecutorActivate=true activiti.asyncExecutor.corePoolSize=2 activiti.asyncExecutor.maxPoolSize=10 # 若用 Job Executor（适用于低频定时），则启用以下 # activiti.jobExecutorActivate=true

更关键的是 Cron 表达式写法。文档只提“可使用 cron expression”，但未说明 Activiti 6.0 使用的是Quartz 2.x 语法（非 Spring 的@Scheduled）。例如：

# ✅ 正确：每天上午9点执行（Quartz格式：秒 分 时 日 月 周 年） 0 0 0 9 * ? * # ❌ 错误：Spring格式（缺少年份位，且周位用*非?） 0 0 9 * * *

若填错，发布流程时不会报错，但ACT_RU_JOB表中查不到对应记录。验证方法：启动引擎后，执行 SQL：

SELECT ID_, TYPE_, EXCLUSIVE_, LOCK_OWNER_, LOCK_TIME_, RETRIES_, EXCEPTION_STACK_ID_, DUEDATE_, REPEAT_, HANDLER_TYPE_ FROM ACT_RU_JOB WHERE PROCESS_DEF_ID_ LIKE '%your-process-key%';

若无结果，优先检查activiti-app.properties中执行器是否启用及 Cron 格式。

2.4 表单绑定：外置表单不是“HTML 文件扔进去就行”

文档 2.3 提到“自定义外置表单”，但未展开其与流程变量的双向绑定机制。Activiti 6.0 的外置表单本质是FreeMarker 模板，通过${variableName}读取流程变量，通过<input name="variableName">提交更新。

一个最小可行表单（leave-form.ftl）应包含：

<form id="leaveForm" method="POST" action="${contextPath}/app/rest/process-instances/${processInstanceId}/tasks/${taskId}/complete"> <label>请假类型：</label> <select name="leaveType"> <option value="sick">病假</option> <option value="personal">事假</option> </select><br> <label>天数：</label> <input type="number" name="days" value="${days!''}"><br> <label>原因：</label> <textarea name="reason">${reason!''}</textarea><br> <button type="submit">提交审批</button> </form>

• 关键设计点：name属性值（leaveType,days,reason）必须与流程中用户任务的formKey关联的表单变量名完全一致，引擎才会将表单数据自动映射为流程变量。
• 避坑提示：若表单提交后变量未更新，检查三点：①formKey是否在 BPMN 中正确设置（如leave-form.ftl）；② 表单actionURL 中的processInstanceId和taskId是否由前端正确传入；③ FreeMarker 模板中${variableName!''}的!''是空值安全操作符，避免变量未初始化时报ExpressionNotFoundException。

---

3. workflow-service 集成：让流程引擎真正嵌入你的业务系统

workflow-service模块（文档第二部分）是 Activiti 6.0 与宿主业务系统（如 Spring MVC 应用）的胶水层。它不提供 UI，但决定了流程如何“活”在你的系统里——任务如何创建、变量如何传递、事件如何响应。本章直击三个核心集成点：数据更新逻辑、方法表达式配置、事件监听器注册，并给出可运行的 Spring XML 配置片段。

3.1 数据更新逻辑：流程变量不是“存在内存里”

文档 2.1 提到“数据更新逻辑”，但未说明其物理载体。Activiti 6.0 的流程变量（Process Variables）默认存储在ACT_RU_VARIABLE（运行时）和ACT_HI_VARINST（历史）表中，不是 JVM 堆内存。这意味着：

• 启动流程时传入的Map<String, Object>，会被序列化为bytea（PostgreSQL）或longblob（MySQL）存入数据库；
• 服务任务中调用execution.setVariable("result", "success")，会触发一次UPDATE ACT_RU_VARIABLE；
• 查询待办任务时taskService.createTaskQuery().taskAssignee("zhangsan").list()，实际执行SELECT * FROM ACT_RU_TASK WHERE ASSIGNEE_ = ?。

设计依据：这种设计保障了流程状态的持久性和集群一致性。但代价是——频繁读写变量会成为性能瓶颈。某次课设中，A同学在循环中每步都setVariable("counter", i++)，导致 100 步流程产生 100 次 DB 更新，耗时从 2s 涨到 18s。解决方案是：用execution.setTransientVariable()存储中间状态（不落库），仅在关键节点（如审批结束）用setVariable()持久化结果。

3.2 方法表达式配置：JavaDelegate 不是唯一选择

文档 1.1.2 列出服务任务的三种实现方式（类、表达式、委托表达式），其中“表达式”最易上手但最易失控。方法表达式（Method Expression）格式为${beanName.methodName(param1, param2)}，其执行依赖 Spring 容器中beanName的存在。

一个典型配置（在 BPMN 中服务任务的class字段填）：

${approvalService.approve(execution, task)}

对应 Spring XML 声明：

<bean id="approvalService" class="com.example.service.ApprovalService"/>

ApprovalService.java示例：

public class ApprovalService { public void approve(DelegateExecution execution, DelegateTask task) { String taskId = task.getId(); String processInstanceId = execution.getProcessInstanceId(); // 业务逻辑：更新订单状态、发送通知等 updateOrderStatus(processInstanceId, "approved"); // 设置流程变量供后续节点使用 execution.setVariable("approvalTime", new Date()); } }

• 关键设计点：方法签名中的DelegateExecution和DelegateTask是 Activiti 提供的上下文对象，可获取流程实例 ID、任务 ID、所有变量。不要试图在方法内调用runtimeService或taskService——Activiti 已在事务中管理这些服务，手动调用易引发事务冲突。
• 避坑提示：若方法抛出未检查异常（如RuntimeException），流程会进入ACT_RU_JOB表的失败队列，需手动调用managementService.moveJobToExecutableJob(jobId)恢复。建议在 service 方法中try-catch并调用execution.setVariable("error", e.getMessage())记录错误。

3.3 事件监听器配置：全局监听不是“写个类就完事”

文档 1.7 和 2.4 提到监听器配置，但未强调其注册时机。Activiti 6.0 的事件监听器分为两类：

• 执行监听器（Execution Listener）：绑定到特定流程节点（如用户任务开始前），通过 BPMN 的executionListener标签配置；
• 全局事件监听器（Global Event Listener）：监听整个引擎事件（如流程启动、任务创建），需在 Spring 中注册为 Bean。

全局监听器必须实现org.activiti.engine.delegate.event.ActivitiEventListener接口。一个监控任务超时的示例：

@Component public class TaskTimeoutListener implements ActivitiEventListener { @Override public void onEvent(ActivitiEvent event) { if (event.getType() == ActivitiEventType.TASK_CREATED) { TaskCreatedEvent taskEvent = (TaskCreatedEvent) event; String taskId = taskEvent.getTask().getId(); Date dueDate = taskEvent.getTask().getDueDate(); if (dueDate != null && dueDate.before(new Date())) { // 发送超时告警（可集成邮件、短信） sendAlert(taskId, "任务已逾期"); } } } private void sendAlert(String taskId, String message) { // 实际告警逻辑 System.out.println("ALERT: Task " + taskId + " - " + message); } @Override public boolean isFailOnException() { return false; // 避免监听器异常阻塞流程 } }

在 Spring XML 中注册：

<bean id="processEngineConfiguration" class="org.activiti.spring.SpringProcessEngineConfiguration"> <!-- 其他配置 --> <property name="eventListeners"> <list> <ref bean="taskTimeoutListener"/> </list> </property> </bean>

设计依据：isFailOnException()=false是血泪经验。曾有学生监听器中sendAlert()抛出NullPointerException，导致所有新流程无法启动（引擎拒绝注册监听器）。设为false后，异常被吞掉，流程照常运行，日志中仅记录 WARN。

---

4. 避坑指南：那些让流程“静默死亡”的 5 个高频陷阱

Activiti 6.0 的报错机制很“温柔”——很多问题不抛异常，只是流程卡住、任务消失、变量不更新。以下是我在指导学生和交付项目时，总结出的 5 个最高频、最隐蔽、最让人抓狂的翻车点。每一条都按“现象 → 原因 → 解决”结构给出可立即验证的动作。

4.1 现象：流程发布成功，但启动后ACT_RU_EXECUTION表无记录，ACT_RU_TASK为空

原因：流程定义中存在未配置的开始事件。Activiti 要求每个流程必须有且仅有一个开始事件（Start Event）。若画了多个空开始事件，或开始事件连线断开（没有指向下一个节点），引擎会静默忽略该流程定义。
解决：

1. 打开bpmn20.xml，搜索<startEvent，确认只有一个，且其id唯一；
2. 检查该开始事件是否有outgoing连线（<sequenceFlow sourceRef="startEventId" targetRef="nextNodeId"/>）；
3. 在 designer 中右键开始事件 → “Validate”（验证），看是否提示“Start event has no outgoing sequence flow”。

4.2 现象：用户任务显示在待办列表，但点击“办理”后页面空白，控制台无 JS 错误

原因：外置表单的formKey与实际文件名或路径不匹配。Activiti 通过formKey查找classpath:/forms/下的模板，若文件不存在，返回 HTTP 404，但前端框架（如 AngularJS）可能静默失败。
解决：

1. 确认formKey值（如leave-form.ftl）与src/main/resources/forms/目录下文件名完全一致（包括大小写和扩展名）；
2. 启动应用后，直接访问http://localhost:8080/app/rest/form/form-resources/leave-form.ftl，看是否返回 HTML 源码；
3. 若 404，检查 Mavenpom.xml中resources配置是否包含**/*.ftl（默认不打包 ftl 文件）。

4.3 现象：定时器事件配置了P1D（1天），但流程始终不触发，ACT_RU_JOB表无数据

原因：asyncExecutorActivate=true已启用，但asyncExecutor的maxPoolSize过小，且存在长期运行的服务任务阻塞线程池。
解决：

1. 检查activiti-app.properties中activiti.asyncExecutor.maxPoolSize，设为5（默认 2，不够）；
2. 在服务任务中避免Thread.sleep(10000)等长耗时操作；
3. 启动后执行 SQL：SELECT COUNT(*) FROM ACT_RU_JOB WHERE LOCK_OWNER_ IS NULL，若为 0，说明执行器未拉取任务，需检查asyncExecutor是否启动（日志中搜索Async executor started）。

4.4 现象：决策任务引用决策表变量，后续排他网关报错Cannot resolve identifier 'riskCheck'

原因：决策表（.drl）中输出变量名与流程中引用名不一致。文档 1.1.10 提到“输出变量只能有一个名称”，但未强调该名称必须与decisionTable元素的outputVariable属性值相同。
解决：

1. 在 BPMN 中选中决策任务 → Properties → Decision Table → Output Variable，记下值（如riskResult）；
2. 打开.drl文件，确认rule "loanRisk"的then块中设置了kcontext.setVariable("riskResult", "reject");；
3. 后续网关条件写${riskResult == 'reject'}，而非${riskCheck}。

4.5 现象：邮件任务配置了 SMTP，但发信失败，日志显示javax.mail.AuthenticationFailedException

原因：activiti-app.properties中邮件配置项缺失或格式错误。Activiti 6.0 使用 JavaMail，要求mail.smtp.auth=true且用户名密码正确。
解决：

1. 确认配置项完整（以下为最小集）：

   mail.host=smtp.qq.com mail.port=587 mail.username=[e-mail] mail.password=your_app_password # 注意：QQ邮箱需用“授权码”，非登录密码 mail.from=[e-mail] mail.smtp.auth=true mail.smtp.starttls.enable=true

2. 在 Java 代码中测试 SMTP 连接（非 Activiti）：

   Properties props = new Properties(); props.put("mail.smtp.host", "smtp.qq.com"); props.put("mail.smtp.port", "587"); props.put("mail.smtp.auth", "true"); props.put("mail.smtp.starttls.enable", "true"); Session session = Session.getInstance(props, new Authenticator() { /* ... */ });

---

5. 验收与答辩：用三张表、两个命令、一次全流程演示征服导师

毕设/课设的终极目标不是“代码跑起来”，而是让导师在 5 分钟内看懂你的工作量、技术深度和问题解决能力。Activiti 项目尤其如此——流程图谁都会画，但能否说清“为什么用并行网关而不是排他网关”、“定时器失败后如何恢复”，才是答辩分水岭。以下是我给学生定的验收 checklist，也是答辩时最有力的陈述框架。

5.1 验收三张表：用数据库证据代替口头描述

不要说“我的流程支持多实例”，要打开ACT_RU_EXECUTION表，指出哪几行PARENT_ID_相同、IS_ACTIVE_=true的记录，证明并行实例正在运行；不要说“我做了权限控制”，要展示ACT_RU_IDENTITYLINK表中TYPE_='candidate'的记录，关联到ACT_RU_TASK的ID_。以下是答辩必查的三张表及关键字段：

表名	核心字段	验收要点	导师可能问
ACT_RU_TASK	ID_,NAME_,ASSIGNEE_,CREATE_TIME_,DUE_DATE_	展示待办任务列表，重点指出ASSIGNEE_如何由表达式动态计算（如${deptLeader}）	“这个ASSIGNEE_是怎么确定的？如果部门领导离职了怎么办？”
ACT_RU_VARIABLE	NAME_,TYPE_,BYTEARRAY_ID_,TEXT_,LONG_	展示流程变量存储，指出TEXT_存字符串、LONG_存数字、BYTEARRAY_ID_指向大对象（如 PDF 表单）	“变量存数据库会不会慢？有没有考虑缓存？”
ACT_RU_JOB	ID_,TYPE_,EXCLUSIVE_,DUEDATE_,RETRIES_,EXCEPTION_MSG_	展示定时器/异步任务，指出RETRIES_=3且EXCEPTION_MSG_为空，证明健壮性	“如果定时器连续失败 3 次，你怎么告警？”

操作技巧：答辩前导出这三张表的当前快照（如task_snapshot.csv），放在 PPT 附录。当导师质疑时，直接切屏展示 CSV，比口头解释高效十倍。

5.2 两个命令：暴露你的调试深度

导师最欣赏能看懂日志、会查 SQL 的学生。准备两个终端命令，随时演示：

命令一：实时跟踪流程执行 SQL
在log4j.properties中开启：

log4j.logger.org.activiti.engine.impl.persistence.entity=DEBUG log4j.logger.org.activiti.engine.impl.db=DEBUG

启动应用后，执行：

tail -f logs/catalina.out | grep -E "(INSERT INTO ACT_|UPDATE ACT_|SELECT.*FROM ACT_)"

当启动一个流程，你会看到类似：

INSERT INTO ACT_RU_EXECUTION (ID_, REV_, PROC_INST_ID_, BUSINESS_KEY_, PARENT_ID_, PROC_DEF_ID_, SUPER_EXEC_, ROOT_PROC_INST_ID_, ACT_ID_, IS_ACTIVE_, IS_CONCURRENT_, IS_SCOPE_, IS_EVENT_SCOPE_, IS_MI_ROOT_, SUSPENSION_STATE_, CACHED_ENT_STATE_, TENANT_ID_, NAME_, START_TIME_, START_USER_ID_, LOCK_TIME_, IS_COUNT_ENABLED_, EVT_SUBSCR_COUNT_, TASK_COUNT_, JOB_COUNT_, TIMER_JOB_COUNT_, SUSP_JOB_COUNT_, DEADLETTER_JOB_COUNT_, VAR_COUNT_, ID_LINK_COUNT_) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)

答辩话术：“您看，这是流程启动时的 INSERT，它创建了执行实例；接下来会有 UPDATE ACT_RU_TASK 设置处理人——这证明分配逻辑生效了。”

命令二：定位失败任务
当流程卡住，执行：

-- 查看所有失败的异步任务 SELECT ID_, EXCLUSIVE_, DUEDATE_, RETRIES_, EXCEPTION_MSG_ FROM ACT_RU_JOB WHERE RETRIES_ <= 0; -- 查看某个流程实例的所有任务（含已完成） SELECT ID_, NAME_, ASSIGNEE_, START_TIME_, END_TIME_, DURATION_ FROM ACT_HI_TASKINST WHERE PROC_INST_ID_ = 'your-process-instance-id';

5.3 一次全流程演示：从“画”到“跑”闭环

答辩演示必须是一次不可中断的端到端流程，建议按此顺序（5 分钟内完成）：

1. 打开 designer：展示已发布的流程图（如“采购审批”），重点圈出：并行网关、定时器边界事件、邮件任务；
2. 启动流程：用 Postman 调用POST /runtime/process-instances，传入 JSON{ "processDefinitionKey":"procurement", "variables":{ "dept":"it", "amount":15000 } }；
3. 查待办：打开浏览器，访问http://localhost:8080/app/#/tasks，登录admin/test，展示三个并行任务（IT 审批、财务审批、法务审批）；
4. 完成一个任务：点击“IT 审批” → 填写表单 → 提交；
5. 验证效果：刷新待办页，展示剩余两个任务；执行 SQLSELECT * FROM ACT_RU_VARIABLE WHERE PROC_INST_ID_='xxx'，指出itApproved=true变量已更新；
6. 触发邮件：等待 10 秒（定时器），查看控制台日志Sent email to [e-mail]。

血泪教训：从那以后我每次带学生做 Activiti 项目，都强制走一遍这个六步演示脚本，并录屏存档。因为答辩现场网络波动、Chrome 缓存、Postman 版本不兼容……任何一环断掉，5 分钟就变成尴尬沉默。脚本化后，学生能脱稿流畅演示，导师点头频率明显提高。希望帮到你。

本文还有配套的精品资源，点击获取