Spring Boot 集成 Flowable 7.1.0 完整教程

一、引言

在企业级应用开发中，工作流管理是不可或缺的一部分。从简单的请假审批到复杂的业务流程，工作流引擎能够显著提升系统的灵活性和可维护性。​​Flowable​​ 作为一个轻量级、基于 Java 的开源工作流引擎，完美支持 ​​BPMN 2.0​​ 标准，广泛应用于各类业务流程管理场景。

​​Spring Boot​​ 凭借其快速开发、自动配置等特性，已成为现代 Java 开发的主流框架。将 ​​Spring Boot 3​​ 与 ​​Flowable 7.1.0​​ 集成，不仅能够快速构建功能强大的工作流应用，还能极大地简化开发流程，提高开发效率。

本教程将从环境准备、依赖配置、数据库设置、流程引擎初始化、流程设计与部署、流程运行与监控等多个方面，详细介绍如何将 Spring Boot 3 与 Flowable 7.1.0 进行深度集成，帮助开发者快速上手并构建专业级的工作流系统。

二、环境准备

在开始集成之前，确保您的开发环境满足以下要求：

• ​​JDK​​: 推荐使用 JDK 17 或更高版本（本教程以 JDK 21 为例）
• ​​IDE​​: IntelliJ IDEA、Eclipse 等主流 Java IDE
• ​​构建工具​​: Maven 或 Gradle（本教程以 Maven 为例）
• ​​数据库​​: MySQL 8.0（也可根据需要选择其他支持的数据库）
• ​​Flowable 版本​​: 7.1.0
• ​​Spring Boot 版本​​: 3.4.1（根据实际情况选择）

三、创建 Spring Boot 项目

您可以使用 Spring Initializr 快速创建一个新的 Spring Boot 项目，或者手动创建一个 Maven 项目。以下是主要步骤：

1. 使用 Spring Initializr 创建项目

1. 访问 Spring Initializr
2. 配置项目基本信息：
   • ​​Project​​: Maven Project
   • ​​Language​​: Java
   • ​​Spring Boot​​: 3.4.1（根据最新版本选择）
   • ​​Group​​: com.example（根据实际情况修改）
   • ​​Artifact​​: flowable-demo（根据实际情况修改）
   • ​​Name​​: flowable-demo
   • ​​Package name​​: com.example.flowabledemo
   • ​​Packaging​​: Jar
   • ​​Java​​: 21
3. 添加依赖：
   • ​​Spring Web​​
   • ​​Spring Data JPA​​（可选，根据需要）
   • ​​MySQL Driver​​
   • ​​Spring Security​​（可选，根据需要）
4. 生成并下载项目，导入到您的 IDE 中。

2. 手动创建 Maven 项目

如果您选择手动创建 Maven 项目，确保 pom.xml 包含以下基本配置：

<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/maven-v4_0_0.xsd"><modelVersion>4.0.0</modelVersion><groupId>com.example</groupId><artifactId>flowable-demo</artifactId><version>1.0.0</version><packaging>jar</packaging><name>Flowable Demo</name><properties><java.version>21</java.version><spring-boot.version>3.4.1</spring-boot.version><flowable.version>7.1.0</flowable.version></properties><dependencies><!-- 待添加 --></dependencies><build><plugins><plugin><groupId>org.springframework.boot</groupId><artifactId>spring-boot-maven-plugin</artifactId><version>${spring-boot.version}</version></plugin></plugins></build>
</project>

四、添加依赖

在 pom.xml 中添加 Spring Boot 和 Flowable 7.1.0 所需的依赖。以下是一个完整的依赖配置示例：

<dependencies><!-- Spring Boot Starter Web --><dependency><groupId>org.springframework.boot</groupId><artifactId>spring-boot-starter-web</artifactId></dependency><!-- Spring Boot Starter Data JPA (可选，根据需要) --><dependency><groupId>org.springframework.boot</groupId><artifactId>spring-boot-starter-data-jpa</artifactId></dependency><!-- MySQL 驱动 --><dependency><groupId>com.mysql</groupId><artifactId>mysql-connector-j</artifactId><scope>runtime</scope></dependency><!-- Flowable Spring Boot Starter --><dependency><groupId>org.flowable</groupId><artifactId>flowable-spring-boot-starter</artifactId><version>${flowable.version}</version></dependency><!-- Spring Boot Starter Security (可选，根据需要) --><dependency><groupId>org.springframework.boot</groupId><artifactId>spring-boot-starter-security</artifactId></dependency><!-- Lombok (可选，简化代码) --><dependency><groupId>org.projectlombok</groupId><artifactId>lombok</artifactId><optional>true</optional></dependency><!-- 其他依赖根据需要添加 -->
</dependencies>

​​说明：​​

• ​​flowable-spring-boot-starter​​: 这是 Flowable 提供的 Spring Boot 启动器，包含了集成所需的核心依赖。
• ​​spring-boot-starter-security​​: 如果您的应用需要权限控制，可以添加此依赖。
• ​​Lombok​​: 可选，用于简化 Java 类的代码，如自动生成 Getter、Setter 等。

确保在 <properties> 中定义了 Flowable 和 Spring Boot 的版本：

<properties><java.version>21</java.version><spring-boot.version>3.4.1</spring-boot.version><flowable.version>7.1.0</flowable.version>
</properties>

五、配置数据库与 Flowable

1. 配置 application.yml

在 src/main/resources/application.yml 中配置数据源和 Flowable 相关参数。以下是一个基于 MySQL 的配置示例：

server:port: 8080spring:datasource:url: jdbc:mysql://localhost:3306/flowable_db?useUnicode=true&characterEncoding=utf8&serverTimezone=UTC&useSSL=false&allowPublicKeyRetrieval=trueusername: rootpassword: your_password  # 替换为您的 MySQL 密码driver-class-name: com.mysql.cj.jdbc.Drivertype: com.zaxxer.hikari.HikariDataSource  # 推荐使用 HikariCP 作为连接池jpa:hibernate:ddl-auto: none  # 根据需要配置，通常 Flowable 会自行管理其表show-sql: trueproperties:hibernate:dialect: org.hibernate.dialect.MySQLDialectflowable:async-executor-activate: false  # 开发阶段建议关闭异步执行器database-schema-update: true  # 启动时自动创建或更新数据库表，生产环境建议设置为 falsehistory-level: audit  # 历史记录级别，可选：none, activity, audit, full# process-definition-location-prefix: classpath:/processes/  # 流程定义文件存放路径，根据需要配置

​​配置说明：​​

• ​​server.port​​: 应用启动端口，可以根据需要修改。
• ​​spring.datasource​​: 配置 MySQL 数据源，确保数据库 flowable_db 已存在，或者 Flowable 能够自动创建（根据数据库权限）。
  • ​​url​​: 数据库连接地址，确保数据库名称（如 flowable_db）正确。
  • ​​username​​ 和 ​​password​​: 数据库用户名和密码。
  • ​​driver-class-name​​: MySQL JDBC 驱动类名。
  • ​​type​​: 推荐使用 HikariCP 作为连接池，性能更优。
• ​​spring.jpa​​: 配置 JPA 相关参数。
  • ​​hibernate.ddl-auto​​: 设置为 none，避免与 Flowable 的表管理冲突。Flowable 会自行管理其数据库表。
  • ​​show-sql​​: 设置为 true，方便调试时查看生成的 SQL 语句。
  • ​​properties.hibernate.dialect​​: 设置 Hibernate 方言为 MySQL。
• ​​flowable​​:
  • ​​async-executor-activate​​: 开发阶段建议设置为 false，避免不必要的异步任务。生产环境可根据需要启用。
  • ​​database-schema-update​​: 设置为 true，应用启动时会自动创建或更新 Flowable 所需的数据库表。​​生产环境强烈建议设置为 false，并通过数据库迁移工具（如 Flyway 或 Liquibase）管理数据库 schema。​​
  • ​​history-level​​: 设置历史记录级别，audit 级别会记录较详细的历史信息，根据需求可选择 none, activity, audit, full。
  • ​​process-definition-location-prefix​​: 如果您将 BPMN 流程定义文件存放在特定目录（如 classpath:/processes/），可以在此配置，Flowable 启动时会自动部署这些流程定义。

2. 数据库准备

确保您已经安装并运行了 MySQL 数据库，并创建了用于 Flowable 的数据库。例如，创建名为 flowable_db 的数据库：

CREATE DATABASE flowable_db CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;

​​注意：​​ 根据您的配置，确保数据库名称、用户名和密码与 application.yml 中的配置一致。

六、配置 Flowable

Spring Boot 与 Flowable 的集成主要通过自动配置完成，但您也可以根据需要进行自定义配置。

1. 自动配置

引入 flowable-spring-boot-starter 后，Spring Boot 会自动配置 Flowable 的核心 Bean，包括 ProcessEngine、RuntimeService、TaskService、RepositoryService、HistoryService 等。您无需手动配置这些 Bean，除非有特殊需求。

2. 自定义 Flowable 配置（可选）

如果需要自定义 Flowable 的配置，可以创建一个配置类实现 ProcessEngineConfigurationConfigurer 接口。例如，配置邮件服务器或自定义表单类型。

package com.example.flowabledemo.config;import org.flowable.common.engine.api.delegate.Expression;
import org.flowable.engine.ProcessEngineConfiguration;
import org.flowable.form.api.FormEngine;
import org.flowable.form.api.FormRepositoryService;
import org.flowable.form.api.FormService;
import org.flowable.mail.api.MailEngine;
import org.springframework.context.annotation.Configuration;
import org.flowable.spring.SpringProcessEngineConfiguration;
import org.springframework.context.annotation.Bean;import javax.sql.DataSource;
import java.util.ArrayList;
import java.util.List;@Configuration
public class FlowableConfig implements ProcessEngineConfigurationConfigurer {@Overridepublic void configure(SpringProcessEngineConfiguration configuration) {// 示例：配置邮件服务器（根据需要）/*configuration.setMailServerHost("smtp.example.com");configuration.setMailServerPort(587);configuration.setMailServerUsername("[e-mail]");configuration.setMailServerPassword("password");configuration.setMailServerDefaultFrom("[e-mail]");*/// 示例：配置自定义表单类型（根据需要）/*List<FormEngine> customFormEngines = new ArrayList<>();// 添加自定义 FormEngineconfiguration.setCustomFormEngines(customFormEngines);List<FormType> customFormTypes = new ArrayList<>();// 添加自定义 FormTypeconfiguration.setCustomFormTypes(customFormTypes);*/// 其他自定义配置}
}

​​说明：​​

• 通过实现 ProcessEngineConfigurationConfigurer 接口，您可以在 Flowable 初始化时自定义其配置。
• 上述示例中注释掉了邮件服务器和自定义表单类型的配置，您可以根据实际需求进行配置。

七、流程设计与部署

1. 使用 Flowable Modeler 设计流程

​​Flowable Modeler​​ 是 Flowable 提供的可视化流程设计工具，您可以通过它设计 BPMN 2.0 流程定义。

1.1 部署 Flowable Modeler

Flowable Modeler 通常作为一个独立的服务运行。您可以通过 Docker 快速部署 Flowable Modeler：

docker run -d -p 9096:8080 --name flowable-modeler \-e FLOWABLE_COMMON_APP_IDM-URL=http://localhost:8080/flowable-idm \-e FLOWABLE_COMMON_APP_IDM-REDIRECT-ON-ERROR=true \flowable/flowable-modeler:7.1.0

​​说明：​​

• 上述命令将 Flowable Modeler 部署在 http://localhost:9096。
• 您需要根据实际情况配置 IDM（身份管理）服务的 URL，如果使用独立的 Flowable IDM，确保其运行并配置正确。

​​注意：​​ 本教程重点在于 Spring Boot 与 Flowable 的集成，若您不需要使用 Flowable Modeler 的图形化设计功能，可以直接在项目中编写 BPMN 文件。

1.2 使用独立 Modeler 服务（可选）

如果您选择使用独立的 Flowable Modeler 服务，可以按照以下步骤操作：

1. ​​下载并部署 Flowable Modeler​​：

   • 访问 Flowable 官方 Docker 镜像 或 Flowable 官方文档 获取最新的 Modeler 镜像。
   • 使用 Docker 运行 Modeler，如上所示。

2. ​​配置跨域与数据库​​：

   • 确保 Modeler 服务与您的 Spring Boot 应用使用相同的数据库，或者根据需要进行配置。
   • 配置跨域支持，以便前端能够与后端服务通信。

​​注意：​​ 为了简化流程，本教程将重点放在直接在 Spring Boot 项目中管理和部署 BPMN 文件。

2. 在项目中管理 BPMN 文件

您可以直接在 Spring Boot 项目的 src/main/resources/processes 目录下存放 BPMN 2.0 文件，Flowable 启动时会自动部署这些流程定义。

2.1 创建流程目录

在 src/main/resources 下创建一个 processes 目录，用于存放 BPMN 文件。

src
└── main└── resources└── processes└── leave-process.bpmn20.xml

2.2 编写 BPMN 文件

以下是一个简单的请假流程 (leave-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/examples"><process id="leaveProcess" name="Leave Process" isExecutable="true"><startEvent id="startEvent" /><sequenceFlow id="flow1" sourceRef="startEvent" targetRef="approveTask" /><userTask id="approveTask" name="Approve Leave" flowable:assignee="${assignee}" /><sequenceFlow id="flow2" sourceRef="approveTask" targetRef="endEvent" /><endEvent id="endEvent" /></process></definitions>

​​说明：​​

• 这是一个非常简单的请假流程，包含一个开始事件、一个用户任务（审批任务）和一个结束事件。
• flowable:assignee="${assignee}" 表示任务的办理人通过流程变量 assignee 动态指定。

​​注意：​​ 您可以根据实际业务需求设计更复杂的流程，包括网关、多个任务、事件等。

八、创建 Spring Boot 应用主类

确保您的 Spring Boot 应用有一个主类，用于启动应用。例如：

package com.example.flowabledemo;import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;@SpringBootApplication
public class FlowableDemoApplication {public static void main(String[] args) {SpringApplication.run(FlowableDemoApplication.class, args);}
}

九、流程运行与操作

1. 自动部署流程

当您在 src/main/resources/processes 目录下放置 BPMN 文件并启动 Spring Boot 应用时，Flowable 会自动扫描并部署这些流程定义。

​​验证流程部署：​​

您可以通过访问 Flowable 提供的 REST API 或编写简单的测试控制器来验证流程是否已成功部署。

2. 编写流程操作控制器

为了与流程引擎交互，您可以编写一个 REST 控制器，提供启动流程、完成任务等接口。

2.1 添加依赖（如果尚未添加）

确保您的项目中包含 Spring Web 依赖，以支持 REST API。

2.2 创建流程服务类

首先，创建一个服务类，用于封装与 Flowable 引擎的交互逻辑。

package com.example.flowabledemo.service;import org.flowable.engine.RuntimeService;
import org.flowable.engine.TaskService;
import org.flowable.engine.runtime.ProcessInstance;
import org.flowable.task.api.Task;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.stereotype.Service;import java.util.HashMap;
import java.util.Map;@Service
public class FlowableService {@Autowiredprivate RuntimeService runtimeService;@Autowiredprivate TaskService taskService;/*** 启动流程实例* @param processDefinitionKey 流程定义 Key，对应 BPMN 中的 process id* @param variables 流程变量* @return 启动的流程实例 ID*/public String startProcess(String processDefinitionKey, Map<String, Object> variables) {ProcessInstance processInstance = runtimeService.startProcessInstanceByKey(processDefinitionKey, variables);return processInstance.getId();}/*** 查询用户的待办任务* @param assignee 办理人* @return 待办任务列表*/public List<Task> getTasksByAssignee(String assignee) {return taskService.createTaskQuery().taskAssignee(assignee).list();}/*** 完成任务* @param taskId 任务 ID* @param variables 任务变量*/public void completeTask(String taskId, Map<String, Object> variables) {taskService.complete(taskId, variables);}
}

2.3 创建 REST 控制器

接下来，创建一个 REST 控制器，暴露启动流程和完成任务的接口。

package com.example.flowabledemo.controller;import com.example.flowabledemo.service.FlowableService;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.web.bind.annotation.*;import java.util.HashMap;
import java.util.List;
import java.util.Map;@RestController
@RequestMapping("/api/flowable")
public class FlowableController {@Autowiredprivate FlowableService flowableService;/*** 启动请假流程* @param assignee 办理人* @return 流程实例 ID*/@PostMapping("/startLeaveProcess")public Map<String, String> startLeaveProcess(@RequestParam String assignee) {Map<String, Object> variables = new HashMap<>();variables.put("assignee", assignee);String processInstanceId = flowableService.startProcess("leaveProcess", variables);Map<String, String> response = new HashMap<>();response.put("processInstanceId", processInstanceId);return response;}/*** 获取指定办理人的待办任务* @param assignee 办理人* @return 待办任务列表*/@GetMapping("/tasks")public List<?> getTasks(@RequestParam String assignee) {return flowableService.getTasksByAssignee(assignee);}/*** 完成任务* @param taskId 任务 ID* @param approved 是否批准（示例变量）* @return 操作结果*/@PostMapping("/completeTask")public Map<String, String> completeTask(@RequestParam String taskId, @RequestParam boolean approved) {Map<String, Object> variables = new HashMap<>();variables.put("approved", approved);flowableService.completeTask(taskId, variables);Map<String, String> response = new HashMap<>();response.put("message", "任务已完成");return response;}
}

​​API 说明：​​

1. ​​启动请假流程​​

   • ​​URL​​: POST /api/flowable/startLeaveProcess?assignee=用户名
   • ​​描述​​: 启动一个请假流程实例，并指定任务的办理人。
   • ​​示例请求​​:

     curl -X POST "http://localhost:8080/api/flowable/startLeaveProcess?assignee=user1"

   • ​​响应​​:

     {"processInstanceId": "12345"
     }

2. ​​获取待办任务​​

   • ​​URL​​: GET /api/flowable/tasks?assignee=用户名
   • ​​描述​​: 查询指定办理人的待办任务列表。
   • ​​示例请求​​:

     curl "http://localhost:8080/api/flowable/tasks?assignee=user1"

   • ​​响应​​:

     [{"id": "task1","name": "Approve Leave","assignee": "user1","created": "...","dueDate": "...",...}
     ]

3. ​​完成任务​​

   • ​​URL​​: POST /api/flowable/completeTask?taskId=任务ID&approved=true|false
   • ​​描述​​: 完成指定的任务，并传递是否批准等变量。
   • ​​示例请求​​:

     curl -X POST "http://localhost:8080/api/flowable/completeTask?taskId=task1&approved=true"

   • ​​响应​​:

     {"message": "任务已完成"
     }

​​注意：​​

• 确保流程定义中的 process id（在 BPMN 文件中为 <process id="leaveProcess" ...>）与控制器中使用的 processDefinitionKey 一致。
• 根据实际业务需求，您可以扩展更多的流程操作，如查询流程实例、历史记录、任务表单等。

十、流程监控与历史记录

Flowable 提供了强大的历史记录和监控功能，您可以通过 HistoryService 查询历史流程实例、任务等信息。

1. 查询历史流程实例

您可以在服务类中添加方法，使用 HistoryService 查询历史记录。例如：

package com.example.flowabledemo.service;import org.flowable.engine.HistoryService;
import org.flowable.engine.history.HistoricProcessInstance;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.stereotype.Service;import java.util.List;@Service
public class HistoryService {@Autowiredprivate HistoryService historyService;/*** 查询历史流程实例* @param processInstanceBusinessKey 业务键* @return 历史流程实例列表*/public List<HistoricProcessInstance> getHistoricProcessInstancesByBusinessKey(String processInstanceBusinessKey) {return historyService.createHistoricProcessInstanceQuery().processInstanceBusinessKey(processInstanceBusinessKey).list();}
}

​​注意：​​ 您需要在启动流程时设置业务键，例如：

ProcessInstance processInstance = runtimeService.startProcessInstanceByKey("leaveProcess", processInstanceBusinessKey, variables);

然后在控制器中添加相应的接口，供前端或其他服务查询历史记录。

十一、生产环境最佳实践

在生产环境中，集成 Flowable 需要注意以下最佳实践，以确保系统的稳定性、安全性和性能。

1. 流程版本管理

随着业务需求的变化，流程定义可能需要不断迭代。Flowable 支持流程版本管理，确保新旧版本的流程定义能够共存，并根据需要启动不同版本的流程实例。

​​操作步骤：​​

1. ​​部署新版本流程​​：每次更新 BPMN 文件后，将其重新部署，Flowable 会自动为新的流程定义分配一个新的版本号。
2. ​​保留历史版本​​：通过配置，Flowable 会保留所有历史版本的流程定义，您可以根据需要启动特定版本的流程实例。

​​示例：​​

将更新后的 leave-process-v2.bpmn20.xml 文件放置在 src/main/resources/processes 目录下，启动应用后，Flowable 会自动部署新版本，并为其分配新的版本号。

2. 表单集成方案

Flowable 支持内嵌表单和外置表单两种方式，根据业务需求选择合适的表单集成方案。

• ​​内嵌表单​​：在 BPMN 文件中通过 flowable:formField 定义表单字段，通过 TaskService.getTaskFormData() 获取表单元数据。
• ​​外置表单​​：使用 Flowable Form 引擎，支持 HTML/CSS/JavaScript 自定义表单，提供更灵活的用户界面。

​​推荐：​​ 对于复杂表单需求，推荐使用外置表单，以实现更高的自定义程度和用户体验。

3. 监控与审计

通过 Flowable 提供的 HistoryService 和 ManagementService，您可以实现流程的全面监控与审计。

• ​​查询流程执行历史​​：了解流程实例的执行情况、任务处理情况等。
• ​​审计日志​​：记录关键操作和流程变更，确保流程的透明性和可追溯性。

​​示例：​​

List<HistoricProcessInstance> instances = historyService.createHistoricProcessInstanceQuery().processInstanceBusinessKey("process_123").list();

4. 安全加固

确保 Flowable 集成系统的安全性，防止未经授权的访问和潜在的安全漏洞。

• ​​权限控制​​：通过 Spring Security 或其他安全框架，限制对 Flowable API 的访问，确保只有授权用户才能启动、处理流程。
• ​​流程变量加密​​：对敏感的流程变量进行加密存储，保护用户数据的隐私。
• ​​防 SQL 注入​​：使用 MyBatis 的 #{} 占位符或 JPA 的参数绑定，避免用户输入直接拼接到 SQL 语句中，防止 SQL 注入攻击。

十二、性能优化

为了确保 Flowable 在生产环境中的高效运行，您可以采取以下性能优化措施：

1. 数据库索引优化

为常用的查询字段添加数据库索引，提高查询性能。例如，为 ACT_RU_TASK 表中的 ASSIGNEE_ 字段添加索引。

​​示例：​​

Flowable 通常会自动管理其数据库表的索引，但您可以根据具体查询需求，手动创建额外的索引。

// 通常不需要手动创建索引，Flowable 自动管理
// 但在特定情况下，您可以通过 ManagementService 执行自定义 SQL

​​注意：​​ 生产环境中，建议通过数据库管理员或使用数据库迁移工具管理索引，确保索引的有效性和性能。