简介Flowable 6.7.2 是一款基于 BPMN 2.0 标准的开源工作流引擎面向企业流程自动化开发人员、Java 后端工程师及业务流程管理人员用于搭建流程定义、执行、任务管理与监控一体化的解决方案。资源包共 2000 个文件约 201.97MB涵盖 1508 个 html 文档、894 个 sql 脚本、275 个 jar 依赖、180 个 js 脚本及 156 个 png 图片等分别用于接口说明、数据库初始化、引擎运行依赖与前端资源展示。已有 1644 人学习下载。内容围绕 BPMN 2.0 元素建模、高性能流程引擎、任务分配与监控、表单集成、事件驱动机制、RESTful 与 Java API 扩展、安全权限管理及用户界面等关键模块展开可帮助读者快速理解流程引擎的目录结构与核心组件对照官方文档完成本地部署、流程建模与接口调试适合需要系统掌握 Flowable 6.7.2 版本特性与集成思路的中高级开发者参考。1. 拿到 flowable-6.7.2.zip 之后先别急着解压想清楚你要的是引擎还是全家桶很多人第一次接触 Flowable是从一个压缩包开始的。搜到flowable-6.7.2.zip下载下来解压然后面对一堆目录发懵——到底哪个是引擎哪个是示例哪个是文档哪个是设计器我见过不止一个团队把整个包丢进项目里当依赖结果编译出一堆用不上的模块启动慢、冲突多最后回头重来。这个标题背后真正的问题不是「怎么下载」而是「拿到这个包之后怎么把它变成能跑起来的工作流引擎」。Flowable 是一个 BPMN 2.0 流程引擎6.7.2 是它的一个稳定版本分支这个 zip 通常包含源码、文档、示例和构建脚本。你要做的第一件事是判断自己需要的是嵌入到 Java 应用里的引擎依赖还是独立部署的 REST 服务还是只想看看 BPMN 文件长什么样。这篇文章面向的是需要把 Flowable 落地到实际业务里的后端开发者尤其是那些拿到分发包却不知道从哪下手的人。我会按「先理清包里有什么、再搭最小可运行环境、然后跑通一个真实流程、最后讲清楚版本选择和踩坑」的顺序讲。不堆概念每一步都落到命令和配置上。2. 拆开 flowable-6.7.2.zip目录结构决定你的接入方式2.1 先看清包里到底有什么别把源码当依赖拿到一个 Flowable 的分发包第一件事是看目录。常见的结构大致是这样modules目录下按功能拆分flowable-engine是核心引擎flowable-spring是 Spring 集成flowable-rest是 REST 接口层flowable-ui是那个带流程设计器的 Web 应用flowable-examples里是一堆演示项目docs里是文档和 schema 脚本。如果你是从源码构建还会有pom.xml和build.gradle。这里有个血泪经验很多人直接把flowable-ui当成引擎来用以为部署了 UI 就能在业务系统里调 API。实际上 UI 是一个独立的 Web 应用它内部依赖了引擎但你的业务系统要集成的是flowable-engine或flowable-spring-boot-starter。UI 适合做流程建模和人工任务管理不适合作为你业务代码的依赖。判断方法很简单打开modules下每个子目录的pom.xml看artifactId。flowable-engine是核心flowable-spring-boot-starter-basic是 Spring Boot 项目最常用的起步依赖。如果你只需要在代码里调用RuntimeService、TaskService这些接口那就只需要引擎和 Spring 集成不需要 UI 和 REST。注意6.7.2 这个版本对 Spring Boot 的版本有要求通常对应 Spring Boot 2.7.x 左右。如果你用的是 Spring Boot 3.x直接引这个版本会有一堆javax和jakarta的包冲突后面会专门讲。2.2 用 Maven 或 Gradle 引入引擎的最小依赖假设你是一个 Spring Boot 项目最省事的做法是引入flowable-spring-boot-starter-basic。这个 starter 会自动配置引擎、数据源、事务管理器你只需要在配置文件里写好数据库连接就行。!-- pom.xml 中引入 Flowable 6.7.2 的 Spring Boot starter -- dependency groupIdorg.flowable/groupId artifactIdflowable-spring-boot-starter-basic/artifactId version6.7.2/version /dependency !-- 如果要用 REST API再加这个 -- dependency groupIdorg.flowable/groupId artifactIdflowable-spring-boot-starter-rest/artifactId version6.7.2/version /dependency这段依赖声明里flowable-spring-boot-starter-basic会传递引入flowable-engine、flowable-spring以及数据库连接池等。版本号必须和你的 zip 包版本一致否则可能出现类找不到或者行为不一致。如果你用的是 Gradle写法类似把implementation加上对应坐标即可。引入之后Spring Boot 的自动配置会检测DataSource然后自动创建ProcessEngine。你不需要手动写flowable.cfg.xml除非你要做深度定制。默认情况下引擎启动时会检查数据库表是否存在不存在就自动创建。这个行为由flowable.database-schema-update参数控制默认值是true生产环境建议改成false并用 SQL 脚本手动初始化。2.3 数据库准备别用内存库糊弄生产Flowable 需要一套关系型数据库来存流程定义、运行时实例、历史数据。开发阶段可以用 H2 内存库快速验证但生产环境必须换成 MySQL、PostgreSQL 或 Oracle。6.7.2 支持的数据库版本在docs目录下的database相关文档里有说明常见的是 MySQL 5.7 和 PostgreSQL 12。# application.yml 中配置数据源和 Flowable 行为 spring: datasource: url: jdbc:mysql://localhost:3306/flowable_demo?useUnicodetruecharacterEncodingutf8serverTimezoneAsia/Shanghai username: flowable password: flowable driver-class-name: com.mysql.cj.jdbc.Driver flowable: database-schema-update: true # 开发环境自动建表生产环境改为 false async-executor-activate: true # 开启异步执行器定时任务和异步任务需要 history-level: full # 历史级别audit 只存关键信息full 存全部这里几个参数值得展开。database-schema-update设为true时引擎启动会对比数据库表结构和预期结构自动执行建表或升级脚本。开发阶段很方便但生产环境如果多个节点同时启动可能并发建表导致锁等待所以生产建议关掉用官方提供的 SQL 脚本手动执行。async-executor-activate控制异步执行器如果你有定时边界事件、异步服务任务必须开启否则这些任务永远不会被触发。history-level影响历史数据量full最全但表增长最快audit只记录流程实例和活动实例适合大多数业务场景。3. 跑通第一个 BPMN 流程从画图到 API 调用3.1 用 Flowable UI 画一个最简单的审批流程如果你解压的包里带了flowable-ui可以直接启动它来画流程图。启动方式通常是java -jar flowable-ui.war或者用 Tomcat 部署。启动后访问默认端口用默认账号登录进入建模器新建一个 BPMN 流程。我一般会画一个最简的「请假审批」开始事件 → 用户任务提交申请→ 用户任务经理审批→ 排他网关同意/拒绝→ 结束事件。这个流程足够覆盖用户任务、网关、条件表达式的用法。画完之后导出为.bpmn20.xml文件这个文件就是流程定义。这里有个细节Flowable UI 里画的图保存的是 XML但 XML 里包含图形信息坐标、连线。如果你手动写 XML可以省略图形信息引擎只关心流程元素和连线关系。但为了后续能在 UI 里继续编辑建议保留完整信息。3.2 把 BPMN 文件部署到引擎并启动实例拿到.bpmn20.xml之后放到 Spring Boot 项目的src/main/resources/processes/目录下。Flowable 的 Spring Boot starter 默认会自动扫描这个目录并部署流程定义。你也可以通过 API 手动部署。// 手动部署 BPMN 文件并启动一个流程实例 Autowired private RepositoryService repositoryService; Autowired private RuntimeService runtimeService; public void deployAndStart() { // 部署流程定义资源名就是 classpath 下的路径 Deployment deployment repositoryService.createDeployment() .addClasspathResource(processes/leave-approval.bpmn20.xml) .name(请假审批流程) .deploy(); // 根据流程定义的 key 启动实例key 在 BPMN XML 的 process 标签上 MapString, Object variables new HashMap(); variables.put(applicant, A同学); variables.put(days, 3); ProcessInstance instance runtimeService.startProcessInstanceByKey(leaveApproval, variables); System.out.println(流程实例 ID: instance.getId()); }这段代码里repositoryService.createDeployment()创建一个部署对象addClasspathResource指定资源路径deploy()执行部署。部署成功后Flowable 会解析 BPMN 文件把流程定义存到ACT_RE_PROCDEF表。runtimeService.startProcessInstanceByKey根据流程定义的 key 启动实例第二个参数是流程变量这些变量可以在后续的用户任务、网关条件里使用。流程启动后第一个用户任务会被创建对应ACT_RU_TASK表里会多一条记录。你可以用taskService.createTaskQuery().processInstanceId(instance.getId()).list()查到待办任务。3.3 查询任务、完成任务让流程往前走流程实例启动后会停在第一个用户任务上。你需要查询任务、完成任务流程才会继续。// 查询待办任务并完成推动流程流转 Autowired private TaskService taskService; public void completeFirstTask(String processInstanceId) { // 查询该流程实例下的待办任务 ListTask tasks taskService.createTaskQuery() .processInstanceId(processInstanceId) .list(); for (Task task : tasks) { System.out.println(待办任务: task.getName() , 任务 ID: task.getId()); // 完成任务同时传入审批结果变量 MapString, Object vars new HashMap(); vars.put(approved, true); taskService.complete(task.getId(), vars); } }taskService.complete会触发流程继续执行。如果后面是排他网关网关会根据approved变量的值决定走哪条分支。这里要注意流程变量在网关条件里要用${approved true}这样的表达式变量名必须和传入的 key 一致。如果变量没传或者类型不对网关会抛异常流程实例会卡住。完成第一个任务后流程会走到第二个用户任务经理审批。你可以用同样的方式查询并完成。全部完成后流程实例结束历史数据会写入ACT_HI_*系列表。4. 版本选择与依赖冲突6.7.2 不是随便用的4.1 为什么是 6.7.2而不是最新版Flowable 的版本迭代比较快6.7.2 属于 6.x 分支的一个维护版本。选择这个版本通常有几个原因项目依赖的 Spring Boot 版本是 2.x而 Flowable 7.x 开始要求 Spring Boot 3.x 和 Jakarta EE 9或者团队之前用的是 6.6 或 6.5升级到 6.7.2 风险较小又或者某些云平台或中间件对 Flowable 版本有兼容性要求。如果你是新项目且用 Spring Boot 3.x那应该考虑 Flowable 7.x 而不是 6.7.2。但如果你维护的是老系统6.7.2 是一个相对稳定的选择。判断方法看你的javax.persistence还是jakarta.persistence如果是前者6.7.2 更合适。4.2 Spring Boot 3.x 下用 6.7.2 的翻车现场我见过一个团队Spring Boot 3.0 的项目里直接引了 Flowable 6.7.2启动时报ClassNotFoundException: javax.xml.bind.JAXBException。原因是 Spring Boot 3.x 移除了 JAXB 和 JAX-WS 的默认依赖而 Flowable 6.7.2 还在用javax命名空间。解决办法有两个要么降 Spring Boot 版本到 2.7.x要么手动补上jakarta.xml.bind-api和jaxb-runtime依赖但后者可能还有其他javax包冲突不推荐。另一个常见问题是 MyBatis 版本冲突。Flowable 6.7.2 内部依赖 MyBatis 3.5.x如果你的项目里已经引了更高或更低的版本可能导致NoSuchMethodError。排查方法是看mvn dependency:tree里org.mybatis:mybatis的版本确保和 Flowable 的预期一致。如果冲突可以在pom.xml里显式声明 MyBatis 版本覆盖传递依赖。4.3 数据库驱动和连接池的版本匹配Flowable 6.7.2 默认使用 HikariCP 作为连接池但如果你自己配了 Druid 或 Tomcat JDBC需要确保连接池的validationQuery和数据库驱动兼容。MySQL 8.x 的驱动类名是com.mysql.cj.jdbc.DriverURL 里要带serverTimezone否则可能报时区错误。PostgreSQL 的驱动类名是org.postgresql.DriverURL 里建议加stringtypeunspecified避免 JSON 字段类型问题。还有一个容易忽略的点Flowable 的建表脚本里有些字段长度是固定的比如ACT_RU_TASK的NAME_字段长度是 255。如果你的业务里任务名称经常超过 255 字符插入时会报错。解决办法是在流程定义里控制任务名称长度或者手动改表结构不推荐升级时会冲突。5. 避坑与排查那些让你加班到凌晨的细节5.1 流程启动后卡在第一个任务查不到待办现象调用startProcessInstanceByKey成功返回但taskService.createTaskQuery().list()返回空列表。原因最常见的是流程定义里第一个用户任务的assignee或candidateGroups没设置或者设置了但当前用户不在候选组里。另一个可能是流程定义部署了多个版本启动时用了旧版本而旧版本的任务分配规则不同。解决先查ACT_RE_PROCDEF表确认KEY_和VERSION_启动时可以用startProcessInstanceByKeyAndTenantId或指定版本。然后查ACT_RU_TASK表看有没有记录。如果有记录但查询不到检查查询条件里的assignee或candidateUser是否匹配。5.2 异步任务不执行定时器不触发现象流程里有定时边界事件或异步服务任务但时间到了没反应。原因async-executor-activate设成了false或者异步执行器的线程池被占满或者数据库里的ACT_RU_JOB表有大量失败记录。解决先确认配置里flowable.async-executor-activatetrue。然后查ACT_RU_JOB表看有没有RETRIES_为 0 的记录这些是重试耗尽的失败任务。可以用managementService.createJobQuery().list()查看手动managementService.executeJob(jobId)重试。如果线程池满调整flowable.async-executor-default-queue-size和flowable.async-executor-core-pool-size。5.3 历史数据暴涨查询越来越慢现象运行一段时间后ACT_HI_*表数据量过大历史查询接口响应超时。原因history-level设成了full所有变量、任务、活动都存历史数据量随流程实例数线性增长。解决根据业务需要调整历史级别。如果只需要审计流程实例和活动用audit如果连变量都不需要用none但这样历史查询功能基本不可用。另外可以配置历史数据清理策略Flowable 提供了historyCleaning相关参数定期删除过期数据。生产环境建议配合分区表或归档策略。5.4 表达式报错流程实例挂起现象完成任务时抛FlowableException: Unknown property used in expression。原因网关条件或服务任务里用了${approved true}但approved变量没传或者变量名拼写不一致。解决在完成任务前确认变量已放入Map并传入taskService.complete(taskId, variables)。如果变量是在流程启动时传入的检查startProcessInstanceByKey的第二个参数。另外表达式里的变量名区分大小写approved和Approved是两个不同的变量。5.5 部署时 BPMN 文件校验失败现象repositoryService.createDeployment().deploy()抛XMLException或ValidationException。原因BPMN XML 格式不对比如缺少targetNamespace或者连线没有正确引用节点 ID或者用了 Flowable 不支持的 BPMN 元素。解决先用 Flowable UI 打开文件看能不能正常渲染。如果 UI 也报错说明 XML 本身有问题。检查process标签的id和isExecutable属性isExecutable必须是true。检查所有sequenceFlow的sourceRef和targetRef是否指向存在的节点 ID。如果用了自定义扩展元素确认命名空间声明正确。6. 进阶把 Flowable 6.7.2 嵌进真实业务系统的三个技巧第一个技巧是动态流程定义。很多业务场景下流程分支不是固定的而是根据表单数据动态决定。Flowable 支持在网关条件里用表达式调用 Spring Bean 的方法比如${approvalService.needsDirectorApproval(days)}。你只需要把approvalService注册成 Spring Bean在表达式里引用即可。这样流程定义不用改业务规则在 Java 代码里维护。第二个技巧是任务监听器和执行监听器。你可以在 BPMN 里配置监听器在任务创建、完成、流程启动、结束时触发自定义逻辑。比如任务创建时发通知流程结束时写业务表。监听器可以用delegateExpression引用 Spring Bean也可以用class指定全限定类名。我一般用delegateExpression方便依赖注入。// 任务监听器示例任务创建时自动设置候选人 Component(taskCreateListener) public class TaskCreateListener implements TaskListener { Override public void notify(DelegateTask delegateTask) { // 根据流程变量动态设置候选人 String dept (String) delegateTask.getVariable(department); if (finance.equals(dept)) { delegateTask.addCandidateGroup(finance-group); } else { delegateTask.addCandidateGroup(general-group); } } }在 BPMN XML 里用户任务节点下加extensionElementsflowable:taskListener eventcreate delegateExpression${taskCreateListener}//extensionElements。这样任务创建时就会执行监听器逻辑。注意监听器里不要做耗时操作否则会拖慢任务创建。第三个技巧是历史数据查询优化。historyService.createHistoricProcessInstanceQuery()默认查全表数据量大时很慢。可以加finished()、startedAfter()、startedBefore()等条件缩小范围。另外如果只需要流程实例的基本信息用HistoricProcessInstance而不是HistoricActivityInstance后者数据量大得多。查询时用listPage(0, 20)分页避免一次性拉全量。最后说一个我自己的习惯每次升级 Flowable 版本前先在测试环境用database-schema-updatefalse跑一遍手动执行升级脚本确认表结构变更不会影响现有数据。升级脚本在docs目录的db子目录下按数据库类型分。别小看这一步我见过直接在生产开自动更新导致锁表的案例后悔药没地方买。希望帮到你。本文还有配套的精品资源点击获取