1. 为什么选择Flowable 7.x与Spring Boot 3.2?
如果你正在构建一个现代化的企业级应用,比如一个复杂的审批系统、一个自动化的订单处理流程,或者一个需要多人协同的任务管理系统,那么“工作流引擎”这个概念对你来说一定不陌生。它就像是应用里的“自动化流水线”,负责定义、执行和监控那些有固定步骤的业务流程。而Flowable,正是这个领域里一个非常强大且活跃的开源选择。
我最近在重构自己的一个项目管理微服务脚手架(eal-pm),决定引入工作流能力。在技术选型时,我直接瞄准了Flowable的最新7.x版本,并把它集成到基于Spring Boot 3.2和JDK 17的项目中。为什么这么选?这里有几个很实在的理由。首先,Spring Boot 3.2和JDK 17代表了Java生态当前最前沿、性能最优且长期支持的技术栈,用它们来搭建新项目,能确保应用的基础足够稳固和现代。其次,Flowable 7.x对Spring Boot 3.x提供了原生支持,集成起来非常顺畅,避免了版本兼容性带来的各种“坑”。最后,从Flowable 6到7,引擎在云原生、性能监控和API设计上都有显著提升,直接上手最新版,意味着我们能用到更完善的功能和更好的社区支持。
可能你会问,Activiti和Flowable是什么关系?简单来说,Flowable是Activiti核心团队另起炉灶创建的一个分支,目前发展得非常活跃,社区响应和版本迭代速度都很快。对于新项目,我个人更推荐直接从Flowable开始。这次实战,我们就从最基础的环境搭建讲起,我会把每一步的操作、遇到的细节和验证方法都掰开揉碎,确保你跟着做一遍,就能在自己的Spring Boot 3.2项目里成功跑起来Flowable 7.x。
2. 搭建基础开发环境
在开始集成Flowable之前,我们需要先把“地基”打好。这个地基就是运行我们项目所必需的软件和中间件。我的脚手架eal-pm是一个微服务项目,但为了简化Flowable入门,我们可以先从一个单体的Spring Boot应用开始集成,原理是相通的。下面是我本地开发环境的清单,你可以对照检查。
2.1 核心开发工具安装
第一件事是安装JDK。必须使用JDK 17或更高版本,因为Spring Boot 3.2最低要求就是JDK 17。我推荐直接安装Oracle JDK 17的LTS(长期支持)版本,或者使用开源的Eclipse Temurin JDK 17,两者都很稳定。安装后,记得在终端里用 java -version 和 javac -version 命令验证一下,确保版本号正确且JAVA_HOME环境变量已配置好。
接下来是构建工具。我习惯用Maven,版本需要在3.6以上。如果你用IntelliJ IDEA或VS Code这些现代IDE,它们通常都内置了Maven支持,非常方便。不过我还是建议在系统里独立安装一个,方便在命令行里执行构建命令。检查命令是 mvn -v。当然,如果你更喜欢Gradle,也完全没问题,Flowable对Gradle的支持同样很好。
2.2 数据库与中间件准备
Flowable需要数据库来存储流程定义、实例运行数据、历史记录等信息。官方支持多种数据库,最常用的还是MySQL。我这里以MySQL 8.0.x为例(兼容8.3.0)。你可以在官网下载安装包,但我更推荐用Docker来快速启动一个,省去配置的麻烦。下面这条命令可以帮你启动一个MySQL 8.0容器:
docker run -d --name flowable-mysql \
-p 3306:3306 \
-e MYSQL_ROOT_PASSWORD=your_strong_password \
-e MYSQL_DATABASE=flowable_db \
-v /your/local/path/mysql_data:/var/lib/mysql \
mysql:8.0
解释一下几个关键参数:-p 3306:3306 是把容器的3306端口映射到本机的3306端口;MYSQL_ROOT_PASSWORD 和 MYSQL_DATABASE 分别设置了root密码和自动创建的数据库名;-v 参数把数据挂载到本地目录,这样即使容器删除,数据也不会丢失。启动后,你可以用MySQL客户端(如DBeaver、Navicat)连接 localhost:3306,看看 flowable_db 数据库是否已经创建成功。
除了数据库,我的脚手架里还用到了Redis做缓存,用到了MongoDB存储一些非结构化数据。对于Flowable基础集成来说,Redis不是必须的,但如果你想做流程引擎的缓存优化或者分布式会话管理,它会很有用。MongoDB在Flowable中主要用于存储一些引擎的附加内容,比如表单、内容等,初期可以先不配置。为了环境完整,我也把它们的Docker启动命令放在这里,你可以根据需要启用:
# Redis
docker run -d --name flowable-redis -p 6379:6379 redis:7-alpine
# MongoDB
docker run -d --name flowable-mongo \
-p 27017:27017 \
-e MONGO_INITDB_ROOT_USERNAME=admin \
-e MONGO_INITDB_ROOT_PASSWORD=secret \
mongo:7.0
3. 创建Spring Boot 3.2项目并集成Flowable依赖
环境准备好后,我们就可以动手创建项目了。这里有两种方式:一是通过Spring Initializr(start.spring.io)在线生成,二是在已有的项目中直接添加依赖。我演示在已有脚手架中集成,但新建项目的步骤是完全一样的。
3.1 初始化项目骨架
如果你是新项目,访问Spring Initializr,按照下图选择:Project选Maven,Language选Java,Spring Boot版本选3.2.x(目前最新是3.2.5)。在Dependencies里,先添加 Spring Web 和 Spring Data JPA,这两个是基础。Group和Artifact按你的习惯来,比如 com.example 和 flowable-demo。打包方式选Jar,Java版本选17。生成项目后,用IDE打开。
如果你是在像我eal-pm这样的现有项目中集成,那就更简单了,直接打开主工程的 pom.xml 文件,找到 <dependencies> 节点,准备添加Flowable的依赖。
3.2 引入Flowable核心依赖
Flowable为Spring Boot提供了官方的Starter,这让集成变得异常简单。我们主要需要两个依赖:flowable-spring-boot-starter 和对应数据库的驱动。在 pom.xml 里添加如下依赖:
<dependency>
<groupId>org.flowable</groupId>
<artifactId>flowable-spring-boot-starter</artifactId>
<version>7.0.1</version> <!-- 请检查并使用最新版本 -->
</dependency>
<dependency>
<groupId>com.mysql</groupId>
<artifactId>mysql-connector-j</artifactId>
<scope>runtime</scope>
</dependency>
这里有几个关键点需要注意。第一,务必去Maven中央仓库或Flowable官网确认最新版本,我写文章时7.0.1是稳定版,但可能已经有更新。第二,mysql-connector-j 是MySQL 8.x的官方驱动,注意artifactId不再是老的 mysql-connector-java。第三,flowable-spring-boot-starter 这个包是个“全家桶”,它会自动引入流程引擎、Spring集成、REST API等所有核心模块,不需要我们再一个个手动引入其他Flowable jar包了,非常省心。
添加依赖后,IDE通常会开始自动下载。如果网络不好,可以尝试在命令行进入项目目录,执行 mvn clean compile 命令来强制下载依赖并编译,看看有没有报错。顺利的话,你的项目就已经具备了Flowable的全部能力。
4. 配置数据库连接与引擎参数
依赖加好了,下一步就是告诉Flowable怎么连接数据库,以及根据我们的需要调整一些引擎行为。所有的配置都在Spring Boot的标准配置文件 application.yml(或 application.properties)里完成。
4.1 基础数据源配置
首先是最基本的数据源配置,这和你配置任何一个使用JPA或MyBatis的Spring Boot项目没有区别:
spring:
datasource:
url: jdbc:mysql://localhost:3306/flowable_db?useUnicode=true&characterEncoding=utf8&useSSL=false&serverTimezone=Asia/Shanghai
username: root
password: your_strong_password
driver-class-name: com.mysql.cj.jdbc.Driver
jpa:
hibernate:
ddl-auto: validate # 重要:不建议使用create-drop或update
show-sql: true # 开发环境可以打开,方便看SQL
properties:
hibernate:
dialect: org.hibernate.dialect.MySQL8Dialect
我特别想强调 ddl-auto 这个配置。对于Flowable这种有自己复杂表结构的组件,强烈不建议设置为 update。因为Flowable引擎在启动时会自动检查数据库表结构,如果缺失会自动执行SQL脚本来创建。如果我们用Hibernate的 update,可能会导致表结构混乱。安全起见,设置为 validate,让Hibernate只验证实体与表是否匹配,或者干脆设置为 none。
4.2 Flowable引擎专属配置
接下来是Flowable特有的配置。在 application.yml 里继续添加:
flowable:
async-executor-activate: true # 启用异步执行器,处理定时任务等
database-schema-update: true # 启动时自动创建或更新数据库表
history-level: audit # 历史记录级别,audit会保存大部分历史信息,适合审计
db-history-used: true # 使用独立的历史数据表
# 禁用自动部署,我们手动控制流程定义的部署
deployment-mode: never-fail
check-process-definitions: false
我来解释一下这几个比较关键的配置。database-schema-update: true 是让Flowable在应用启动时,自动去检查 flowable_db 数据库。如果发现表不存在,它就会执行内置的SQL建表脚本。第一次启动时,你会看到日志里打印大量Creating table...的信息,这就是它在建表。history-level 有多个选项:none(不保存历史)、activity(保存节点信息)、audit(保存节点和变量信息)、full(保存全部细节,包括变量更新)。对于大多数业务场景,audit 是一个平衡了性能和可追溯性的选择。async-executor-activate: true 对于需要定时器事件、异步任务等功能的流程是必须的。
配置完成后,你可以先启动一下应用试试。如果控制台没有报数据库连接错误,并且看到类似 Flowable ProcessEngine started 的日志,那么恭喜你,Flowable引擎已经成功集成并启动了!此时去数据库看看,应该已经多出了几十张以 ACT_ 开头的表,这些就是Flowable的“大脑”,负责存储流程的一切。
5. 验证集成:编写第一个流程定义与API
环境跑通了,但我们还得确认引擎真的能工作。最好的验证方式就是部署一个最简单的流程,然后通过代码来启动它、完成它。这个过程能让我们直观地理解Flowable的核心概念。
5.1 创建并部署一个BPMN 2.0流程
Flowable使用标准的BPMN 2.0 XML文件来定义流程。我们在 src/main/resources 目录下新建一个 processes 文件夹,然后创建一个名为 my-first-process.bpmn20.xml 的文件。内容如下:
<?xml version="1.0" encoding="UTF-8"?>
<definitions xmlns="http://www.omg.org/spec/BPMN/20100524/MODEL"
xmlns:flowable="http://flowable.org/bpmn"
targetNamespace="http://flowable.org/bpmn">
<process id="myFirstProcess" name="我的第一个流程" isExecutable="true">
<startEvent id="startEvent1"/>
<sequenceFlow sourceRef="startEvent1" targetRef="userTask1"/>
<userTask id="userTask1" name="审批任务" flowable:assignee="${assignee}"/>
<sequenceFlow sourceRef="userTask1" targetRef="endEvent1"/>
<endEvent id="endEvent1"/>
</process>
</definitions>
这个流程简单到极致:开始事件 -> 用户任务 -> 结束事件。用户任务的办理人(assignee)通过变量 ${assignee} 动态指定。接下来,我们需要写一段Java代码来部署这个流程文件。创建一个Spring Bean,比如 ProcessDeployer:
import org.flowable.engine.RepositoryService;
import org.springframework.boot.CommandLineRunner;
import org.springframework.core.io.ClassPathResource;
import org.springframework.core.io.Resource;
import org.springframework.stereotype.Component;
import java.io.IOException;
@Component
public class ProcessDeployer implements CommandLineRunner {
private final RepositoryService repositoryService;
public ProcessDeployer(RepositoryService repositoryService) {
this.repositoryService = repositoryService;
}
@Override
public void run(String... args) throws IOException {
Resource resource = new ClassPathResource("processes/my-first-process.bpmn20.xml");
repositoryService.createDeployment()
.addInputStream("my-first-process.bpmn20.xml", resource.getInputStream())
.name("我的第一个流程部署")
.deploy();
System.out.println("流程部署成功!");
}
}
CommandLineRunner 接口会让 run 方法在Spring Boot应用启动完成后自动执行。它通过注入的 RepositoryService(Flowable管理流程定义的服务)将我们的BPMN文件部署到引擎中。启动应用,如果看到“流程部署成功!”的日志,并且去数据库 ACT_RE_PROCDEF 表里能看到一条流程定义记录,就说明部署成功了。
5.2 通过RuntimeService启动并完成任务
流程定义部署好了,它只是一个“模板”。要让它运行起来,需要启动一个流程实例。我们再写一个简单的REST API来演示如何启动流程、查询任务和完成任务。创建一个 ProcessController:
import org.flowable.engine.RuntimeService;
import org.flowable.engine.TaskService;
import org.flowable.task.api.Task;
import org.springframework.web.bind.annotation.*;
import java.util.HashMap;
import java.util.List;
import java.util.Map;
@RestController
@RequestMapping("/api/process")
public class ProcessController {
private final RuntimeService runtimeService;
private final TaskService taskService;
// 构造器注入...
public ProcessController(RuntimeService runtimeService, TaskService taskService) {
this.runtimeService = runtimeService;
this.taskService = taskService;
}
// 启动流程实例
@PostMapping("/start")
public String startProcess(@RequestParam String assignee) {
Map<String, Object> variables = new HashMap<>();
variables.put("assignee", assignee);
var processInstance = runtimeService.startProcessInstanceByKey("myFirstProcess", variables);
return "流程实例启动成功,ID: " + processInstance.getId();
}
// 查询某个用户的任务
@GetMapping("/tasks")
public List<Task> getTasks(@RequestParam String assignee) {
return taskService.createTaskQuery().taskAssignee(assignee).list();
}
// 完成任务
@PostMapping("/complete/{taskId}")
public String completeTask(@PathVariable String taskId) {
taskService.complete(taskId);
return "任务 " + taskId + " 已完成";
}
}
现在,我们可以用Postman或curl来测试了。第一步,调用 POST /api/process/start?assignee=zhangsan。这会让引擎创建一个流程实例,并将用户任务分配给“zhangsan”。第二步,调用 GET /api/process/tasks?assignee=zhangsan,你会得到一个任务列表,里面应该有一条ID为“zhangsan”的任务。第三步,拿着这个任务ID,调用 POST /api/process/complete/{taskId},任务就完成了,流程会走到结束事件。
通过这一套操作,我们验证了从流程部署、实例启动、任务查询到任务完成的完整链路。这证明了我们的Spring Boot 3.2环境与Flowable 7.x的集成是完全成功且可用的。在这个过程中,你可能已经接触到了Flowable最核心的几个Service:RepositoryService、RuntimeService、TaskService,它们是后续我们操作流程的利器。
6. 常见问题排查与优化建议
第一次集成,难免会遇到一些问题。我把自己踩过的坑和解决方案总结一下,希望能帮你快速排雷。
6.1 启动时报错:表不存在或语法错误
这是最常见的问题。如果启动时抛出一堆SQL异常,说某个 ACT_ 表不存在,首先检查 flowable.database-schema-update 是否设置为 true。如果已经是 true 还报错,请检查数据库连接URL、用户名密码是否正确,以及该数据库用户是否有创建表的权限。另一个可能是MySQL版本问题,确保你使用的是MySQL 5.7以上或MariaDB 10.3以上。
如果错误信息是SQL语法错误,比如提示某个关键字错误,这很可能是MySQL模式问题。可以尝试在数据库连接URL后面加上 &sessionVariables=sql_mode=NO_ENGINE_SUBSTITUTION,或者检查MySQL的 sql_mode 是否包含 ONLY_FULL_GROUP_BY 等严格模式,可以考虑暂时将其移除。
6.2 流程部署失败:BPMN文件解析错误
如果你在部署流程时遇到XML解析错误,请首先确认你的BPMN文件格式是否正确。一个快速验证的方法是使用Flowable提供的在线设计器(Flowable Modeler)或者Eclipse的BPMN 2.0插件来绘制并导出XML,这样可以保证格式的规范性。另外,检查XML头部的命名空间(xmlns)是否正确,我上面提供的例子是Flowable 7.x可用的。文件后缀名最好是 .bpmn20.xml,这样Flowable的自动扫描器才能识别。
6.3 性能与生产环境配置建议
在开发环境,我们怎么方便怎么来。但一旦要上生产,有些配置就需要调整了。第一,务必把 flowable.database-schema-update 改为 false。生产环境的表结构应该通过Flyway或Liquibase这样的数据库迁移工具来管理,使用版本控制的SQL脚本,而不是让应用自动创建。第二,spring.jpa.hibernate.ddl-auto 也设置为 validate 或 none。第三,根据业务量调整历史数据级别。如果流程实例非常多,history-level 设置为 audit 或 activity 可以显著减少历史表的数据量,提升性能。第四,考虑启用 flowable.idm.enabled=false。如果你的系统已经有自己的用户权限体系,可以禁用Flowable自带的身份管理模块,避免维护两套用户数据。
还有一个实践是,将流程定义文件(BPMN)的部署与管理放到一个独立的“流程管理服务”中,而不是和业务代码混在一起。这样当业务服务需要启动流程时,通过API调用流程管理服务来获取最新的流程定义,架构上更清晰,也便于流程的独立升级和回滚。
走到这一步,你已经成功搭建了一个集成了Flowable 7.x工作流引擎的Spring Boot 3.2项目,并且跑通了一个完整的流程。这只是一个开始,Flowable的强大之处在于它丰富的任务类型(如脚本任务、服务任务、网关)、事件机制、表单引擎以及与Spring Security的深度集成。在后续的实战中,我们会深入这些特性,并结合前端bpmn.js设计器,打造一个可视化的流程管理平台。如果你在搭建过程中遇到了其他问题,欢迎在评论区交流。
1034



被折叠的 条评论
为什么被折叠?



