Activiti6中文文档实战：工作流引擎配置、BPMN与二次开发-北京尧图网络

简介《Activiti6 中文用户指南.docx》面向工作流开发初学者与需要落地BPMN 2.0流程的Java工程师系统梳理Activiti6的安装配置、核心API、Spring集成与BPMN元素用法可帮助读者快速理解流程引擎的运行机制并用于项目实践。资源包仅含1个docx文档压缩包约4.22MB内容以中文译文形式组织涵盖一分钟入门、ProcessEngine配置、数据库与JNDI数据源、Job Executor、表达式脚本、单元测试、BAR部署以及计时器、错误、信号、消息等事件定义与边界事件、中间捕获事件等BPMN 2.0构造目录层级清晰便于按主题检索。目前已有1816人学习下载适合作为案头查阅手册也可作为团队内部培训与项目落地的参考材料。读者可从中获得从环境搭建、流程建模到部署执行与问题排查的完整知识框架尤其适合对照官方文档查漏补缺提升Activiti6的实际应用能力。1. 先弄清楚这份 Activiti6 中文文档能解决什么接手一个半停摆的审批系统时我最想要的不是源码而是一份能对着查的中文手册——源码能读但参数含义、表名规则、事件类型这些东西读源码效率太低。这份 Activiti6 中文用户指南 docx 就是这种定位十三章从一分钟把 war 包丢进容器跑起来到 BPMN 2.0 的事件、网关、子流程、多实例再到 REST 接口清单和历史表查询二次开发要碰的概念基本都在里面。它适合两类人刚接触工作流引擎、需要照着把环境和第一个流程跑通的新手已经写过几版审批流、需要一份参数与 API 速查表的老手。下面按我拆文档的顺序把骨架、配置、API 和踩坑点逐层摊开。2. 文档骨架与运行架构十三章节其实是三条线2.1 章节分组建模、引擎、接口三条主线这份指南的目录看着很长但按职责切一刀就清楚了。我一般把它分成四块读的时候不必从第一章顺着翻按手上的活去挑。章节范围覆盖内容什么时候翻它第 13 章简介、入门、配置搭环境、换数据库、调 Job Executor 时第 46 章API、Spring 整合、部署写部署与任务流转代码时第 711 章BPMN 简介与构造、表单、JPA、历史画流程图、定义事件与网关时第 1213 章Eclipse 设计器、REST API给前端或外部系统开放接口时第 7 章那个「10 分钟教程」是最值得先读的一节它把工艺图、XML 表示、启动实例、任务清单、领取、完成、结束串成一条完整链路读完再回头翻第 8 章的构造细节理解成本会低很多。第 8 章是全书最厚的一块事件定义、顺序流、网关、任务、子流程、事务与并发全在里面它更像字典而不是教程别指望一遍读完。第 13 章 REST API 按资源类型分节部署、流程定义、模型、流程实例、执行、任务、历史各成一节写对接文档时直接把对应小节抄成接口说明就行。有一点要提前说明第 1 章的许可证、下载、报告问题那几节属于发行信息跟二次开发关系不大快速略过即可真正影响落地的是「所需软件」里那条 JDK 7 的约束——这条决定了你后面能不能用 Java 8 的语法糖。2.2 ProcessEngine 与七个 Service 的分层关系文档第 3 章和第 4 章反复出现 ProcessEngine它是整个引擎的门面。从架构上看是三层最底下是 ProcessEngineConfiguration负责数据库、事务、缓存、异步执行器这些基础设施中间是 ProcessEngine一个重量级、线程安全的单例最上面是七个 Service业务代码只跟它们打交道。// 引擎的三层结构业务代码通常只持有 Service 引用 ProcessEngineConfiguration cfg ProcessEngineConfiguration .createStandaloneProcessEngineConfiguration(); // 第一层基础设施配置 ProcessEngine engine cfg.buildProcessEngine(); // 第二层引擎单例 RepositoryService repositoryService engine.getRepositoryService(); // 流程定义与部署 RuntimeService runtimeService engine.getRuntimeService(); // 运行中实例与变量 TaskService taskService engine.getTaskService(); // 人工任务 HistoryService historyService engine.getHistoryService(); // 历史数据 ManagementService managementService engine.getManagementService(); // 作业与引擎元数据 IdentityService identityService engine.getIdentityService(); // 用户与组 FormService formService engine.getFormService(); // 表单RepositoryService 管部署包和流程定义对应文档第 6 章的部署与版本控制RuntimeService 管流程实例和执行流对应第 4.3 节的启动、挂起、激活TaskService 管人工任务的领取、完成、评论、附件HistoryService 对应第 11 章那五种历史查询ManagementService 是异步作业和引擎属性的入口Job Executor 出问题时基本都从它查。把这层关系记住文档第 4 章那堆 API 就不再是散点。需要留意的是 ProcessEngine 是重对象创建一次要建连接池、加载配置、可能还要建表。常见做法是在应用启动时构建一次并注入容器而不是每个请求 new 一个。2.3 环境准备与 war 包一分钟跑通文档第 2.1 节的「一分钟版」是最快的验证路径适合先确认整条链路能跑再回头做正式配置。前提是装好 JDK 7 以上和一个 Servlet 容器。# 1) 确认 Java 版本低于 7 直接失败 java -version # 2) 把演示 war 包放进容器的 webapps 目录 cp activiti-app.war $TOMCAT_HOME/webapps/ # 3) 启动容器 $TOMCAT_HOME/bin/startup.sh # Windows 用 startup.bat # 4) 浏览器访问 http://localhost:8080/activiti-app # 默认账号 admin密码 test这段命令里没有玄学坑主要在后面这个演示应用默认使用内存数据库 H2进程一停数据全没重启后你昨天画的流程定义会消失第一次遇到会以为部署失败了。要换成 MySQL 之类的持久库得改应用内的数据源配置或者干脆跳过演示包、直接在自有工程里装配引擎。另外容器只用到 servlet 能力理论上任何容器都行但文档明确说主要在 Tomcat 上验证非 Tomcat 环境出问题时要先怀疑容器差异而不是引擎。启动成功后建议先用演示界面画一个只有开始、用户任务、结束三节点的流程走一遍部署和完成确认登录、建表、任务流转都正常再去接自己的业务代码。这一步花十分钟能省掉后面排查环境问题的一整天。3. 配置层拆解从 ProcessEngineConfiguration 到 Job Executor3.1 两种装配方式编程式与 Spring 托管配置是整个引擎最容易出错的地方文档第 3 章给了两条路。独立部署用 createStandaloneProcessEngineConfiguration 系列工厂方法Spring 环境用 SpringProcessEngineConfiguration 配合 ProcessEngineFactoryBean。// 独立部署显式给出连接信息适合批处理、测试或非 Spring 工程 ProcessEngineConfiguration cfg ProcessEngineConfiguration .createStandaloneProcessEngineConfiguration() .setJdbcUrl(jdbc:mysql://127.0.0.1:3306/activiti6?useUnicodetruecharacterEncodingutf8) .setJdbcDriver(com.mysql.jdbc.Driver) .setJdbcUsername(act) .setJdbcPassword(act) // true 表示启动时对比并自动建表 / 升级表结构 .setDatabaseSchemaUpdate(ProcessEngineConfiguration.DB_SCHEMA_UPDATE_TRUE); ProcessEngine engine cfg.buildProcessEngine();几个参数值得单独说。jdbcUrl 里的 characterEncoding 别省流程定义名、任务名带中文时少了它会出现乱码。databaseSchemaUpdate 三个取值false 不动作true 启动时检查并补齐缺失的表create-drop 是启动建表、关闭删表后者只适合单元测试在生产上用过一次就会知道什么叫血泪经验。工厂方法还有内存版和单例版测试里用内存版最省事。Spring 环境下的写法差异在于数据源和事务由容器托管!-- Spring 装配事务管理器必须交给引擎否则任务完成不会提交 -- bean idprocessEngineConfiguration classorg.activiti.spring.SpringProcessEngineConfiguration property namedataSource refdataSource/ property nametransactionManager reftransactionManager/ property namedatabaseSchemaUpdate valuetrue/ property nameasyncExecutorActivate valuetrue/ !-- 启动时自动部署 classpath 下 processes 目录的资源 -- property namedeploymentResources valueclasspath*:/processes/*.bpmn20.xml/ /bean bean idprocessEngine classorg.activiti.spring.ProcessEngineFactoryBean property nameprocessEngineConfiguration refprocessEngineConfiguration/ /beanProcessEngineFactoryBean 存在的意义就是让引擎参与 Spring 的事务一次 taskService.complete 内部可能写 ACT_RU_TASK、ACT_RU_EXECUTION、ACT_HI_* 好几张表必须在一个事务里提交或回滚。transactionManager 漏配的典型表现是任务完成了但流程不往前走因为数据没落库。3.2 数据库与 JNDI从 H2 内存库切到 MySQL文档第 3.3 到 3.8 节把数据库这块讲得比较细。引擎的所有表都带 ACT_ 前缀按职责分四组ACT_RE_ 是流程定义与部署这类「静态资源」ACT_RU_ 是运行中的实例、任务、变量、作业ACT_HI_ 是历史归档ACT_ID_ 是用户与组。排查问题时先按前缀定位效率比翻代码高得多。支持的数据库覆盖主流关系库切库时除了换驱动和 URL还要注意方言自动探测——引擎会读数据库产品名选方言云上某些兼容库报告的产品名对不上时会报方言找不到需要在配置里显式指定。建表策略生产环境建议先用 true 跑一次验证通过后改成 false避免每次启动都去比对表结构拉长启动时间。容器里不方便暴露账号密码时走 JNDI!-- 数据源由容器提供应用只按名查找 -- bean iddataSource classorg.springframework.jndi.JndiObjectFactoryBean property namejndiName valuejava:comp/env/jdbc/activiti/ /beanJNDI 这套的坑不在引擎在于命名前缀必须和容器里的资源名完全一致java:comp/env/ 少了任何一段都是启动即失败。文档第 3.4 节列了那几个 java.naming.* 属性用外部命名服务时才需要纯本地容器通常留空。3.3 Job Executor、历史级别与邮件服务器6.0 版本一个明显变化是 Job Executor 成了内建组件定时边界事件、异步任务、失败重试都靠它驱动。它默认可能不激活所以「画了定时器但到点不触发」是最高频的问题之一。cfg.setAsyncExecutorActivate(true) // 打开异步执行器定时与异步任务才会被扫 .setHistoryLevel(HistoryLevel.AUDIT) // 历史级别none / activity / audit / full .setMailServerHost(smtp.internal) .setMailServerPort(25) .setMailServerDefaultFrom(workflowexample.com);历史级别直接影响 ACT_HI_ 表的写入量和查询能力none 什么都不记查历史永远空activity 只记流程实例和活动节点audit 额外记任务和变量是多数业务系统的选择full 连变量明细都留数据量会涨得很快。我一般先按 audit 上需要审计追溯的少数流程再单独处理。邮件配置只有用到邮件任务或通知才需要填但它一旦配错表现是流程走到邮件节点后卡住而不是报错所以上线前务必发一封测试邮件。异步执行器的线程池默认大小对中小系统够用任务量大时再调调之前先确认瓶颈在作业数还是在数据库。4. BPMN 2.0 与 API 落地一个请假流程从建模到归档4.1 一份能跑通的 BPMN XML文档第 7、8 章加起来上百个小节全记住不现实。我的做法是先拿一份最小可用的流程定义当模板把用户任务、网关、定时边界事件这三个最常用的东西吃透剩下的按需查。?xml version1.0 encodingUTF-8? definitions xmlnshttp://www.omg.org/spec/BPMN/20100524/MODEL xmlns:activitihttp://activiti.org/bpmn targetNamespacehttp://example.com/leave !-- process 的 id 就是后面 startProcessInstanceByKey 用的 key -- process idleaveProcess name请假审批 isExecutabletrue startEvent idstart/ sequenceFlow sourceRefstart targetRefapplyTask/ !-- assignee 用表达式取流程变量提交人启动时传入 -- userTask idapplyTask name提交申请 activiti:assignee${starter}/ sequenceFlow sourceRefapplyTask targetRefapproveTask/ !-- 候选组审批谁先 claim 谁处理 -- userTask idapproveTask name主管审批 activiti:candidateGroupsmanager/ !-- 48 小时未处理则触发边界事件非中断式会另开一条分支 -- boundaryEvent idtimeout attachedToRefapproveTask cancelActivitytrue timerEventDefinition timeDurationPT48H/timeDuration /timerEventDefinition /boundaryEvent sequenceFlow sourceReftimeout targetRefautoPass/ userTask idautoPass name超时自动转交/ sequenceFlow sourceRefapproveTask targetRefend/ sequenceFlow sourceRefautoPass targetRefend/ endEvent idend/ /process /definitions几个关键点process 的 id 是业务代码里的流程 key改了它等于换了一个流程旧实例全部找不到定义activiti:assignee 和 activiti:candidateGroups 是引擎扩展属性标准 BPMN 里没有写错命名空间前缀会被当成未知属性静默忽略表现为任务没有办理人timeDuration 用 ISO 8601 时长格式PT48H 是 48 小时写 48h 解析不了。cancelActivity 决定边界事件是中断还是并行中断式会撤销原任务做超时升级时选它做超时提醒时选非中断。网关部分文档第 8.4 节列了排他、并行、包容、基于事件四种。排他网关走条件序列流条件写在 sequenceFlow 的 conditionExpression 里要注意所有分支都不满足时引擎会抛异常务必留一条默认流。并行网关的分支数在运行时才确定多实例配合它做会签是常见组合。4.2 五个 Service 串起的完整链路流程定义有了落地代码就是一条固定链路部署、启动、查任务、认领、完成、查历史。文档第 4.3 节的顺序和我实际写的顺序基本一致。// 1) 部署一个部署包可以带多个 BPMN 与附属资源 Deployment deployment repositoryService.createDeployment() .addClasspathResource(processes/leave.bpmn20.xml) .name(请假流程 v1) .deploy(); // 2) 启动第二个参数是 businessKey串起业务单据号 MapString, Object vars new HashMap(); vars.put(starter, zhangsan); ProcessInstance pi runtimeService.startProcessInstanceByKey( leaveProcess, LEAVE-20240101-001, vars); // 3) 查任务候选组查询与办理人查询是两个不同条件 Task task taskService.createTaskQuery() .processInstanceId(pi.getId()) .taskCandidateGroup(manager) .singleResult(); // 4) 认领完成认领会把候选人转成 assignee taskService.claim(task.getId(), lisi); taskService.complete(task.getId(), Collections.singletonMap(approved, true)); // 5) 归档流程结束后运行表数据清空只剩历史表 HistoricProcessInstance hpi historyService.createHistoricProcessInstanceQuery() .processInstanceId(pi.getId()) .singleResult();businessKey 这一项别偷懒它是流程实例和业务单据之间唯一的桥不传的话后面做「按单号查流程」只能靠变量捞慢且不准。claim 与 setAssignee 的区别要分清claim 会校验当前用户是否在候选范围内setAssignee 是管理员式直接指派用错会把权限校验绕过去。变量作用域也容易翻车taskService.complete 传的变量挂在流程实例上全局可见taskService.setVariableLocal 挂的只在该任务作用域内有效任务结束后就查不到了。第 4.4 节的查询 API 支持链式条件、排序、分页写列表页时务必带分页历史表数据量上去后全量查会把连接池打满。4.3 Spring Boot 下的自动部署与 REST 接口Spring Boot 环境把上面这些配置压缩成了几行 properties进程启动时自动扫描 classpath 下 processes 目录里的流程文件并部署这一点在开发期很方便但要注意每次启动都会产生新版本版本号会一直涨。spring: datasource: url: jdbc:mysql://127.0.0.1:3306/activiti6?characterEncodingutf8 username: act password: act activiti: database-schema-update: true async-executor-activate: true history-level: audit # 关闭自动部署改由运维在发布流程手动触发 check-process-definitions: false对外提供接口时文档第 13 章的 REST 模块可以直接拿来当接口规范也可以自己包一层 Controller 调 Service。用现成 REST 模块的话认证是基础认证分页参数是 start 和 size返回体里带 total 和 data 两个字段。# 查询候选组 manager 的待办任务size 控制单页条数 curl -u admin:test \ http://localhost:8080/activiti-rest/service/tasks?candidateGroupmanagerstart0size10调用时注意两点claim、complete 这类动作型接口在 REST 里是 POST 到 /runtime/tasks/{taskId} 并带 action 字段不是简单的 PUT涉及变量的接口要按文档给的 JSON 变量格式传直接传裸值会反序列化失败。5. 排查部署、事务、作业这三处最容易翻车5.1 启动与部署阶段先讲两条我在项目里遇到过不止一次的。现象应用重启后报「表已存在」或者反过来报某张 ACT_ 表不存在。原因多环境共用了同一个库而 database-schema-update 在不同环境配置不一致或者切换数据库产品后旧表结构没清干净。解决先确认当前连的是哪个库把 schema 更新策略统一成开发 true、测试 true、生产 false 的三段式生产环境的表变更走独立脚本不靠引擎自动改。现象流程文件明明放进去了startProcessInstanceByKey 却抛流程定义找不到。原因一是 XML 里 process 的 id 与代码里的 key 不一致二是文件后缀不匹配引擎只识别 .bpmn20.xml 和 .bpmn三是部署到了另一个数据源。解决用 repositoryService.createProcessDefinitionQuery().list() 把所有已部署定义打出来比对 key 和版本号再看 ACT_RE_PROCDEF 里的 DEPLOYMENT_ID_ 确认部署落在哪个库。5.2 运行与事务阶段现象定时边界事件到点不触发ACT_RU_JOB 表里查不到任何记录。原因异步执行器未激活或者作业根本没被创建比如 timeDuration 格式非法被跳过。解决先确认配置里 asyncExecutorActivate 为 true 且线程池没有被打满再查 ACT_RU_JOB 里是否存在该实例的作业有作业但不执行时用 managementService.executeJob 手动触发一次能立刻区分是调度问题还是执行报错。我第一次遇到这个排查了半天配置最后发现是定时器写成了「48h」。现象taskService.complete 返回正常但流程没往下走重启后任务又回来了。原因没有事务管理或者自行管理了 SqlSession 导致提交被吞Spring 环境里常见于漏配 transactionManager。解决确认引擎用的是容器事务管理器业务方法上加事务注解别在引擎事务里再嵌套一层不同的数据源。现象候选组的人登录后看不到任务。原因候选组名和 ACT_ID_GROUP 里的组名大小写或空格不一致或者任务既设了 assignee 又设了 candidateGroups认领逻辑被覆盖。解决先按 taskCandidateGroup 直接查一次查得到就是身份模块的问题查不到就是流程定义里属性写错再检查是否有监听器在创建任务时把办理人改掉了。现象流程结束后历史表里没有变量审计页面空白。原因history-level 配成了 none 或 activity变量级数据未记录。解决改成 audit 并重启注意这个改动对已产生的历史数据不追溯历史缺失只能靠业务日志补。6. 二次开发把文档当基线改扩展点并逐个验证真正开始改的时候我的顺序是先改配置层、再动流程定义、最后才写代码扩展点。配置层改动风险最低也最好验证——改完重启看引擎是否正常构建、表结构是否对齐流程定义改动次之用一次完整的实例跑通即可确认代码扩展点最麻烦因为它出错时往往不抛异常只是默默不执行。常见的扩展点有这几类继承 JavaDelegate 写服务任务注意字段注入在流程定义里配别用静态变量存状态实现 TaskListener 或 ExecutionListener 做任务前后钩子监听器里抛异常会中断整个流转做非关键逻辑时务必自己 try 住自定义 ProcessEngineConfiguration 的子类去改缓存、事件分发这些底层行为改之前先确认没有现成配置项能用还有表单和 REST 层的自定义文档第 9 章和第 13 章有对应说明。验证方法我固定用一套组合一份只含开始、服务任务、结束的最小 BPMN 专门用来测扩展点跑通后再套到真实流程上再配一组单元测试覆盖部署、启动、完成任务、查历史四步每次升级引擎版本先把这组跑一遍。这样出问题时能把「引擎本身的问题」和「我改的东西的问题」快速分开。从那以后我每次接工作流项目第一步都是把这份中文文档对应章节翻出来对着写一遍最小流程的回归用例跑通了才动业务代码。这份指南不会替你做架构决策但它能让你少走很多「以为是引擎的错、其实是一个配置项写反了」的弯路。希望帮到你。本文还有配套的精品资源点击获取

Activiti6中文文档实战：工作流引擎配置、BPMN与二次开发

相关推荐

TensorFlow从安装到实战：2024年深度学习框架选型与避坑指南

美赛A题时序预测：混合模型与特征工程实战

Telegram验证码机制解析与安全实践

更多资讯

UI自动化测试批量执行优化与pytest实战

企业级WinForm开发模板与工业软件实战经验

从97分钟到10分钟：VR机房可视化系统与创新型QC材料

什么是Buzz？从热度传播到硬件提示的技术解析

链式队列实现原理与优化策略详解

收付一体系统：企业资金管理效率革命与架构解析

今日更新

淘宝商品详情API开发实战与性能优化指南

Unity Package Manager刷新错误排查与解决方案

Java record 规范构造器能否被反序列化或反射绕过

本周精选

面向复杂光照与角度的宠物面部识别鲁棒性增强策略

基于DRV8818与STM32的双极步进电机驱动方案实战解析

DRV8818PWPR+PIC18F45K80双极步进电机控制方案实战

本月热门

面向复杂光照与角度的宠物面部识别鲁棒性增强策略

基于DRV8818与STM32的双极步进电机驱动方案实战解析

DRV8818PWPR+PIC18F45K80双极步进电机控制方案实战

读完文章，想聊聊您的网站？