简介Activiti 6社区版中文用户指南面向Java开发人员、流程建模师及企业应用集成工程师帮助读者理解工作流引擎的部署、配置与二次开发。指南系统覆盖Activiti 6.0核心知识包含环境准备、ProcessEngine配置、数据库及JNDI数据源设置、Job Executor、邮件服务器配置、Spring/Spring Boot集成、BAR部署、流程版本控制以及BPMN 2.0标准中各类事件、网关、任务等完整构造说明。资源为1个独立docx文档约4.22MB已有1816位学习者下载阅读。读者可从中掌握快速入门步骤、Activiti API服务调用、单元测试方法、表达式与脚本应用以及计时器事件、信号事件、边界事件等关键BPMN元素的实际用法是系统学习工作流技术栈的实用参考资料。1. 拿到这份 Activiti 6 中文 用户指南 docx第一件事不是急着翻正文很多刚接手流程引擎的同事第一眼看到这个标题都会愣一下一份 docx 格式的 Activiti 6 中文用户指南到底能解决什么问题它不是源码包也不是某个项目的二次开发文档而是一份把“引擎搭建、表结构、部署方式、任务流转、配置调优”串在一起的离线知识库。对正在评估 Activiti 6 能不能接进现有系统的人来说这份指南的价值在于提前画出了边界哪些事情引擎帮你做了哪些事情必须自己写代码。你看完第一章基本能判断这个项目要不要引入看到第三章就能照着配置出一个能跑的最小引擎后面几张表和数据字典则是你真正部署到测试环境时反复翻的参考手册。2. 先搞清引擎骨架从 docx 目录里拆出表结构、服务与配置Activiti 6 是一个基于 BPMN 2.0 标准的工作流引擎核心思路是“流程定义与业务代码分离”。文档开头往往花很大篇幅讲 BPMN 概念很多人看着看着就困了。我的建议是反过来读先弄清引擎启动后数据库里会发生什么再回来看流程模型。这一章带你按“目录优先”的方式把这份中文用户指南拆成三块可操作的内容让你在写代码之前先知道自己在跟什么打交道。2.1 用户指南的正确读法一类一章跳过暂时用不上的一份常见的中文 Activiti 6 用户指南大致会按下面这样的章节结构组织。你不需要从头到尾逐字读而是按照项目阶段找对应章节。文档章节作用什么时候读安装与配置环境要求、数据库配置、引擎初始化搭环境当天必须读引擎架构与流程虚拟机流程如何被解析、执行理解原理时读一遍BPMN 2.0 模型元素用户任务、排他网关、子流程、事件定义画流程图前查阅五个核心服务接口Repository、Runtime、Task、History、Identity动手写代码前通读任务处理与操作签收、委派、转办、催办开发任务审批功能时精读流程实例与执行管理挂起、终止、变量作用域做流程控制功能时精读监听器与扩展点任务监听器、执行监听器、Spring 集成需要扩展业务时精读引擎配置参数数据库策略、历史级别、异步执行器部署前逐个对照表格清单与数据字典ACT_GE、ACT_RE、ACT_RU、ACT_HI排查问题随时翻我个人习惯是第一天只读“安装与配置”和“引擎架构”两部分然后立刻动手跑通一个流程之后写什么功能再回头查对应章节。文档不是小说你看完不敲一行命令三天后肯定忘干净。2.2 引擎启动时的骨架ProcessEngine 和它的服务是怎么被拼起来的Activiti 6 里一切动作都围绕一个核心对象展开ProcessEngine。它是引擎的门面内部由ProcessEngineConfiguration负责组装数据源、事务管理器、历史级别、命令拦截器等。你调用ProcessEngines.getDefaultProcessEngine()时引擎会去activiti.cfg.xml或 Spring 配置里读取参数然后初始化七张分类下的数据表。常见做法是自己显式构建ProcessEngineConfiguration而不是完全依赖默认配置。原因很简单实际项目里数据源一定是你自己配的事务管理器也要跟 Spring 的事务边界对齐。引擎本身是“命令模式”设计你调用某个 Service 方法时其实是往命令执行器里塞了一个命令由拦截器链统一处理事务和日志。理解这一点对后面排查“为什么数据没提交”“为什么 SQL 没执行”非常有帮助。// 显式构建引擎配置使用本地 MySQL ProcessEngineConfiguration config ProcessEngineConfiguration .createStandaloneProcessEngineConfiguration() .setJdbcUrl(jdbc:mysql://localhost:3306/activiti_test?useUnicodetruecharacterEncodingutf8) .setJdbcUsername(root) .setJdbcPassword(123456) .setDatabaseSchemaUpdate(true) .setHistoryLevel(HistoryLevel.FULL.getLevel()); ProcessEngine processEngine config.buildProcessEngine();这段代码把数据库连接和初始化策略都写死了databaseSchemaUpdate设为 true引擎启动时会自动检查并创建缺失的业务表适合开发阶段。生产环境我建议改为false由专门的脚本管理表结构变更。historyLevel决定历史数据记录到多细业务上有审计需求就设 FULL否则设 AUDIT 可以减少很多冗余数据。2.3 7 张基础表与五个核心服务文档里最值得反复看的清单Activiti 6 的数据表按前缀分了四类搞清它们你就掌握了引擎的存储逻辑。ACT_RE_是流程定义和模型等静态资源ACT_RU_是运行中的流程实例、任务、变量等临时数据流程结束后会被清掉ACT_HI_是所有历史数据相当于流程的档案ACT_GE_存放通用数据比如流程图的二进制内容。表名前缀典型表存什么生命周期ACT_RE_ACT_RE_PROCDEF、ACT_RE_DEPLOYMENT流程定义与部署包长期保存ACT_RU_ACT_RU_TASK、ACT_RU_EXECUTION、ACT_RU_VARIABLE运行中任务和执行流实例结束即清理ACT_HI_ACT_HI_PROCINST、ACT_HI_TASKINST、ACT_HI_ACTINST历史实例、任务、活动节点一直保留ACT_GE_ACT_GE_BYTEARRAY、ACT_GE_PROPERTY流程图文件、引擎属性长期保存ACT_ID_ACT_ID_USER、ACT_ID_GROUP身份信息不用可跳过核心服务里你最先接触的通常是这三个RepositoryService负责流程定义和部署包的增删改查RuntimeService负责启动流程实例和设置流程变量TaskService负责查询、认领、审批用户任务。其余如HistoryService查历史数据ManagementService做引擎管理按需学习即可。记住这张表后面文档里所有配置参数才不会显得无厘头。3. 照着指南搭的第一个可跑引擎依赖、部署与任务闭环理论看再多不如亲手把引擎跑起来。这一章我们从零搭一个最小可运行环境中间会踩到不少坑包括依赖版本冲突、流程文件放错目录、部署成功但查询不到任务等。我把常见做法展开写你照着操作大概半小时就能看到第一个流程实例落地。3.1 最小 Maven 依赖用最小集合跑通Activiti 6 的工程依赖比 5.x 清爽一些但如果你直接搜“activiti 依赖”很容易被网上各种组合带偏。最常见做法是引入activiti-engine再用 H2 或 MySQL 作为数据源。下面是适合本地调试的依赖组合。dependency groupIdorg.activiti/groupId artifactIdactiviti-engine/artifactId version6.0.0/version /dependency !-- 本地调试用内存数据库打包时排除 -- dependency groupIdcom.h2database/groupId artifactIdh2/artifactId version1.4.200/version scoperuntime/scope /dependency !-- 与 Spring 集成时才需要 -- dependency groupIdorg.activiti/groupId artifactIdactiviti-spring/artifactId version6.0.0/version /dependencyactiviti-engine是引擎本体里面包含了 BPMN 解析、流程虚拟机、命令执行器等核心模块。activiti-spring负责把引擎对象交给 Spring 管理没有它你也能跑但事务边界和对 Bean 的注入就得自己处理后面会很痛苦。H2 的scope设为 runtime意味着编译期不引用只在运行时提供驱动这是为了避免在业务代码里直接依赖某个数据库。3.2 部署一条 BPMN 流程流程定义、部署包和流程实例的关系很多新手容易把“部署流程”和“启动流程”混在一起。部署是把一个.bpmn20.xml流程文件交给引擎保存相当于注册了流程的类型启动才是真正创建一个执行实例。流程文件放在src/main/resources/processes/下下面是部署代码。// 部署一条请假流程 RepositoryService repositoryService processEngine.getRepositoryService(); Deployment deployment repositoryService.createDeployment() .addClasspathResource(processes/leave.bpmn20.xml) .name(请假流程) .deploy(); System.out.println(部署 ID deployment.getId());部署完成后引擎会解析 XML 里的 BPMN 元素校验网关、事件、任务节点是否合法。addClasspathResource是从 classpath 加载文件路径必须是processes/下的相对路径如果你用addInputStream则文件放哪都行。这里有个关键点同样一条流程可以重复部署每次部署会产生一个新的流程定义版本业务流程还在等待旧版本但新审批会使用新版本这是很常见的问题后面避坑章节再细说。3.3 任务的发起与审批第一个完整闭环部署完流程定义我们来走一遍完整流程启动实例、查询任务、审批任务。下面的代码假定流程里有一个用户任务节点审批人字段是assignee。// 启动流程实例 RuntimeService runtimeService processEngine.getRuntimeService(); ProcessInstance instance runtimeService .startProcessInstanceByKey(leave); System.out.println(流程实例 ID instance.getId()); // 查询这个实例下某个人待办的任务 TaskService taskService processEngine.getTaskService(); ListTask tasks taskService.createTaskQuery() .processInstanceId(instance.getId()) .taskAssignee(zhangsan) .list(); System.out.println(待办数量 tasks.size()); // 审批第一笔任务 if (!tasks.isEmpty()) { taskService.complete(tasks.get(0).getId()); }startProcessInstanceByKey用的是 BPMN 文件里process元素的id属性不是文件名。流程启动后TaskQuery里taskAssignee用的昵称是租户处理人不是数据库表里的用户主键。如果查出来的任务数量是 0先确认你查询条件写对没有大概率是assignee没设或者设给了别人。complete之后引擎会自动推进流程走向下一个节点如果后面还有任务再次用taskService查询就能看到新任务。4. 把指南落进 Spring Boot事务、表前缀与流程可视化到目前为止我们用的是独立引擎真实业务很少这么干。绝大多数项目会把流程引擎嵌进 Spring Boot让引擎的事务与业务事务共用一个DataSource和TransactionManager。这一章的配置项都是中文用户指南里容易一笔带过、但实际部署时异常关键的参数。4.1 集成 Spring Boot 的初始化配置我们常用的是基于activiti-spring自动装配的方式。在application.yml里配置好数据源引擎启动时会复用同一份数据源避免出现“引擎连一个库、业务连另一个库”的尴尬局面。spring: datasource: url: jdbc:mysql://localhost:3306/activiti_test?useUnicodetruecharacterEncodingutf8 username: root password: 123456 driver-class-name: com.mysql.cj.jdbc.Driver activiti: database-schema-update: true history-level: full db-history-used: true async-executor-activate: falsedatabase-schema-update: true在集成模式下依然只建议开发环境开启。history-level: full记录所有流程变量快照、活动实例信息适合后续做审批历史追溯。async-executor-activate: false是很多人会忽略的坑如果流程里没有定时器、异步延续等需求关掉异步执行器能少很多后台线程和死锁日志。等你真的需要异步节点时再打开并把线程池参数调好。引擎的事务边界可以用一个简单的架构说明每次服务方法调用都会在一个事务里执行完从任务查询到任务提交的全部动作。Spring 配置的事务管理器会包住这个边界所以你不必手动调用saveOrUpdate只要方法正常返回整个流程节点推进、变量更新就一并提交了。若方法中途抛出异常所有已执行的任务操作也会回滚。4.2 任务监听器业务流程里最常被用错的扩展点用户指南里必然有“监听器”这一节但很多人要么不用要么把监听器当成万能钩子在create事件里写一堆业务代码。常见做法是用任务监听器给任务指定处理人或动态设置任务截止时间。下面是一个在任务创建时自动指定审批人的示例。public class DeptManagerTaskListener implements TaskListener { Override public void notify(DelegateTask delegateTask) { // 任务创建时设置处理人 if (EVENTNAME_CREATE.equals(delegateTask.getEventName())) { // 这里可以从业务表查询实际审批人 delegateTask.setAssignee(dept-manager); } } }在 BPMN 文件中给用户任务节点加入监听器配置userTask idapproveTask name部门审批 extensionElements activiti:taskListener eventcreate classcom.example.listener.DeptManagerTaskListener/ /extensionElements /userTask监听器的执行时机在任务插入数据库之后引擎提交事务之前。这里最容易踩的坑是在监听器里调用了外部服务而外部服务又依赖数据库查询结果因为事务还没提交查不到刚创建的任务。解决办法有两种要么把外部调用改成事件发布等事务提交后异步处理要么在监听器里直接使用DelegateTask传过来的流程变量尽量减少反向查询。4.3 让非技术人员看到流程动态生成流程图用户指南会提到一个实用的能力根据流程实例的运行位置生成一张标记了当前节点的流程图。这在给业务方演示“流程走到哪一步”时特别有用。开发阶段很多人卡在中文乱码这里给一个可用方案。// 生成当前流程实例的流程图 ProcessDiagramGenerator generator processEngine.getProcessDiagramGenerator(); BpmnModel bpmnModel repositoryService .getBpmnModel(processInstance.getProcessDefinitionId()); InputStream diagram generator.generateDiagram( bpmnModel, 宋体, 宋体, 宋体, processEngine.getRepositoryService(), highLightedFlows, highLightedNodes);generateDiagram方法的三组字体参数分别控制节点名称、事件名称和备注文字必须传入服务器上真实存在的字体否则中文全部显示成方框。highLightedFlows是高亮的连线 ID 集合highLightedNodes是当前活动节点 ID 集合把运行中任务的节点 ID 传进去生成的图就会把当前步骤标红。这个功能建议封装成一个独立接口业务方随时可以查看流程图比让他们翻数据库直观得多。5. Activiti 6 中文 用户指南 落地避坑5 个高频翻车点文档归文档实际部署时总会冒出一些“文档里写了但你根本没注意”的问题。这一章整理了我自己和身边同事在这些年踩过的 5 个高频坑每条都是现象、原因、解决一条龙。有些问题网上讨论很多但中文资料里往往只有零散答案这里集中写清楚。5.1 流程任务和流程图里的中文全部变成问号现象引擎部署正常但在任务列表里看名称是“”调用流程图生成接口图片里的中文全是方框。原因有两层。第一层是数据库连接没有指定 UTF-8 字符集MySQL 默认排序规则可能让中文在写入时变成乱码第二层是服务器操作系统缺少对应的中文字体或者 JVM 默认字符集不是 UTF-8。解决数据库连接串必须像前面写的那样加上useUnicodetruecharacterEncodingutf8生成流程图时把字体参数明确指定为服务器上存在的字体并确认系统装了fontconfig和相应字体包。也可以在 JVM 启动参数里加上-Dfile.encodingUTF-8避免某些环境默认使用 GBK。5.2 引擎启动时报 schema 版本不匹配现象项目第一次启动抛出类似“Could not update Activiti database schema”或版本号对应不上的异常ActivitiWrongDbException。原因这台机器上的数据库里已经存在一套其他版本引擎建的表常见于之前跑过 Activiti 5.x 的演示项目。表结构里ACT_GE_PROPERTY会记录当前 schema 版本6.x 引擎发现留存版本不同就拒绝写入。解决在开发环境直接把所有ACT_*表全部删掉让引擎重建如果是联调环境先备份数据再删表重建。不要试图手动改ACT_GE_PROPERTY的版本号硬凑Activiti 6 的表结构和老版本差异很大硬改只会引发后面更隐蔽的 SQL 报错。生产环境的升级需要做完整的数据迁移脚本而不是删表。5.3 流程部署成功但任务查询结果始终为空现象deployment.deploy()执行成功流程实例也能启动taskService.createTaskQuery().list()却返回空。原因最常见的是查询条件写错。assignee对应的是办理人在引擎中的用户 ID但流程 XML 里写的是候选组或候选人例如activiti:candidateGroupshr这时任务没有明确的assignee用taskAssignee查当然查不到。第二个常见原因是任务在并行网关之后查询时任务还没创建到数据库需要等异步逻辑执行完。解决排查时先去掉所有过滤条件直接查整个流程实例下的任务列表确认任务存在后再回推条件写法。候选组方式用taskCandidateGroup查询候选用户方式用taskCandidateUser查询。如果任务确实没生成检查流程引擎日志里有没有节点跳转失败或者监听器里抛出的异常被吞掉。5.4 集成后 Spring Boot 版本与 Activiti 6 不匹配现象应用能启动但一旦调用引擎服务就抛出NoSuchMethodError、ClassNotFoundException或者 Bean 注入失败的提示。原因Activiti 6 的 Spring 集成代码是在特定版本 Spring 环境下编译的如果项目的 Spring Boot 版本升得非常高自动配置类里引用的某些内部类路径已经变了。最常见的是spring-jdbc与spring-tx的 API 变化导致引擎装配时找不到方法。解决做项目选型时先确认要用的 Activiti 6 对应推荐的 Spring Boot 版本范围尽量保持主版本一致。如果团队坚持使用较新的 Boot 版本就不要依赖它的自动配置改为显式声明ProcessEngineConfiguration和ProcessEngineBean完全自主控制版本依赖方向。这条经验也提醒我们非必要不要混用工作流引擎和最新框架工作流引擎的价值是稳定。5.5 中文文档版本与实际引擎代码版本不同步现象照着 docx 里的配置项写启动时发现某个属性已经不存在或者属性名提示是错误的。原因翻译和整理的文档往往基于引擎某个早期发行版本后续引擎补丁、修复没有同步更新到这份中文文档里比如某些set方法改名、某些 XML 配置被新注解替代。这是离线知识库的通病不是这份文档独有。解决办法以 jar 包内部源码为准。把activiti-engine源码包下到本地遇到参数不生效时直接搜索对应类的setXxx方法看是否还对外暴露。文档的价值是建立整体概念和常用路径具体细节必须对照本地依赖版本。6. 用户指南吃透之后给流程模型建立回归测试和体检当你照着一份中文用户指南把一个引擎跑通、把第一批业务流程部署上线后真正的长期工作才刚刚开始。工作流引擎最怕的不是写不出来而是改坏了没人知道。我习惯把流程模型当成业务代码一样维护给每个流程建一个最小回归测试每次改动流程 XML 或监听器跑一遍再说。6.1 一个能跑的开发期回归测试模板public class LeaveProcessTest { private ProcessEngine processEngine; Before public void setup() { processEngine ProcessEngines.getDefaultProcessEngine(); } Test public void shouldCompleteLeaveProcess() { ProcessInstance pi processEngine.getRuntimeService() .startProcessInstanceByKey(leave); Task task processEngine.getTaskService().createTaskQuery() .processInstanceId(pi.getId()).singleResult(); Assert.assertNotNull(流程启动后应生成第一个任务, task); processEngine.getTaskService().complete(task.getId()); // 断言流程实例已结束 Assert.assertEquals(0, processEngine.getHistoryService() .createHistoricProcessInstanceQuery() .processInstanceId(pi.getId()) .finished() .count()); } }这个模板的意义不仅仅是验证“流程能走通”而是每次改动后能快速感知流程结构是否被破坏。比如你给中间节点加了一个必填变量旧测试立刻会挂方便尽早发现。把这份测试跑在内存数据库上几秒钟就能完成不需要真实环境。6.2 通过历史数据做一次引擎体检等流程跑了一段时间ACT_HI_PROCINST和ACT_HI_TASKINST里的数据就是你优化流程的最好依据。我常用的几个统计维度包括流程实例平均完成时长、某个人或某个组的平均处理时长、挂起超过 7 天的实例列表。这些数据用一遍HistoryService查询出来导成报表能直接指出流程瓶颈出在哪个节点。经常有同事找我说“流程卡住了”我打开历史表一看往往是在某个审批人手里停了三四天这其实不是引擎问题是流程设计问题。工作流引擎能帮你把“停留时长”记录下来但推动人去审批还得靠业务机制。6.3 把离线知识库变成团队常态这份中文用户指南的价值会随着使用而递减因为引擎版本总在变。我现在的做法是把它当成团队新人的入门教材但在项目内部另维护一份实践笔记按真实项目形态记录配置项和踩坑记录。新人先读 docx 了解整体再对照实践笔记接入具体项目两三天就能上手。每当发现与文档描述不符的地方顺手在原文档里做批注定期组织统一梳理。以前我总迷信文档本身遇到问题先翻书后来吃过几次亏才明白工作流引擎这类中间件的文档更多是给你一个完整的认知框架。真正的细节边界必须靠自己的代码和测试去验证。把流程定义当代码一样管理把引擎配置当接口一样评审项目才能走得更稳。希望帮到你。本文还有配套的精品资源点击获取