在企业后端项目里工作流引擎几乎是绕不开的话题请假审批、报销审批、合同会签如果靠硬编码状态机去维护撑过两三个流程就会让人想砸键盘。我在这类场景里试过好几个方案最后长期留下来的组合是SpringBoot配合Flowable。这篇文章我会从零开始把SpringBoot集成Flowable的完整过程、版本选择、数据库初始化、BPMN流程定义、业务侧的核心API操作以及实际项目中踩过的坑和沉淀下来的配置一次讲清楚。如果你会SpringBoot但还没碰过工作流引擎按着这篇的节奏一步步操作基本都能顺利跑起来。1. 对比完Activiti和Camunda我为什么把Flowable放进SpringBoot1.1 工作流引擎选型这件事不能只看名气网上搜工作流引擎最先跳出来的永远是Activiti、Flowable、Camunda这三家。很多新人会直接选名气最大的Activiti但等真正开工才发现版本分裂和社区维护状态的问题很闹心。Activiti 5的时代确实很辉煌BPMN 2.0规范落地得早中文教程一抓一大把。但后来项目主体拆分Flowable团队从Activiti 5分支出来独立发展Activiti 6/7则走上了另一条路。如果你现在开新项目再用老一套Activiti 5的思路会遇到两个直接问题一是和SpringBoot 2.7版本的适配需要自己折腾二是遇到问题去搜资料搜出来的解决方案大多是针对Flowable和Activiti 5的版本对不上踩坑成本很高。Camunda功能确实强特别是它的Cockpit监控界面很漂亮对复杂编排场景支持也细。但它本身更偏重企业级平台组件体积大和SpringBoot集成时需要引入的模块也多。对大部分中小规模项目的审批场景来说有点杀鸡用牛刀的意味。1.2 Flowable的定位和优势Flowable从Activiti分叉之后主打的路线就是把流程引擎做成一个可以嵌入SpringBoot的轻量级组件。它保留了BPMN 2.0的完整支持CMMN Case模型、DMN决策表这些后续也都做了。最让我满意的是它的Spring Boot Starter体系很完整引入一个依赖就能拿到ProcessEngine以及所有的Service Bean不用自己写引擎初始化代码。另外Flowable的中文社区内容密度比Camunda高不少遇到资源表达式写法、多实例加签这种问题搜索引擎里能翻到不少真实案例。这对新手来说太重要了因为工作流引擎的调试难度比普通CRUD接口高得多我之前就为了一个排他网关的条件不生效问题折腾了一个下午最后还是靠社区帖子解决的。2. 版本搭配与数据库初始化这个环节最容易翻车2.1 SpringBoot和Flowable的版本对应关系很多人第一次集成就把版本搞错了导致启动直接报ClassNotFoundException或者引擎里一堆方法找不到。Flowable和SpringBoot的适配是有明确对应关系的我整理了一份实际验证过的搭配SpringBoot版本Flowable版本备注2.3.x6.4.x老项目常见建议升级2.7.x6.6.0 ~ 6.8.x国内目前的主流组合3.0.x及以上7.0.0及以上新项目建议JDK 17我自己目前主力项目用的是SpringBoot 2.7.18 Flowable 6.7.2这个组合跑了一年多没有遇到引擎层的问题。如果你是新项目且JDK环境允许直接上SpringBoot 3 Flowable 7毕竟Flowable 7的底层持久层换成了MyBatis Plus体系对现代开发更友好。但别随便把旧项目的Flowable 6升到7两个版本之间的一些配置项和API行为有差异升级成本不像依赖替换那么简单。2.2 数据库选型与MySQL连接串里的隐形坑Flowable跑起来需要一系列ACT_开头的表来维护流程定义、流程实例、任务、历史数据。首次启动时你可以让它自动建表但数据库得先建好。生产环境建议用MySQL或PostgreSQL本地练手可以用H2内存库配置简单但重启后数据全丢。如果用MySQL 8连接串里有一个参数特别关键spring: datasource: url: jdbc:mysql://localhost:3306/flowable?useUnicodetruecharacterEncodingutf8nullCatalogMeansCurrenttrueserverTimezoneAsia/Shanghai username: root password: root driver-class-name: com.mysql.cj.jdbc.DrivernullCatalogMeansCurrenttrue这个参数不加Flowable在某些MySQL版本下查询ACT_ID_GROUP等表时会直接报“Table doesnt exist”之类的异常。原因是JDBC驱动对catalog的处理方式不一致Flowable在获取表元数据时用到了catalog信息默认驱动行为会把当前catalog置为null结果误判了表是否存在。这个问题表面看是缺表实际是数据库连接参数的问题排查方向很容易跑偏。2.3 首次启动建表后的验证方法Flowable的表不是一次性全部建好是根据引擎初始化的深度分模块创建的。启动成功后你至少能看到ACT_GE_PROPERTY、ACT_GE_BYTEARRAY、ACT_RE_PROCDEF等几十张表。可以在数据库客户端执行SHOW TABLES LIKE ACT_%;如果一张表都没有基本可以确定引擎没有真正初始化。最常见的三个原因flowable.database-schema-update没配置、数据源没被Flowable识别、或者启动日志里有异常被logback吞了。建议第一轮就直接在SpringBoot启动日志里搜Flowable关键字看到类似Flowable 6.7.2 starting和database schema update successful的输出才算初始化成功。3. 依赖、配置与引擎服务跑通最小可用的集成环境3.1 pom.xml里到底要引入什么Flowable 6.x和7.x的Spring Boot Starter坐标是一样的直接在pom.xml里加dependency groupIdorg.flowable/groupId artifactIdflowable-spring-boot-starter-process/artifactId version6.7.2/version /dependency这一个依赖会把引擎核心、Spring Boot自动配置、BPMN解析等全部带进来。如果你后面想用DMN决策表再加flowable-spring-boot-starter-dmn想做流程监控页面可以引入flowable-spring-boot-starter-ui但这个UI实际生产用得少更多是自己开发。千万别同时引入flowable-engine和flowable-spring-boot-starter-process两套那会造成引擎初始化路径混乱Spring上下文里出现两个ProcessEngine的Bean各种诡异问题都会冒出来。3.2 最关键的五个配置项application.yml里除了数据源还需要把Flowable自身的开关配好。我实际项目里用的最小配置是这样flowable: database-schema-update: true async-executor-activate: true history: full db-history-used: true check-process-definitions: falsedatabase-schema-update: true启动时自动创建或更新表结构。生产环境想更稳妥可以改为false用SQL脚本手工管理表结构变更。async-executor-activate: true激活异步执行器定时器事件、异步任务都需要它。这个选项我第一次集成时没太在意后来做超时自动提醒功能时才发现没开。history: full历史记录级别。full会保存流程变量的所有快照方便追踪但数据量也最大。如果只是简单审批audit级别就够能拿到任务历史但不会记录变量变更细节。check-process-definitions: false默认情况下Flowable会去扫描并部署classpath下的流程定义文件如果还没准备BPMN文件先把它关掉免得启动报找不到文件的错。3.3 自动配置背后发生了什么Flowable的自动配置核心类会创建ProcessEngine然后把它管理的一系列Service注册到Spring容器里。你在业务代码里直接注入这些Bean就能用RepositoryService部署流程定义、查询流程定义。RuntimeService启动流程实例、触发流程推进。TaskService查询任务、认领任务、审批完成任务。HistoryService查询历史流程实例和活动记录。IdentityService设置流程发起人、管理用户组关系。ManagementService引擎管理和Job操作用得少。刚接触Flowable时很多人分不清RepositoryService和RuntimeService的区别。我自己的记忆方式是RepositoryService管“模板”流程定义是静态的模板RuntimeService管“实例”流程实例是模板跑起来的一次具体过程。定义相当于类实例相当于对象这样理解就顺了。4. 部署请假审批流程BPMN文件的写法与校验4.1 一个最简单的BPMN 2.0 XML长什么样Flowable用BPMN 2.0 XML来描述流程。你可以用Flowable官方Modeler画图然后导出XML也可以直接在IDEA里用插件画。但我觉得入门阶段最好手动写一遍XML这对理解流程结构很有帮助。一个经典的请假审批流包含开始事件、两个用户任务、一个排他网关和结束事件核心XML如下?xml version1.0 encodingUTF-8? definitions xmlnshttp://www.omg.org/spec/BPMN/20100524/MODEL xmlns:xsihttp://www.w3.org/2001/XMLSchema-instance xmlns:flowablehttp://flowable.org/bpmn targetNamespacehttp://www.flowable.org/processdef process idleaveProcess name请假审批流程 isExecutabletrue startEvent idstartEvent name发起申请/ userTask idapplyTask name填写请假单 flowable:assignee${applyUser}/ userTask idmanagerTask name经理审批 flowable:assignee${managerUser}/ exclusiveGateway idgateway name是否通过/ sequenceFlow idflow1 sourceRefstartEvent targetRefapplyTask/ sequenceFlow idflow2 sourceRefapplyTask targetRefmanagerTask/ sequenceFlow idflow3 sourceRefmanagerTask targetRefgateway/ sequenceFlow idflowPass sourceRefgateway targetRefendEvent conditionExpression xsi:typetFormalExpression${approved true}/conditionExpression /sequenceFlow sequenceFlow idflowReject sourceRefgateway targetRefapplyTask conditionExpression xsi:typetFormalExpression${approved false}/conditionExpression /sequenceFlow endEvent idendEvent name结束/ /process /definitions这里用到了两个流程变量applyUser和managerUser决定任务分配给谁approved决定审批通过还是驳回重填。排他网关的条件是按顺序解析的先匹配到的生效所以条件顺序很重要。我见过有人把两个条件都写成类似${status ! 0}结果永远走进第一个分支的情况。4.2 部署代码和校验步骤把上面的XML放到src/main/resources/processes/leave.bpmn20.xml然后通过RepositoryService部署Autowired private RepositoryService repositoryService; public void deployLeaveProcess() { Deployment deployment repositoryService.createDeployment() .name(请假审批流程) .addClasspathResource(processes/leave.bpmn20.xml) .deploy(); System.out.println(部署ID deployment.getId()); }部署完成后用查询接口确认流程定义是否成功发布ListProcessDefinition definitions repositoryService.createProcessDefinitionQuery() .processDefinitionKey(leaveProcess) .orderByProcessDefinitionVersion().desc() .list();这里要注意流程定义key相同的情况下每部署一次就会生成一个新版本。如果在开发阶段频繁部署ACT_RE_PROCDEF里会堆出一串历史版本启动流程时默认使用最新版本。这个设计是合理的但如果你在测试环境反复改了又部署查问题时会发现旧流程实例还在运行新流程实例却已经用了新版本逻辑对不上版本容易糊涂。4.3 中文乱码是部署时最容易踩的坑BPMN文件里写了中文部署后在流程定义名称里看到一串乱码这种问题很常见。根本原因是XML文件读取时的编码和引擎解析时的编码不一致。我遇到过的三种情况和对应解法文件保存为GBK编码而XML声明了UTF-8。这种情况直接改IDE默认编码把文件统一成UTF-8。使用addClasspathResource部署时Spring Boot读取classpath资源默认用了平台编码。在部署代码里显式指定UTF-8读字节流再用addInputStream部署通常能解决。Linux服务器环境变量LANG没设置导致JVM默认文件编码不是UTF-8。在启动参数里加上-Dfile.encodingUTF-8最稳妥。部署这块的经验是流程图可以先画个极简版本先把部署和启动链路走通再回过来丰富细节。我一开始就研究复杂的会签、子流程结果排错时既要排查XML问题又要看网关逻辑自己把自己绕晕了。5. 业务代码里的核心操作发起、查询、审批与条件流转5.1 发起流程实例的完整姿势Flowable里发起一个流程实例核心调用是RuntimeService.startProcessInstanceByKey。业务侧需要把流程变量一起传进去这样流程里的表达式才能解析Autowired private RuntimeService runtimeService; Autowired private IdentityService identityService; public void startLeave(String applyUser, String managerUser, Integer days) { identityService.setAuthenticatedUserId(applyUser); MapString, Object variables new HashMap(); variables.put(applyUser, applyUser); variables.put(managerUser, managerUser); variables.put(days, days); variables.put(approved, null); ProcessInstance processInstance runtimeService .startProcessInstanceByKey(leaveProcess, variables); System.out.println(流程实例ID processInstance.getId()); }identityService.setAuthenticatedUserId(applyUser)这个设置很关键它会在历史数据里记下发起人信息。如果不设置ACT_HI_PROCINST里的START_USER_ID_字段就是空的后续做流程追溯时无从查起。这段代码我建议放在业务事务的最外层保证发起人和流程实例在同一事务上下文中。5.2 查询待办任务和审批操作引擎会为每个userTask生成一条任务记录。业务系统里最常见的操作就是按人查待办Autowired private TaskService taskService; public ListTask findTodoTasks(String assignee) { return taskService.createTaskQuery() .taskAssignee(assignee) .orderByTaskCreateTime().desc() .list(); }任务查询可以组合很多条件比如.processInstanceId()按实例查、.taskDefinitionKey()按节点查、.active()只看未结束任务。实际项目里列表页还需要返回流程名称、发起人、发起时间这些业务字段那就需要拿task.getProcessInstanceId()再查一遍ACT_HI_PROCINST或者直接写自定义Mapper连表查。这里我更推荐后者因为引擎自带查询在复杂条件组合和分页性能上没那么理想业务侧用自定义SQL更灵活。审批完成的操作是public void completeTask(String taskId, boolean approved, String comment) { MapString, Object taskVariables new HashMap(); taskVariables.put(approved, approved); taskVariables.put(comment, comment); taskService.complete(taskId, taskVariables); }taskService.complete()会触发流程向前推进。如果走到了排他网关引擎会解析后续连线的条件表达式。特别注意表达式里变量为null时排他网关的校验会直接判false进入不了任何分支。我在5.1里特意把approved初始化为null就是防止在发起环节的表达式解析阶段出意外。5.3 网关条件里的表达式规则Flowable的条件表达式基于Spring的EL表达式最常用的三种写法${approved true}布尔变量比较。${days 3}数值比较这里days是Integer或Long。${managerUser lisi}字符串比较注意用单引号。表达式里方法调用也支持比如${businessService.isApproved(execution)}但这类写法会把业务逻辑耦合进流程定义除非特别必要否则我建议还是用纯变量表达式。一个额外的教训条件变量一定要在到达网关之前就放进变量表里否则网关在完全不知道变量存在的情况下不会报错而是直接抛异常或者走向默认分支这个问题排查起来特别容易懵。6. Spring事务与Flowable的配合自调用陷阱和异步执行器6.1 Flowable在Spring环境下的事务行为如果你用了flowable-spring-boot-starter-processFlowable会自动使用Spring的事务管理器。这意味着什么意味着Flowable的引擎操作会和你的业务操作在同一个事务里要么一起成功要么一起回滚。我举个例子业务侧在审批通过之后要更新业务单据状态Service public class LeaveService { Autowired private TaskService taskService; Autowired private LeaveOrderMapper leaveOrderMapper; Transactional(rollbackFor Exception.class) public void approveTask(String taskId, String orderId, boolean approved) { taskService.complete(taskId, Collections.singletonMap(approved, approved)); leaveOrderMapper.updateStatus(orderId, approved ? 2 : 3); } }由于两个操作在同一个Transactional事务里任务完成和单据状态的更新就是原子的。如果后面那步操作抛了RuntimeException任务流转也会回滚。这是Flowable整合Spring后最好的地方之一也是我建议把引擎操作包在Service方法里而不是直接丢给Controller的原因。6.2 自调用导致事务失效流程推进一半出了问题Spring事务基于代理实现而代理在通过this调用同类方法时不会被触发。这是一个老生常谈的坑但放在Flowable场景下风险更大Service public class LeaveService { // 错误写法内部调用导致Transactional不生效 public void handleBusiness(String taskId) { completeTaskInternal(taskId); } Transactional(rollbackFor Exception.class) public void completeTaskInternal(String taskId) { taskService.complete(taskId, Collections.singletonMap(approved, true)); } }上面的例子中completeTaskInternal的事务注解完全没用。流程任务一旦推进成功但后续业务代码异常引擎这步已经提交了数据就出现一边完成一边没更新的情况。解决方法是换一个Service类来调用或者在当前类里注入自己的代理对象。这个坑我印象特别深因为我们线上出现过一次审批通过但业务状态没更新的问题排查了一整个下午最后发现就是自调用导致事务边界失效。6.3 异步执行器的理解和配置flowable.async-executor-activate这个开关初学者容易直接复制配置没弄明白。它的作用是启动Flowable的异步执行器线程池用来处理定时器事件、异步延续等逻辑。如果你在流程里用了边界超时事件比如请假超过两天自动提醒经理就需要开启它。我建议从第一天就设成true不然以后加了定时器相关节点流程会卡在等待事件上不肯往下走。同时它支持线程池参数调整flowable: async-executor-activate: true async-executor-core-pool-size: 10 async-executor-max-pool-size: 20 async-executor-queue-capacity: 100默认值对中小项目够用流量上来再按实际情况调。线上调优时别只盯着线程池大小还要看数据库连接池因为异步执行器的任务最终都要落库连接池太小会出现等待连接的日志。7. 高频报错排雷与生产环境值得调的几个参数7.1 我整理了一份真实的报错排查表下面这些异常是我在实际项目和社区里见过频率最高的后面附上了根因和处理方式报错现象根因处理方案no processes deployed with key xxx流程未部署或key写错检查部署代码用repositoryService.createProcessDefinitionQuery()确认keyTable flowable.act_ge_property doesnt exist数据库schema未初始化检查flowable.database-schema-update配置确认账号有建表权限部署后流程名称中文乱码XML或JDBC读取编码不一致统一UTF-8编码启动参数加-Dfile.encodingUTF-8NullPointerException出现在表达式解析流程变量在网关判断前未赋值在启动流程或completeTask时显式初始化变量OptimisticLockingException同一流程实例被并发操作业务层做幂等控制或对任务加锁后再操作ClassNotFoundException: org.flowable.spring.boot.ProcessEngineAutoConfigurationFlowable和SpringBoot版本不匹配先核对版本对应表7.2 生产环境下值得调优的参数除了异步执行器线程池还有几个参数在流量上来后一定要关注。history级别建议按业务诉求控制。我之前有个项目对流程变量的历史不敏感但因为没改默认值ACT_HI_VARINST表长到了上千万行。后来把history调成audit彻底避免记录变量表的增量查询速度快了很多。代价是不能再追踪单个流程变量在每一步的值这个取舍看业务。数据库连接池参数也要跟着调。Flowable的异步执行器、定时任务Job都会占用连接而业务代码本身也要访问数据库。如果项目使用的是Druid或HikariCP建议最大连接数至少比引擎线程池多出一倍避免互相争抢连接池资源。历史表清理策略在Flowable里没有内置的老数据自动清理机制企业版除外生产上我一般自己写个定时任务按时间清理ACT_HI_PROCINST、ACT_HI_TASKINST、ACT_HI_ACTINST等表。写清理SQL时有一个特别注意点不要直接DELETE大表全量数据很可能把活跃流程引用的历史数据删了导致关联查询异常一定要先确认要清理的流程实例确实已经结束。7.3 实际项目里的扩展思路Flowable用顺手之后可以在它上面做不少扩展。比如我后来的项目在完成审批时用事件监听器同步ES索引用RuntimeService.addEventListener监听任务创建和流程结束事件。也做过动态加签通过RuntimeService.createChangeActivityStateBuilder()把流程实例移动到指定节点实现驳回或跳转。这些高级玩法都需要对Flowable的内部命令体系有所了解但前提仍然是先把基础的部署、发起、审批、条件流转跑通。我给新人的建议是从小流程开始建立完整的主线认知再去碰高级特性。工作流的调试成本天然比普通接口高如果连主线都没跑顺就上复杂特性出问题时很容易到处怀疑最后连问题出在“流程定义”还是“业务代码”都分不清。最后分享一个我自己的习惯每套流程定义我都会在本地写一个JUnit测试覆盖“正常通过”和“驳回重填”两条主线。不要小看这个步骤Flowable的流程定义改动很难发现副作用回归测试能帮你把大部分低级问题挡在开发阶段。你如果也在做SpringBoot项目且准备引入工作流希望这篇东西能帮你少走几个我走过的弯路。
