简介：Activiti 5.17.0 官方工作流引擎资源包，面向需要实现企业级流程自动化的 Java 开发人员、流程架构师与系统运维者，可基于 BPMN 2.0 搭建流程模型，并借助引擎完成流程实例调度、任务分配与状态查询，适用于审批、工单、项目管理等常见场景。压缩包为 zip 格式，整体约 69.35MB，内容涵盖官方发布的 jar 运行文件、源代码与离线手册，包内文件组织清晰，便于按需检索，既可直接引入项目运行，也可对照源码研究流程引擎核心机制。目前已有 202 人学习浏览，有助于从入门到进阶掌握 Activiti。该版本重点关注流程定义与模型设计、引擎 API 使用、任务与分支并发处理、动态表单关联、事件监听与自定义行为等知识点；同时可学习与 Spring、Hibernate 的整合方式，以及 REST API、事务管理、数据库持久化等工程化能力，使开发者能够快速将流程引擎融入业务系统。借助源码与手册，开发者能深入理解 Activiti 5.17.0 的整体结构，为后续基于该框架的业务流程二次开发提供可靠参考。

1. activiti-5.17.0 到底是个什么版本：先给一句判断

如果你所在的团队接手了一套 2015 年前后的审批系统，大概率会看到一个老熟人：activiti-5.17.0。它没有 7.x 的云原生概念，也不带 Spring Boot 的自动配置，但核心能力一个不少：流程部署、任务流转、会签、驳回、条件分支、历史查询全部撑得住。真正让人翻车的地方集中在三处：和 Spring 版本的配合、数据库表名大小写、以及 BPMN 文件里的命名空间细节。这篇笔记会顺着“搭环境 → 跑通一条流程 → 审批流转 → 避坑 → 批量处理技巧”的顺序讲透，每一段都给出能直接复制的代码和参数。适合两类人看：刚接手存量系统、被历史代码追着跑的新人，以及正在评估“老版本值不值得继续投入”的架构师。

2. 先把引擎跑起来：依赖、配置与建表动作

Activiti 5.17.0 的引擎核心是一个重量级对象 ProcessEngine，它负责管理所有的 Service（部署、运行时、任务、历史、身份），所有操作都从它身上拿。这一章不碰 Spring，先把“裸引擎”跑起来，目的是确认依赖、数据库和建表策略这三件事都正确。这一步通了，后面接 Spring 还是接别的容器都只是装配问题。

2.1 依赖怎么加：两个坐标，别加多

先看 Maven 依赖。5.17.0 的坐标和 7.x 不一样，核心是这个：

<dependency> <groupId>org.activiti</groupId> <artifactId>activiti-engine</artifactId> <version>5.17.0</version> </dependency> <!-- 如果要接 Spring 3/4，再加这个，不要重复引入 engine --> <dependency> <groupId>org.activiti</groupId> <artifactId>activiti-spring</artifactId> <version>5.17.0</version> </dependency>

这里有个常见误操作：有人为了“保险”，把 activiti-engine、activiti-spring、activiti-bpmn-converter 一次性全引进来，结果 classpath 里出现同一类的多个版本，启动时直接 NoSuchMethodError。5.17.0 的依赖管理没有 7.x 那么完善，engine 自己带了模型解析、BPMN 转换、MyBatis 映射，正常业务不需要额外加解析模块。

参数说明：activiti-engine 内部会传递依赖 mybatis 和 spring-expression，如果你的项目里已经用了另一个版本的 mybatis，这里大概率会冲突。我一般会在引入后先跑一次mvn dependency:tree -Dincludes=org.activiti看实际的依赖树，确认没有两个版本的 engine 并存。这个习惯能省掉后面一小时的排查时间。

2.2 引擎配置：数据库连接和建表策略

5.17.0 提供了独立的配置类 ProcessEngineConfiguration，可以通过 Java 代码直接构建引擎，这是最小化验证的最佳路径，不依赖 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 参数 .setJdbcUrl("jdbc:mysql://localhost:3306/activiti_test?useUnicode=true&characterEncoding=utf8") .setJdbcDriver("com.mysql.jdbc.Driver") .setJdbcUsername("root") .setJdbcPassword("root") // true = 没有表就自动创建，false = 不建表，drop-create = 每次删了重建 .setDatabaseSchemaUpdate(ProcessEngineConfiguration.DB_SCHEMA_UPDATE_TRUE) // 历史级别：full 记录最全，none 完全不记录 .setHistoryLevel(ProcessEngineConfiguration.HISTORY_FULL); ProcessEngine processEngine = config.buildProcessEngine(); System.out.println("Engine name: " + processEngine.getName()); } }

逻辑说明：createStandaloneProcessEngineConfiguration()创建的是一个不依赖事务管理器、不依赖数据源的“独立引擎配置”，适合工具类、命令行脚本、单元测试。如果直接接 Spring，应该换成createProcessEngineConfigurationFromResource("activiti.cfg.xml")或者用 Spring 的SpringProcessEngineConfiguration，但这不影响建表逻辑。

参数说明：setDatabaseSchemaUpdate有三个值，生产环境我强烈建议用false并手工执行官方 SQL 脚本，而不是让引擎每次启动都去探测表结构。setHistoryLevel默认是HISTORY_AUDIT（记录流程实例、活动实例、任务、变量，但跳过流程变量更新明细），如果不需要历史数据，改成HISTORY_NONE能显著减少写入量。这里先保持 FULL，方便后面的章节验证历史查询。

2.3 验证引擎真的初始化成功

引擎启动成功不等于表都建对了。5.17.0 默认会创建一组以 ACT_ 开头的表，分布在几个域里：ACT_RE_（流程定义和流程模型）、ACT_RU_（运行时）、ACT_HI_（历史）、ACT_ID_（身份信息）、ACT_GE_（通用数据）。验证方式直接查数据库：

SELECT table_name FROM information_schema.tables WHERE table_schema = 'activiti_test' AND table_name LIKE 'ACT\_%';

正常情况下列表里应该同时出现 ACT_RE_PROCDEF、ACT_RU_TASK、ACT_HI_PROCINST、ACT_GE_BYTEARRAY 这些核心表。如果一张表都没有，先确认数据库账号有建表权限；如果只建了一半就停下，大概率是字符集或表名大小写问题，这部分在第 5 章细说。

这一步还有一个容易被忽略的点：buildProcessEngine()默认创建的引擎 id 是default。如果同进程里再次调用同样代码，会得到同一个引擎实例（单例缓存），而不是重新建一遍。你可以在跑完代码后调用：

System.out.println(ProcessEngines.getProcessEngines().keySet());

看到输出里有default，说明引擎已经注册到全局缓存。后续代码里直接ProcessEngines.getDefaultProcessEngine()就能拿到同一个实例，不需要重新配置。这也是为什么很多基于 5.17.0 的老项目工具类里到处是ProcessEngines.getDefaultProcessEngine()的原因。

3. 让第一个流程实例跑通：BPMN、部署与启动参数

引擎起来后，下一件事是部署一条真实流程。这一章用手写 BPMN 文件的方式走完全流程：写文件 → 部署 → 查询流程定义 → 启动实例。整个过程里最容易出错的不是 Java 代码，而是 XML 文件里的命名空间和表达式写法。

3.1 一个能直接用的请假审批流程 BPMN

下面这个文件是略去布局信息的最小 BPMN 2.0 流程，包含一个开始事件、两个用户任务、一个排他网关、一个结束事件。注意文件后缀用.bpmn20.xml，这是 5.17.0 部署时识别最稳的命名方式。

<?xml version="1.0" encoding="UTF-8"?> <definitions xmlns="http://www.omg.org/spec/BPMN/20100524/MODEL" xmlns:activiti="http://activiti.org/bpmn" targetNamespace="http://example.com/leave"> <process id="leaveProcess" name="请假审批流程" isExecutable="true"> <startEvent id="start" name="开始"/> <sequenceFlow id="flow1" sourceRef="start" targetRef="apply"/> <userTask id="apply" name="提交请假申请" activiti:assignee="${submitter}"/> <sequenceFlow id="flow2" sourceRef="apply" targetRef="approve"/> <userTask id="approve" name="审批" activiti:assignee="${approver}"/> <sequenceFlow id="flow3" sourceRef="approve" targetRef="gateway"/> <exclusiveGateway id="gateway" name="是否通过"/> <sequenceFlow id="flowPass" sourceRef="gateway" targetRef="end"> <conditionExpression xsi:type="tFormalExpression">${approved == true}</conditionExpression> </sequenceFlow> <sequenceFlow id="flowReject" sourceRef="gateway" targetRef="apply"> <conditionExpression xsi:type="tFormalExpression">${approved == false}</conditionExpression> </sequenceFlow> <endEvent id="end" name="结束"/> </process> </definitions>

两个新手必踩的点：第一，activiti:前缀的命名空间声明不能漏，activiti:assignee依赖它，漏了会直接部署失败；第二，${approved == true}这种表达式是 JUEL 语法，布尔值直接比较就行，不用加引号。字符串比较才需要引号，比如${approved == 'true'}。

我把这份文件放在src/main/resources/diagrams/leave.bpmn20.xml下，接下来用它做部署测试。

3.2 部署流程定义：关键在 latestVersion

部署动作由 RepositoryService 负责。部署的本质是把 BPMN 文件打包成一个 Deployment 对象入库，引擎再从中解析出 ProcessDefinition。同一个流程如果部署两次，会生成两个版本，但 key 相同。

RepositoryService repositoryService = processEngine.getRepositoryService(); // 部署：addClasspathResource 可以多次调用，支持一个包带多个文件 Deployment deployment = repositoryService.createDeployment() .addClasspathResource("diagrams/leave.bpmn20.xml") .name("请假流程") .deploy(); // 查询最新版本的流程定义 ProcessDefinition definition = repositoryService.createProcessDefinitionQuery() .processDefinitionKey("leaveProcess") .latestVersion() .singleResult(); System.out.println("流程定义ID: " + definition.getId()); System.out.println("版本号: " + definition.getVersion());

逻辑说明：processDefinitionKey对应 BPMN 文件里<process id="leaveProcess">这个 id，不是文件名。latestVersion()会按 key 分组取版本号最大的那个，这个限定在重复部署后尤其重要，否则singleResult()会因为查到多行而抛异常。

deployment.getId()和definition.getId()是两回事：前者是部署包 id，后者是流程定义 id，格式通常像leaveProcess:1:某个数字。启动流程实例时用的是 key 或定义 id，不是部署 id。

3.3 启动流程实例：businessKey 和 variables 的配合

流程定义是“图纸”，流程实例是“按图纸跑起来的具体业务”。启动时通常要传两个东西：业务单据编号（businessKey）和流程变量（variables）。业务上最典型的例子是“工单号或请假单号”。

RuntimeService runtimeService = processEngine.getRuntimeService(); IdentityService identityService = processEngine.getIdentityService(); Map<String, 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("流程实例ID: " + processInstance.getId()); System.out.println("业务编号: " + processInstance.getBusinessKey());

参数说明：startProcessInstanceByKey有三个重载版本，第二个参数是 businessKey，第三个是 variables。businessKey 建议填业务单据的唯一编号，不要填自增数字；后续用historicProcessInstanceQuery().processInstanceBusinessKey("LEAVE-2024-001")可以精确找回这个实例关联的所有历史数据。

这里的 variables 会直接影响流程走向：submitter决定第一个用户任务的办理人，approver决定审批任务的办理人。如果漏了这两个变量，任务是能创建出来的，但 assignee 字段是空的，这帮任务不会出现在任何人的待办列表里，只能靠taskQuery().taskUnassigned()捞出来——这是第 5 章要展开讲的一个经典坑。

还有一点要注意：identityService.setAuthenticatedUserId("user01")这行在某些团队代码里会出现，作用是为历史记录里“发起人”字段赋值，不是流程执行的必需条件。老系统里常见，但无关流程能否跑通，建议把它和业务操作解耦。

4. 审批流转的三种常用姿势：任务、变量、会签与驳回

流程实例启动后，真正的业务量都在“审批”上。这一章覆盖三个最常见诉求：普通单人审批、条件网关分支、会签和驳回。5.17.0 在 API 上非常直白，但表达式的细节决定流程走的对不对。

4.1 待办任务查询与 complete 的完整链路

审批人打开待办列表，本质是查询 ACT_RU_TASK 表里 assignee 等于自己或者候选人是自己的任务。完成审批则有两条路：直接 complete，或先 setAssignee 再 complete。代码如下：

TaskService taskService = processEngine.getTaskService(); // 查询 user02 的待办任务 List<Task> tasks = taskService.createTaskQuery() .taskAssignee("user02") .orderByTaskCreateTime() .desc() .list(); for (Task task : tasks) { System.out.println(task.getId() + " -> " + task.getName()); } // 完成第一个任务，并传递审批结果变量 Task task = tasks.get(0); Map<String, Object> taskVars = new HashMap<>(); taskVars.put("approved", true); taskService.complete(task.getId(), taskVars);

逻辑说明：taskAssignee("user02")查的是办理人已经明确分配给 user02 的任务。如果团队用候选人模式，比如任务分配给一个角色组，需要改成taskCandidateUser("user02")，并且 complete 时引擎会校验 user02 是否是候选人。complete方法执行时，引擎会顺着当前节点的出口 SequenceFlow 走，遇到排他网关时用表达式的值决定走哪个分支。

任务变量和流程变量是两套存储：complete(taskId, vars)里传入的变量写入的是流程变量（ACT_RU_VARIABLE），不是任务本地变量。如果只想给当前任务附加数据而不影响流程走向，应该用taskService.setVariableLocal(taskId, "key", value)。我见到的错误大多是该用 local 的地方用了全局，导致后续流程的表达式被不该存在的变量影响。

4.2 排他网关的条件表达式：类型决定写法

排他网关（ExclusiveGateway）在 5.17.0 里是默认网关，遇到多条出口线时会从上到下找第一个条件为 true 的线。上一章的请假流程里，网关的两条线分别用approved == true和approved == false判断。这里是 JUEL 表达式，类型很敏感：

团队里最常见的玄学现场：${approved}单独作为条件表达式，当 approved 是 true 时确实为真，但当它只是“存在但值为 null”时，表达式会抛异常而不是走 false 分支。所以条件判断宁可写完整，也不要省略比较对象。另一个习惯是把流程结果的枚举值（如 “PASS”、“REJECT”）用字符串变量传，可读性比布尔值高，但记得在 gateway 两条线上都写条件，并在最后留一条无条件的默认线，防止变量缺失时直接抛异常。

4.3 会签节点与“驳回”的常见实现方式

5.17.0 支持 BPMN 2.0 的多实例活动（multiInstanceLoopCharacteristics），会签就是靠它实现的。下面是一个 60% 通过即放行的多人会签节点：

<userTask id="multiApprove" name="多人会签" activiti:assignee="${currentApprover}"> <multiInstanceLoopCharacteristics isSequential="false" activiti:collection="${approverList}" activiti:elementVariable="currentApprover"> <completionCondition>${nrOfCompletedInstances >= nrOfInstances * 0.6}</completionCondition> </multiInstanceLoopCharacteristics> </userTask>

参数说明：approverList是启动流程时传入的 List 变量；currentApprover是引擎在每次循环时自动生成的局部变量，代表当前要处理的审批人；isSequential="false"表示并行会签，每个任务同时生成，而不是排着队来。completionCondition 是完成条件表达式，默认全部处理完才算完成，写了这个条件后，达到 60% 就会提前结束。

注意缺失场景：如果启动流程时没传approverList，或传的 List 为空，这个节点运转时会报ActivitiException，提示无法解析集合。这属于启动参数校验问题，我会在启动流程前先用业务代码校验集合是否为空，而不是等引擎运行到一半才炸。

驳回在 5.17.0 里没有像 7.x 那样的专用 API，最常见做法是我在第 3 章 BPMN 里展示的回退流：审批网关条件为 false 时指向“重新申请”任务，让提交人修改后再提交。简单、可追踪、历史记录完整，比直接调用底层 jump 更安全。如果确认团队对底层 API 有把握，也可以走runtimeService.createProcessInstanceModification()，但不建议在核心业务里冒这个险。做出决定前，先问自己：审批记录要不要留痕？驳回后要不要改表单数据？网关回退在这两点上都占优势。

5. 避坑：5.17.0 最常见的五个翻车现场

这一章写的每个坑都是真实会让项目半夜响电话的那种。按“现象 → 原因 → 解决”的格式展开，顺序大致按从环境到代码再到运维排。

5.1 Linux 下表名大小写导致引擎找不到表

现象：同一个应用在 Windows 开发机上跑得好好的，部署到 Linux 测试环境后，引擎启动报错，提示找不到 ACT_HI_PROCINST 或 ACT_ID_GROUP，数据源连接正常但建表永远不完整。

原因：MySQL 在 Linux 上默认区分表名大小写（lower_case_table_names=0），而 5.17.0 的建表 SQL 里表名大小写混用，部分语句用小写表名，部分用大写。开发环境 MySQL 不区分大小写，所以掩盖了问题。

解决：第一时间检查 MySQL 配置，在[mysqld]段加lower_case_table_names=1并重启数据库；如果数据库已经建好，需要先把旧表导出备份，删除库后重建。对已经上线的库，更稳妥的方式是手工执行官方 SQL 脚本建表，然后把setDatabaseSchemaUpdate改成false，让应用不再参与建表动作，从源头避免大小写探测。

5.2 中文乱码：流程定义名、任务名全是问号

现象：BPMN 文件里写了中文名称，部署后查询流程定义，显示name字段是“???”，任务节点名字在流程图里也乱码。

原因：串了两个环节。第一，BPMN 文件本身不是 UTF-8 编码，某些 Windows 编辑器会默认存成 GBK；第二，JDBC 连接没有显式声明字符集，MySQL 会话使用默认 latin1，入库时按单字节存转义符号。

解决：BPMN 文件统一保存为 UTF-8 无 BOM 格式，编辑器右下角能看编码；JDBC 连接串带上useUnicode=true&characterEncoding=utf8，两个参数成对出现，缺一个都不生效。注意 5.17.0 年代用的 MySQL 驱动是 5.1.x，参数名必须这样写。改完连接串后，已经乱码的数据需要重新部署流程，历史数据不会自动修复。

5.3 依赖冲突：应用启动直接 NoSuchMethodError

现象：Web 应用引入 activiti-engine 5.17.0 后，Spring 容器启动时报NoSuchMethodError或ClassNotFoundException，堆栈指向org.springframework.expression或org.apache.ibatis。

原因：5.17.0 对传递依赖的版本管理很松散，尤其 mybatis 和 spring-expression。项目里已有的 mybatis 3.4+ 与内置的 mapper 映射不兼容，或者 Spring 4 的 expression 模块和引擎依赖的版本不一致，都会在运行时爆发。

解决：跑mvn dependency:tree -Dincludes=org.activiti,org.mybatis,org.springframework看完整依赖树，找到实际生效的版本号。常见做法是在项目的 dependencyManagement 里把 mybatis 锁定到 3.2.x（5.17.0 适配较好的版本），同时确认 Spring 版本在 3.x 或 4.x 的早期版本区间，避免直接用 Spring 4.3 以上的新特性。如果项目已经用了新版本 mybatis，且升级引擎不现实，优先级应该是评估接口隔离，而不是继续在依赖里硬压版本。

5.4 待办任务永远查不到：assignee 变量缺失

现象：流程实例启动了，数据库里 ACT_RU_TASK 也有任务记录，但taskAssignee("某用户")查询结果为空。再一查原表，任务的 ASSIGNEE_ 字段是 NULL。

原因：BPMN 里写的activiti:assignee="${submitter}"用了表达式，但启动流程时 variables 里没有 submitter 或 submitter 为 null。引擎不会在启动时校验变量是否存在，只会在创建任务节点时把表达式求值结果写入 ASSIGNEE_ 字段；求值为 null 时，字段就是 NULL。NULL 的任务不会出现在任何人的待办列表里，但流程会一直停在那个节点。

解决：在startProcessInstanceByKey之前，用业务代码对必填流程变量做校验。我习惯写一个启动前的变量检查方法，手动校验submitter、approver、approverList这些 BPMN 里引用到的 key，缺一个就抛业务异常，宁可在启动时拒绝，也不要让流程默默停摆。如果线上已经出现这种任务，补救方法是taskService.setAssignee(taskId, "user02")手动补上办理人，再让用户继续操作。

5.5 历史表无限膨胀：没有归档策略

现象：上线半年后，ACT_HI_ACTINST 表数据量达到上千万行，历史流程查询接口响应从毫秒级变成秒级，数据库所在服务器 IO 频繁告警。

原因：5.17.0 引擎默认historyLevel是 audit，对流程实例、活动实例、任务、变量全量记录，且没有任何自动归档清理机制。很多业务系统上线后完全没处理历史表，导致数据量线性增长。

解决：分三个动作处理。第一，评估历史数据必要程度，把setHistoryLevel调整到HISTORY_ACTIVITY或HISTORY_NONE减少写入量（注意会丢失变量历史，降级前要确认业务可接受）；第二：定时清理三个月前的历史数据，直接按时间删除 SQL：

-- 按时间删除已完成流程的活动实例记录 DELETE FROM ACT_HI_ACTINST WHERE END_TIME_ IS NOT NULL AND END_TIME_ < '2024-01-01 00:00:00'; -- 清理任务实例 DELETE FROM ACT_HI_TASKINST WHERE END_TIME_ IS NOT NULL AND END_TIME_ < '2024-01-01 00:00:00';

第三，对还在运行的流程实例不要删，否则历史流程视图会断链。清理脚本放到定时任务里跑，建议先备份验证，压测到目标数据量后再全量执行。我见过因为没备份直接跑删除，结果误删未结束流程实例导致流程跳转断掉的情况，这操作没有后悔药。

6. 收尾技巧：批量任务用事务隔离，别让一个失败拖垮整批

老系统发展到后面，一定会遇到“批量审批”的需求：部门主管一次勾选几十张请假单，点一下批量通过。这个场景用 5.17.0 最直接的写法是循环调用 complete，但一不注意就会出一个大问题：循环里某个任务已被人抢办，complete 抛异常，整个循环中断，前面已完成的审批跟着回滚。因为 ProcessEngine 默认和 Spring 事务绑定在同一条事务链里，一处失败全部回滚。

我现在的习惯是：批量场景下，每个任务的 complete 单独提交，不共用外部事务。Spring 配置里给批量方法单独标记@Transactional(propagation = Propagation.REQUIRES_NEW)，或者干脆用编程式事务，让每个任务独立 commit。伪代码如下：

List<String> taskIds = getSelectedTaskIds(); for (String taskId : taskIds) { try { taskService.complete(taskId, buildApproveVars()); } catch (Exception e) { // 记录失败任务，继续处理后续任务 failedTaskIds.add(taskId); log.error("任务审批失败: taskId={}", taskId, e); } } if (!failedTaskIds.isEmpty()) { // 收集失败原因，给用户明确的失败清单，而不是一句“系统错误” throw new BizException("部分任务审批失败，已成功 " + (taskIds.size() - failedTaskIds.size()) + " 个"); }

另外推荐一个查询习惯：历史流程列表必须带分页，不要用list()一把梭。5.17.0 的 HistoryService 分页参数和 7.x 一样是listPage(firstResult, maxResults)，配合orderByProcessInstanceStartTime().desc()，能把接口响应稳定压在百毫秒内。加上 businessKey 过滤条件，能让“按单号查流程”这种高频操作直接命中索引，而不是全表扫描。

这套组合拳打下来，一个基于 activiti-5.17.0 的审批系统，还能再健康地跑好几年。老版本不值得盲目换，但值得被认真对待——先把批处理事务边界划清楚，把历史表归档做起来，剩下的交给时间验证。希望这篇笔记能帮到你，也祝你的流程引擎少一点半夜告警。

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