简介这份资源是 Activiti6 工作流引擎的中文用户指南文档面向需要基于 BPMN 2.0 标准设计、部署与执行业务流程的 Java 开发者、架构师及工作流初学者。内容覆盖系统要求、快速入门、ProcessEngine 与数据库配置、Job Executor、邮件服务器与历史记录配置、Process Engine API 与服务、查询与变量、单元测试、Spring 与 Spring Boot 集成、JPA 支持、BAR 部署与版本控制以及 BPMN 2.0 的事件定义、边界事件、中间捕获与抛出事件等构造目录结构完整便于按章节系统查阅。资源包共 1 个 docx 文件约 4.22MB为纯文档型资料适合离线阅读与检索。目前已有 1816 人学习下载可作为搭建与调试 Activiti6 流程引擎时的中文参考手册帮助读者快速理解核心组件配置、API 调用方式与 BPMN 元素用法减少查阅英文文档的成本。1. 从一份离线文档说起Activiti6 中文用户指南到底能解决什么接手一个遗留审批系统时最怕的不是代码烂而是流程引擎的版本和文档对不上。上个月帮一个团队排查工单流转卡死的问题翻遍内网只找到一份英文的 Activiti 6.0.0 用户指南团队里几个刚入行的同学对着 BPMN 2.0 的 XML 一脸茫然。后来找到这份《Activiti6 中文 用户指南.docx》从 JDK 7 环境要求、ProcessEngine 配置到 BPMN 2.0 构造、REST API、Spring Boot 集成目录结构基本覆盖了落地一个工作流系统需要的全部环节。它不是那种只讲概念的科普材料而是一份可以当手册查的离线文档——遇到 Job Executor 不触发、历史表查不到数据、边界事件不生效这类具体问题时能直接翻到对应章节找参数和配置项。适合正在用或准备用 Activiti6 做审批流、工单流、订单状态机的后端开发也适合需要把 BPMN 流程部署到 Spring Boot 项目里的全栈工程师。下面按我实际拆文档的顺序把这份指南里真正能落地的部分拆开讲。2. 环境搭建与快速启动从 WAR 包到 admin/test 登录2.1 运行环境与依赖清单这份指南在开头就明确了最低要求JDK 7IDE 不限。但实际用下来JDK 8 更稳因为 Activiti6 内部依赖的一些反射和泛型处理在 JDK 7 上偶尔会报UnsupportedClassVersionError。数据库方面指南默认用内存 H2适合跑通 Demo生产环境建议直接上 MySQL 5.7 或 PostgreSQL建表脚本在activiti-engine的 jar 包里自带不需要手动写 DDL。组件版本要求说明JDK7推荐 8编译和运行流程引擎Web 容器Tomcat 7部署 activiti-app.war数据库H2默认/ MySQL 5.7生产建议换 MySQL构建工具Maven 3.x拉取 activiti-engine 依赖2.2 一分钟跑通 Demo 的完整步骤指南里“一分钟版”的流程写得很直白但有几个细节原文没展开。我按实际操做补全# 1. 下载 activiti-app.war从官方 release 包获取 # 2. 复制到 Tomcat webapps 目录 cp activiti-app.war $TOMCAT_HOME/webapps/ # 3. 启动 TomcatLinux 下 $TOMCAT_HOME/bin/startup.sh # 4. 观察日志确认 H2 数据库初始化完成 tail -f $TOMCAT_HOME/logs/catalina.out | grep Activiti启动后浏览器访问http://localhost:8080/activiti-app用admin / test登录。这里有个容易翻车的点如果 Tomcat 的webapps目录下已经有解压过的旧版本新 war 包不会覆盖必须先把旧目录删掉再放 war。另外H2 是内存库Tomcat 一重启数据全丢只适合验证功能别拿它测持久化逻辑。2.3 数据库切换与建表策略从 H2 切到 MySQL 时指南在“数据库配置”一节给了ProcessEngineConfiguration的配置项。我一般直接在activiti.cfg.xml里改bean idprocessEngineConfiguration classorg.activiti.engine.impl.cfg.StandaloneProcessEngineConfiguration property namejdbcUrl valuejdbc:mysql://localhost:3306/activiti_db?useUnicodetrueamp;characterEncodingutf8/ property namejdbcDriver valuecom.mysql.jdbc.Driver/ property namejdbcUsername valueroot/ property namejdbcPassword valueyour_password/ !-- 首次启动自动建表生产环境建议设为 false 并手动执行 SQL -- property namedatabaseSchemaUpdate valuetrue/ /beandatabaseSchemaUpdate这个参数值得单独说true表示启动时自动检查并创建/更新表结构开发阶段省事false则完全手动控制生产环境必须设false否则引擎启动时可能因为权限不足或锁表导致启动失败。建表 SQL 在activiti-engine-6.0.0.jar的org/activiti/db/create目录下按数据库类型分好了直接拿出来执行就行。3. ProcessEngine 配置与 Job Executor异步任务不执行的排查路径3.1 ProcessEngineConfiguration 的核心参数ProcessEngine 是整个 Activiti6 的心脏所有 ServiceRepositoryService、RuntimeService、TaskService 等都从它派生。指南第 3 章把配置项列得很全但实际项目里真正需要改的就那么几个。我习惯用编程式配置比 XML 更直观ProcessEngineConfiguration cfg ProcessEngineConfiguration .createStandaloneProcessEngineConfiguration() .setJdbcUrl(jdbc:mysql://localhost:3306/activiti_db) .setJdbcUsername(root) .setJdbcPassword(your_password) .setJdbcDriver(com.mysql.jdbc.Driver) .setDatabaseSchemaUpdate(ProcessEngineConfiguration.DB_SCHEMA_UPDATE_TRUE) // 历史级别full 记录所有细节audit 只记关键节点none 关闭 .setHistoryLevel(HistoryLevel.FULL) // 异步执行器开关6.0.0 之后默认开启 .setAsyncExecutorActivate(true); ProcessEngine processEngine cfg.buildProcessEngine();historyLevel设成full会写大量历史数据查询方便但表增长快audit是折中方案只记录流程实例和活动实例不记变量明细。如果业务方要求“能查到每个任务的处理人”audit就够如果要追溯变量每次变更必须full。3.2 Job Executor 的激活与常见静默失败从 6.0.0 开始Job Executor 独立成一个组件负责扫ACT_RU_JOB表里的定时器和异步任务。指南在 3.9 和 3.10 两节专门讲了这个。实际踩坑最多的是流程里配了activiti:asynctrue但任务一直停在中间不往下走查ACT_RU_JOB表发现有记录但RETRIES_字段变成 0 了。原因通常是 Job Executor 没激活或者激活了但执行时抛异常导致重试耗尽。排查顺序-- 1. 查是否有待执行作业 SELECT * FROM ACT_RU_JOB WHERE RETRIES_ 0; -- 2. 查作业是否被锁定LOCK_EXP_TIME_ 过期时间 SELECT ID_, LOCK_OWNER_, LOCK_EXP_TIME_, RETRIES_ FROM ACT_RU_JOB WHERE LOCK_EXP_TIME_ IS NOT NULL; -- 3. 查历史作业异常信息 SELECT * FROM ACT_HI_JOB_LOG WHERE JOB_ID_ 你的作业ID ORDER BY TIME_STAMP_ DESC;如果RETRIES_为 0说明重试次数用完了默认是 3 次。可以在流程定义里给异步任务配activiti:failedJobRetryTimeCycleR5/PT5M表示重试 5 次、每次间隔 5 分钟。这个参数指南在“异步延续”一节提过但没给具体写法实际用的时候直接写在serviceTask的扩展属性里。3.3 邮件服务器与事件监听器配置指南 3.11 到 3.17 覆盖了邮件服务器、事件处理程序、监听器。邮件任务在审批通知场景很常用配置项包括mailServerHost、mailServerPort、mailServerDefaultFrom。注意一点如果用的是企业邮箱且要求 SSL需要额外设mailServerUseSSLtrue否则连接会被拒绝。事件监听器分全局和流程级两种。全局监听器在ProcessEngineConfiguration里注册对所有流程生效流程级监听器写在 BPMN XML 的extensionElements里。我一般把审计日志的监听器做成全局的避免每个流程都重复配cfg.setEventListeners(Arrays.asList(new AuditEventListener()));AuditEventListener实现ActivitiEventListener接口在onEvent方法里根据ActivitiEventType判断是TASK_CREATED还是PROCESS_COMPLETED然后写自己的业务日志表。这样流程定义里不用加任何东西所有流程自动带审计。4. BPMN 2.0 核心构造网关、事件与任务的实际用法4.1 排他网关与并行网关的选型差异指南第 8 章是整份文档最厚的部分BPMN 2.0 构造几乎每个元素都单独列了小节。实际项目里用得最多的网关是排他网关Exclusive Gateway和并行网关Parallel Gateway。排他网关按条件选一条路走条件表达式写在连线上exclusiveGateway iddecisionGateway / sequenceFlow idflow1 sourceRefdecisionGateway targetReftaskA conditionExpression xsi:typetFormalExpression ${amount 1000} /conditionExpression /sequenceFlow sequenceFlow idflow2 sourceRefdecisionGateway targetReftaskB conditionExpression xsi:typetFormalExpression ${amount 1000} /conditionExpression /sequenceFlow并行网关则是 fork/join 语义所有出口同时激活所有入口都到达后才继续。这里有个血泪经验并行网关的 join 必须等所有分支都到达如果某个分支因为条件不满足被跳过了流程会永久卡住。所以并行网关的分支里不要放排他网关做条件跳过要么全走要么用包容网关Inclusive Gateway。4.2 边界事件与定时器的组合场景边界事件挂在任务或子流程上用来处理超时、错误、取消等情况。最常用的是定时器边界事件比如“审批任务超过 24 小时自动升级”userTask idapproveTask name审批 / boundaryEvent idtimeoutBoundary attachedToRefapproveTask cancelActivitytrue timerEventDefinition timeDurationPT24H/timeDuration /timerEventDefinition /boundaryEvent sequenceFlow sourceReftimeoutBoundary targetRefescalateTask /cancelActivitytrue表示边界事件触发时取消原任务false则不取消、只是旁路触发。timeDuration用 ISO 8601 格式PT24H是 24 小时P1D是 1 天。指南在“计时器边界事件”一节给了 XML 表示但没强调时区问题——引擎默认用 JVM 时区如果服务器是 UTC 而业务方按北京时间算会差 8 小时。稳妥做法是在ProcessEngineConfiguration里显式设setDefaultTimerJobAcquireWaitTime和时区相关参数或者干脆在业务层把时间算好再传变量。4.3 用户任务分配与监听器注入用户任务的分配方式指南列了三种直接指定 assignee、用 candidateUsers/candidateGroups、通过任务监听器动态分配。直接指定最简单但硬编码在 XML 里不灵活候选组适合“某个角色的人都能领”的场景监听器最灵活可以在create事件里根据流程变量查数据库决定给谁。public class AssigneeListener implements TaskListener { Override public void notify(DelegateTask delegateTask) { String dept (String) delegateTask.getVariable(department); // 根据部门查负责人动态设置 assignee String assignee userService.findManagerByDept(dept); delegateTask.setAssignee(assignee); } }监听器里可以注入字段但注意线程安全问题如果监听器是单例且用了实例变量并发时会串数据。指南在“执行监听器上的字段注入”一节提过这个但说得比较隐晦。我一般把监听器写成无状态的所有数据从delegateTask或 Spring 容器里拿。5. 避坑与排查那些文档没写但一定会遇到的问题5.1 现象流程启动报 “no processes deployed with key”原因RuntimeService.startProcessInstanceByKey用的 key 和 BPMN XML 里process id...不一致或者部署时资源名和 key 对不上。解决先查ACT_RE_PROCDEF表确认已部署的 key 和版本再核对代码里的 key 字符串。注意部署时如果用了.bpmn20.xml后缀key 取的是 process 元素的 id不是文件名。5.2 现象历史表查不到数据HistoricProcessInstanceQuery返回空原因historyLevel设成了none或者流程启动时引擎配置没生效。解决检查ProcessEngineConfiguration的historyLevel是否为audit或full并确认流程实例确实已经结束历史数据在流程结束后才完整写入。如果流程还在运行中查ACT_RU_EXECUTION而不是历史表。5.3 现象Job Executor 不执行异步任务日志无报错原因asyncExecutorActivate设为false或者 Job Executor 的线程池被其他任务占满。解决确认配置里setAsyncExecutorActivate(true)然后查ACT_RU_JOB表的RETRIES_和LOCK_EXP_TIME_。如果LOCK_EXP_TIME_是过去时间但作业没被捡起来可能是集群环境下多个引擎实例竞争锁导致需要配setAsyncExecutorLockOwner区分实例。5.4 现象Spring Boot 集成后 REST API 返回 401原因Activiti6 的 REST 模块默认带安全拦截Spring Boot 自动配置没有放行。解决在application.properties里加management.security.enabledfalse旧版 Spring Boot或在 Security 配置类里对/activiti-rest/**放行。指南在“Spring Boot 的 REST 支持”一节提了兼容性但没给具体放行配置这个坑我踩过两次。5.5 现象边界事件不触发定时器到点没反应原因边界事件挂载的任务已经完成或者cancelActivity设错。解决确认边界事件的attachedToRef指向的任务还在活动状态如果任务已完成边界事件自动失效。另外检查timeDuration的格式PT1H是 1 小时写成1H会解析失败但不报错只是不触发。6. 进阶技巧用 REST API 和单元测试验证流程正确性6.1 用 REST API 做流程实例的快速验证指南第 13 章 REST API 覆盖了部署、流程定义、流程实例、任务、历史等全部端点。实际调试时我习惯用 curl 直接打接口比写 Java 代码快# 启动一个流程实例 curl -X POST http://localhost:8080/activiti-rest/service/runtime/process-instances \ -H Content-Type: application/json \ -u admin:test \ -d { processDefinitionKey: leaveProcess, variables: [ {name: applicant, value: zhangsan}, {name: days, value: 3} ] } # 查询当前用户的任务 curl -X GET http://localhost:8080/activiti-rest/service/runtime/tasks?assigneezhangsan \ -u admin:test注意 REST 模块的认证默认是 Basic Authadmin/test是内置账号。如果返回 403检查activiti-rest的web.xml里安全约束是否放行了对应角色。分页参数用start和size排序用sort和order这些在指南 13.1.6 的“分页和排序”一节有说明。6.2 单元测试验证流程路径Activiti6 提供了ActivitiRuleJUnit 规则可以自动建内存库、加载流程文件、断言流程状态。指南 4.8 和 4.9 两节讲了单元测试和调试我补一个实际用的模板public class LeaveProcessTest { Rule public ActivitiRule activitiRule new ActivitiRule(); Test Deployment(resources {leaveProcess.bpmn20.xml}) public void testApprovePath() { MapString, Object vars new HashMap(); vars.put(days, 3); ProcessInstance pi activitiRule.getRuntimeService() .startProcessInstanceByKey(leaveProcess, vars); Task task activitiRule.getTaskService() .createTaskQuery().processInstanceId(pi.getId()).singleResult(); assertEquals(部门经理审批, task.getName()); // 完成任务验证流程是否走到预期节点 activitiRule.getTaskService().complete(task.getId()); long count activitiRule.getTaskService() .createTaskQuery().processInstanceId(pi.getId()).count(); assertEquals(1, count); // 下一节点任务已生成 } }Deployment注解会自动部署指定资源ActivitiRule默认用 H2 内存库每个测试方法独立事务、互不干扰。断言时重点看任务名称、流程实例是否结束、变量值是否正确。如果测试跑不通但手动操作没问题多半是Deployment的资源路径写错了或者 BPMN 文件里有语法错误导致部署失败但没抛异常。6.3 流程图自动生成与版本回滚指南 6.4 和 6.5 讲了流程图生成。部署时如果 BPMN 文件旁边有同名的.png引擎会自动关联没有的话可以用ProcessDiagramGenerator动态生成InputStream diagram processEngine.getProcessEngineConfiguration() .getProcessDiagramGenerator() .generateDiagram(bpmnModel, png, Collections.emptyList(), Collections.emptyList(), 宋体, 宋体, null, 1.0, true);字体参数不传中文会显示方框这个坑在中文环境下必踩。版本回滚方面Activiti 的流程定义版本只增不减回滚的做法是重新部署旧版本的 BPMN 文件引擎会生成新版本号但流程定义 key 不变。如果业务方要求“回到上一版”实际是部署旧文件产生新版本而不是删除当前版本。从那以后我每次部署新流程前都会先用Deployment跑一遍单元测试确认所有分支路径都能走通再上环境。流程引擎这东西上线前多花十分钟测边界比上线后半夜被叫起来查ACT_RU_JOB强得多。希望帮到你。本文还有配套的精品资源点击获取