springboot flowable 工作流入门与实战

Spring Boot3 Flowable 项目地址

https://gitee.com/supervol/loong-springboot-study

（记得给个start，感谢）

Flowable 概述

        Flowable 是一款基于 BPMN 2.0 规范的轻量级、高性能开源流程引擎，专注于流程自动化、业务流程管理（BPM）与工作流编排。Spring Boot 3 作为主流的 Java 开发框架，通过自动配置与 starters 机制，极大简化了 Flowable 的集成与使用。

Flowable 核心

1. Spring Boot 3 关键特性

        Spring Boot 3 基于 Spring Framework 6，核心升级点包括：

• 最低支持 JDK 17+，适配 Jakarta EE 9/10（包名从 javax.* 迁移为 jakarta.*）；
• 强化原生镜像支持（GraalVM）；
• 简化自动配置逻辑，支持条件化 Bean 注册的精细化控制。

        这些特性要求 Flowable 必须使用适配 Jakarta EE 与 JDK 17+ 的版本（Flowable 7.x 及以上）。

2. Flowable 核心定位与组件

        Flowable 源于 Activiti 分支，核心价值是将 “业务流程” 从代码中解耦，通过可视化建模（BPMN 文件）定义流程，再由引擎驱动执行。其核心组件包括：

• 流程引擎（ProcessEngine）：Flowable 的核心入口，负责创建与管理其他服务组件；
• 核心服务（Services）：封装具体业务能力的接口，如：
  • RepositoryService：流程定义的部署、查询与管理；
  • RuntimeService：流程实例的启动、暂停、查询；
  • TaskService：用户任务 / 组任务的分配、查询、完成；
  • HistoryService：流程历史数据（实例、任务、变量）的查询；
  • ManagementService：引擎配置、定时任务的管理；
• BPMN 2.0 规范：定义流程的国际标准，支持流程节点（开始 / 结束事件、用户任务、服务任务等）、网关（排他 / 并行网关）、流程变量等核心元素。

Flowable 对比

特性	Flowable	Camunda	Activiti 7	JBPM (RedHat)
起源	2016 年从 Activiti 分支而来	2013 年由 Activiti 创始人团队创建	2010 年由 Alfresco 发起，后归属于 Camunda	2003 年起源，现为 RedHat 旗下
BPMN 2.0 兼容性	完全兼容，支持复杂流程模式	完全兼容，强调 “可执行性” 与规范严格性	兼容基础规范，复杂场景支持较弱	兼容，更侧重与 Drools 规则引擎集成
核心定位	轻量、高性能、易扩展	企业级完整 BPM 平台（流程 + 决策 + 表单）	轻量入门级工作流	与 RedHat 生态深度整合的 BPM 引擎
Spring 整合	原生支持 Spring Boot 3，自动配置完善	支持 Spring Boot 3，配置略复杂	支持 Spring Boot，但更新较慢	支持 Spring，更优与 JBoss 整合
历史数据管理	灵活的历史级别（NONE/FULL 等）	精细化历史追踪，支持流程实例重放	基础历史记录，功能较简单	与流程执行紧耦合，查询能力一般
企业级特性	多租户、权限集成（Spring Security）	多租户、SSO、流程监控（Operate）	基础多租户，企业特性较弱	多租户、与 RedHat 权限系统集成
社区活跃度	活跃，版本迭代快（7.x 适配 JDK 17）	非常活跃，企业支持强	较低，更新缓慢	中等，依赖 RedHat 战略
商业支持	Flowable GmbH 提供企业版服务	Camunda 公司提供商业支持	由 Camunda 维护，企业版服务较弱	RedHat 提供商业支持与服务

        推荐：Flowable或Camunda

Flowable 示例

        请参考项目地址中 springboot-workflow/springboot-flowable 模块代码。

Flowable 整合

1. 环境要求

依赖项	版本要求	说明
JDK	17 及以上	适配 Spring Boot 3 最低要求
Spring Boot	3.0.x 及以上	本文以 3.2.0 为例
Flowable	7.0.0 及以上	需适配 Jakarta EE 与 Spring Boot 3
数据库	MySQL 8.0/Oracle 19c/PostgreSQL 14 等	Flowable 需持久化流程数据

2. 依赖配置

        Spring Boot 3 整合 Flowable 需引入 Flowable Spring Boot Starters，无需手动配置流程引擎。核心依赖如下：

<!-- 核心依赖：Flowable Spring Boot Starter（包含流程引擎核心服务） -->
<dependency><groupId>org.flowable</groupId><artifactId>flowable-spring-boot-starter</artifactId><version>7.0.1</version>
</dependency><!-- 数据库驱动（以 MySQL 为例） -->
<dependency><groupId>com.mysql</groupId><artifactId>mysql-connector-j</artifactId><scope>runtime</scope>
</dependency>

3. 核心配置

        Flowable 会自动读取 Spring Boot 的数据源配置，并自动初始化数据库表结构（默认策略：create-drop）。核心配置如下：

# 1. 数据源配置
spring:datasource:url: jdbc:mysql://localhost:3306/flowable_db?useSSL=false&serverTimezone=UTC&allowPublicKeyRetrieval=trueusername: rootpassword: 123456driver-class-name: com.mysql.cj.jdbc.Driver# 2. Flowable 配置
flowable:# 数据库表结构更新策略（生产环境建议用 none 或 validate）database-schema-update: true  # 等价于 create-drop，开发环境可用# 历史级别（控制历史数据的存储粒度，默认 FULL）history-level: FULL  # 可选：NONE（无历史）、ACTIVITY（活动历史）、AUDIT（审计级）、FULL（全量）# 流程定义部署路径（默认扫描 classpath:processes/ 下的 BPMN 文件）process-definition-location-prefix: classpath:processes/# 定时任务线程池配置async-executor-core-pool-size: 5async-executor-max-pool-size: 10

关键配置说明：

• database-schema-update：开发环境用 true（自动建表），生产环境必须改为 none（手动执行 SQL 初始化）；
• history-level：存储粒度越高，查询能力越强，但性能开销越大，需根据业务场景选择（如仅需审计用 AUDIT）；
• 流程定义默认扫描路径 classpath:processes/：将 BPMN 文件放在此目录下，Flowable 会自动部署。

Flowable 实践

        以经典的 “请假流程”（员工申请 → 经理审批 → 流程结束）为例，演示 Flowable 的核心流程开发步骤。

1. 绘制 BPMN 流程定义

        Flowable 支持通过 Flowable Modeler（可视化建模工具）绘制 BPMN 2.0 流程，生成 .bpmn20.xml 或 .bpmn 文件。请假流程 BPMN 核心元素：

1. 开始事件：流程触发点；
2. 用户任务（User Task）：
   • 员工申请：assignee 设为 #{applicant}（动态指定申请人）；
   • 经理审批：assignee 设为 #{manager}（动态指定审批人）；
3. 排他网关（Exclusive Gateway）：根据 “审批结果” 分支（通过 / 驳回）；
4. 结束事件：流程终止点。

        生成的 leave-process.bpmn 文件放在 src/main/resources/processes/ 目录下，Flowable 启动时会自动部署。

2. 核心服务注入与使用

        Flowable 的核心服务（RepositoryService、RuntimeService 等）已由 Spring Boot 自动配置为 Bean，可直接通过 @Autowired 注入使用。

（1）流程定义部署

• 自动部署：将 BPMN 文件放在 classpath:processes/ 下，启动 Spring Boot 应用时，Flowable 会自动调用 RepositoryService 部署流程定义；
• 手动部署（如需动态部署）：

@Service
public class LeaveProcessService {@Autowiredprivate RepositoryService repositoryService;// 手动部署流程定义（从文件/输入流）public void deployProcess() {Deployment deployment = repositoryService.createDeployment().addClasspathResource("processes/leave-process.bpmn")  // 流程文件路径.name("请假流程V1.0")  // 部署名称.category("人事流程")  // 流程分类.deploy();  // 执行部署System.out.println("部署成功，部署ID：" + deployment.getId());}
}

（2） 启动流程实例

        流程实例是流程定义的 “一次执行”（如员工张三的请假申请），通过 RuntimeService 启动，可携带流程变量（如请假天数、申请人、审批人）。

@Service
public class LeaveProcessService {@Autowiredprivate RuntimeService runtimeService;// 启动请假流程实例public String startLeaveProcess(String applicant, String manager, Integer days) {// 流程变量（用于动态填充 BPMN 中的 #{applicant} 等表达式）Map<String, Object> variables = new HashMap<>();variables.put("applicant", applicant);variables.put("manager", manager);variables.put("leaveDays", days);// 启动流程实例（通过流程定义Key，默认取 BPMN 文件中 process 标签的 id 属性）ProcessInstance processInstance = runtimeService.startProcessInstanceByKey("leaveProcess",  // 流程定义Key（BPMN中 process id="leaveProcess"）variables       // 流程变量);System.out.println("流程实例启动成功，实例ID：" + processInstance.getId());return processInstance.getId();}
}

（3）处理用户任务

        用户任务需通过 TaskService 查询（按申请人 / 审批人），并执行 “完成任务” 操作，可传递任务结果（如审批意见）。

@Service
public class LeaveProcessService {@Autowiredprivate TaskService taskService;// 1. 查询指定用户的待办任务public List<Task> getTodoTasks(String assignee) {return taskService.createTaskQuery().taskAssignee(assignee)  // 按办理人查询.orderByTaskCreateTime().desc()  // 按创建时间倒序.list();}// 2. 完成任务（如经理审批）public void completeTask(String taskId, boolean approved, String comment) {Map<String, Object> variables = new HashMap<>();variables.put("approved", approved);  // 审批结果（用于网关分支）variables.put("comment", comment);    // 审批意见// 完成任务并传递变量taskService.complete(taskId, variables);System.out.println("任务完成，任务ID：" + taskId);}
}

（4） 查询流程历史

        流程执行完成后，通过 HistoryService 查询历史数据（如实例状态、任务处理记录、变量变更），用于审计或报表。

@Service
public class LeaveProcessService {@Autowiredprivate HistoryService historyService;// 查询流程实例的历史记录public HistoricProcessInstance getProcessHistory(String processInstanceId) {return historyService.createHistoricProcessInstanceQuery().processInstanceId(processInstanceId).singleResult();}// 查询指定流程实例的所有历史任务public List<HistoricTaskInstance> getTaskHistory(String processInstanceId) {return historyService.createHistoricTaskInstanceQuery().processInstanceId(processInstanceId).orderByTaskCreateTime().asc().list();}
}

3.接口层调用

        通过 REST 接口暴露流程功能，供前端调用：

@RestController
@RequestMapping("/api/leave")
public class LeaveController {@Autowiredprivate LeaveProcessService leaveProcessService;// 启动请假流程@PostMapping("/start")public ResponseEntity<String> start(@RequestParam String applicant,@RequestParam String manager,@RequestParam Integer days) {String processInstanceId = leaveProcessService.startLeaveProcess(applicant, manager, days);return ResponseEntity.ok("流程启动成功，实例ID：" + processInstanceId);}// 查询待办任务@GetMapping("/todo")public ResponseEntity<List<Task>> getTodo(@RequestParam String assignee) {return ResponseEntity.ok(leaveProcessService.getTodoTasks(assignee));}// 完成审批任务@PostMapping("/complete")public ResponseEntity<String> complete(@RequestParam String taskId,@RequestParam boolean approved,@RequestParam String comment) {leaveProcessService.completeTask(taskId, approved, comment);return ResponseEntity.ok("任务审批完成");}
}

Flowable 高级

1. 流程事件监听

        Flowable 支持通过 “监听器” 监听流程生命周期事件（如实例启动 / 结束、任务创建 / 完成），实现业务扩展（如发送通知、更新业务表）。示例：任务创建监听器（发送审批通知）

（1）定义监听器类

@Component
public class TaskCreateListener implements TaskListener {@Overridepublic void notify(DelegateTask delegateTask) {// 获取任务信息String taskId = delegateTask.getId();String assignee = delegateTask.getAssignee();String processInstanceId = delegateTask.getProcessInstanceId();// 模拟发送通知（实际项目可集成短信/邮件服务）System.out.println("通知：用户 " + assignee + " 有新任务（任务ID：" + taskId + "），流程实例：" + processInstanceId);}
}

（2）在 BPMN 中配置监听器
        在 “经理审批” 任务的 “Listeners” 中添加 “Task Create” 事件，引用上述监听器（需通过 delegateExpression 注入 Spring Bean）：

<userTask id="managerAudit" name="经理审批" activiti:assignee="#{manager}"><extensionElements><activiti:taskListener event="create" delegateExpression="${taskCreateListener}" /></extensionElements>
</userTask>

2. 与 Spring Security 整合

        Flowable 可集成 Spring Security 实现任务权限控制（如仅登录用户可查询自己的待办任务）。核心配置：

1. 引入 Spring Security 依赖；
2. 配置 FlowableSecurityConfig，指定 “当前登录用户” 的获取方式：

@Configuration
public class FlowableSecurityConfig {@Beanpublic FlowableAuthenticationProvider flowableAuthenticationProvider() {return new FlowableAuthenticationProvider() {@Overridepublic Authentication getAuthentication() {// 从 Spring Security 中获取当前登录用户Authentication auth = SecurityContextHolder.getContext().getAuthentication();if (auth == null) {return null;}// 转换为 Flowable 认证对象return new FlowableUserDetailsAuthentication(auth);}};}
}

3. 多租户支持

        Flowable 支持多租户隔离（通过 tenantId 区分不同租户的流程定义与实例），Spring Boot 中可通过配置默认租户或动态指定：

# 配置默认租户ID
flowable:tenant-id: default-tenant

        动态指定租户（部署 / 启动流程时）：

// 部署租户专属流程
repositoryService.createDeployment().addClasspathResource("processes/tenant-leave.bpmn").tenantId("tenant-1001")  // 指定租户ID.deploy();// 启动租户专属流程实例
runtimeService.startProcessInstanceByKeyAndTenantId("leaveProcess",variables,"tenant-1001"  // 租户ID
);

Flowable 注意

1. 流程定义版本管理

        Flowable 会为同一 processKey 的流程定义自动递增版本号（如 leaveProcess:1、leaveProcess:2）。部署新流程时：

• 旧流程实例不受影响（继续按旧版本执行）；
• 新启动的流程实例使用最新版本；
• 可通过 repositoryService 查询所有版本：

  List<ProcessDefinition> definitions = repositoryService.createProcessDefinitionQuery().processDefinitionKey("leaveProcess").list();
  

2. 数据库性能优化

• 历史级别选择：非审计场景用 ACTIVITY 或 NONE，减少历史数据存储；
• 定时清理历史数据：通过 HistoryService 定期删除过期历史记录；
• 数据库索引：Flowable 自动创建基础索引，可根据查询场景补充（如按 processInstanceId 查任务的索引）。

3. 避免流程死循环

• 网关分支条件必须互斥且覆盖所有场景（如审批结果仅 “通过 / 驳回”，避免 null 导致死循环）；
• 开发环境启用 Flowable 调试日志，追踪流程执行路径：

  logging:level:org.flowable: DEBUG
  

4. 生产环境配置建议

配置项	生产环境建议	原因
database-schema-update	none	避免自动建表 / 删表导致数据丢失，需手动执行 Flowable 提供的 SQL 脚本
history-level	AUDIT	平衡审计需求与性能开销
数据源	配置连接池（如 HikariCP）	提升并发访问性能
异步执行器	增大线程池（max-pool-size: 20+）	处理大量异步任务（如定时任务、异步服务任务）

总结

        Spring Boot 3 与 Flowable 的整合，通过自动配置简化了流程引擎的初始化，让开发者聚焦于 “流程设计” 而非 “引擎配置”。核心流程为：绘制 BPMN 流程定义 → 部署流程 → 启动实例 → 处理任务 → 查询历史。结合进阶功能（如事件监听、多租户、Spring Security 整合），可满足复杂业务场景的流程自动化需求。在实际项目中，需根据业务复杂度选择合适的历史级别、优化数据库性能，并通过 Flowable 的监控工具保障流程稳定运行。