flowable-engine 使用手册

📄字数 6.7K

👁️阅读量 加载中...

本文将介绍在 spring-boot-web 应用中如何使用 flowable-engine v6.7.2-xugu 连接 XuguDB，并测试在虚谷数据库部署 BPMN 模型、开启、处理流程实例等功能，以及UI组件功能介绍。

框架名称	适配起始版本	官网地址	源框架下载地址	XuguDB框架下载	demo程序地址
flowable-engine	6.7.2	flowable官网	flowable源码	版本发布	xugu-flowable

提示

其他支持版本可详见版本发布列表

一、使用说明

1.1 下载 flowable 虚谷适配源码

虚谷对 flowable 的下载方式有两种，通过 git 命令和 github 下载功能。

1.1.1 方式一：克隆 flowable 代码到本地

1. 访问虚谷数据库开放源代码仓库，使用命令 git clone <repository-url> 通过 HTTPS 或者 SSH 克隆到本地。

   图 1.1 flowable仓库克隆地址

2. 使用命令 git branch -r --list '*-xugu' 列出已适配版本分支，再使用命令切换分支到所需版本。

   图 1.2 本地分支切换

1.1.2 方式二：下载 flowable 代码到本地

1. 访问虚谷数据库开放源代码仓库，选择所需版本分支。

   图 1.3 flowable仓库分支选择

2. 直接下载当前分支源码（本地未安装 Git）。

   图 1.4 flowable分支代码下载

1.2 安装 flowable 到本地 Maven 仓库

注意

flowable 模块较多，建议使用 Maven 将源码安装到本地仓库

1. 推荐使用 jdk 8 和 Maven 3.6.x 运行环境。

   图 1.5 Java环境检查

2. 使用项目中 Maven 脚本 scripts/build-all.sh 安装 flowable-engine 到本地仓库，出现 BUILD SUCCESS 即安装成功。

   图 1.6 flowable脚本安装

3. 进入目录 modules/flowable-ui 使用 Maven 命令 mvn clean install -DskipTests 安装 flowable-ui 到本地仓库。

   图 1.7 flowable-ui命令安装

1.3 下载/安装 liquibase 虚谷适配源码

1. 通过 flowable 源码中 pom.xml 找到依赖的 liquibase 版本。

   图 1.8 flowable依赖的liquibase版本

2. 下载/安装 liquibase 步骤详情，请参考liquibase 使用手册。

二、连接示例

2.1 前提条件

• 计算机已安装 JDK 1.8 和 Maven。
• 计算机已安装 IntelliJ IDEA。
• 计算机已安装 DBManager 或者 xgconsole。
• 计算机已安装 Apifox 或者 postman
• 计算机已部署 XuguDB 12.0.0 或有能连接访问的虚谷数据库实例。

提示

1. 本文档示例程序运行使用的软件为IntelliJ IDEA 2025.1.2 (Community Edition)，也可以按照自己的喜好选择其它开发工具运行此示例程序。
2. 本文档演示说明中使用 Apifox 发起 HTTP 请求进行测试，也可以按照自己的喜好选择其它发起 HTTP 请求的方式。

2.2 操作步骤

• 导入 xugu-flowable 项目到 IDEA 中。
• 修改 xugu-flowable 项目中数据库连接信息。
• 运行 xugu-flowable 项目。

提示

本文是在Windows环境中进行操作说明的，若使用的是其它操作环境，那么与本文中的步骤可能存在不同。

2.2.1 导入 xugu-flowable 项目到 IDEA

1. 参考 IntelliJ IDEA 官方文档，导入项目。

   1. 启动 IntelliJ IDEA。 如果欢迎屏幕打开，请选择左侧栏目中项目（Projects）-> 右侧选项打开（Open）。 否则，请转到左上角主菜单的 文件（File）-> 打开（Open）。
   2. 在打开的对话框中，选择下载的源代码、库目录下的二级目录 xugu-flowable6.7.2，然后点击 Select Folder 打开。

2. 项目结构设置

   1. 更改项目 SDK 设置：参考 SDK | IntelliJ IDEA 文档，请点击右上角工具栏上的齿轮⚙设置按钮并选择项目结构按钮（Project Structure...）。 或者，前往 文件（File）-> 项目结构（Project Structure...） 或按 Ctrl+Alt+Shift+S。

      图 2.1 xugu-flowable项目JDK设置

   2. 项目 Maven 设置：参考 Maven | IntelliJ IDEA 文档，文件 -> 设置 -> 构建、执行、部署 -> 构建工具 -> Maven。

      图 2.2 xugu-flowable项目Maven设置

3. liquibase 需要使用适配虚谷版，请在示例项目根目录中执行以下命令：

   mvn install:install-file -Dfile=./lib/liquibase-core-4.5.0-xugu.jar -DgroupId=org.liquibase -DartifactId=liquibase-core -Dversion=4.5.0-xugu -Dpackaging=jar

提示

已执行过步骤 1.3 不再需要执行此步骤

2.2.2 修改 xugu-flowable 项目中数据库连接信息

1. 执行示例项目中 xugu-flowable6.7.2/sql 目录中 createDatabase.sql，创建数据库。

   -- 在SYSTEM下执行
   CREATE DATABASE `flowable` CHARACTER SET 'utf8_bin' TIME ZONE 'GMT+08:00';
   
   use flowable;
   CREATE USER `flowable` IDENTIFIED BY 'flowable';
   GRANT DBA IN SCHEMA `flowable` TO `flowable`;

2. 修改 xugu-flowable6.7.2/src/main/resources/application.yml 文件中的数据库连接信息。

   图 2.3 xugu-flowable配置详情

• 示例代码

  server:
    # 程序的 HTTP 服务器监听的端口号
    port: 8080
  spring:
    jackson:
      ### ui-modeler保存会报错
      #    date-format: yyyy-MM-dd HH:mm:ss
      # 时区
      time-zone: Asia/Shanghai
    datasource:
      # 数据库url连接
      url: jdbc:xugu://127.0.0.1:5138/flowable
      # 数据库用户名
      username: flowable
      # 数据库密码
      password: flowable
      # 数据库驱动类名
      driver-class-name: com.xugu.cloudjdbc.Driver
      # 数据库连接池类名称
      type: com.alibaba.druid.pool.DruidDataSource
      druid:
        # 初始化连接池大小
        initialSize: 5
        # 最小连接数
        minIdle: 10
        # 最大连接数
        maxActive: 20
        # 获取连接时的最大等待时间,超过该时间则抛出异常
        maxWait: 6000
        # 间隔多久才进行一次检测，检测需要关闭的空闲连接
        time-between-eviction-runs-millis: 2000
        # 连接在被清理前的最小空闲时间
        # 如果此时minEvictableIdleTimeMillis还没有赋值，则使用默认值1800000
        min-evictable-idle-time-millis: 600000
        max-evictable-idle-time-millis: 1800000
        # 心跳检测语句
        validationQuery: SELECT 1
        testWhileIdle: true
        # 申请连接时执行validationQuery检测连接是否有效，默认true，开启后会降低性能
        testOnBorrow: false
        # 归还连接时执行validationQuery检测连接是否有效，默认false，开启后会降低性能
        testOnReturn: false
        keep-alive: true
  flowable:
    ### 设置为 false，禁用 /resources/processes 自动部署 BPMN XML 流程
    check-process-definitions: false
    ### full：保存历史数据的最高级别，可保存全部流程相关细节，包括流程流转各节点参数
    history-level: full
    ### 关闭定时任务JOB
    async-executor-activate: false
    ### 自动更新数据库版本
    database-schema-update: true

提示

官方文档链接：Flowable 应用程序属性

2.2.3 pom.xml 依赖检查

1. 检查项目依赖中是否引入了 flowable 与 liquibase，以及虚谷数据库的 JDBC 驱动。

   图 2.4 xugu-flowable依赖设置

2. 若使用 flowable-ui 组件，需引入虚谷版本。

   图 2.5 xugu-flowable依赖引入ui组件

3. 重新加载/刷新 Maven 项目，无报错即引入依赖成功

   图 2.6 xugu-flowable项目重新加载测试

2.2.4 运行 xugu-flowable 项目

2.2.4.1 运行路径

1. 在项目路径 xugu-flowable6.7.2/src/main/java/com/xugu/FlowableDemoApplication.java 中运行主启动类。

2. 第一次运行，在数据库创建表结构需要等待一段时间。待完全启动后访问本地webapp监控页面，默认用户名admin，密码test。

   图 2.7 xugu-flowable运行路径
   图 2.8 flowable-ui登录界面

3. 测试方法存放于 xugu-flowable6.7.2/src/main/java/com/xugu/controller/ExpenseProcessController.java 目录文件中，通过 HTTP 请求调用。

   图 2.9 xugu-flowable测试入口

4. 按照 ExpenseProcessController.java 中注释信息引导，依次测试流程部署、流程实例创建、任务查询与完成等。

2.2.4.2 Flowable 引擎调用方式

1. 程序中直接调用 Java API

   1. 通过 Post 请求接口http://localhost:8080/expense-process/deploy 调用 com.xugu.controller.ExpenseProcessController#uploadAndDeployment(org.springframework.web.multipart.MultipartFile, javax.servlet.http.HttpServletRequest) 方法上传 BPMN 并部署。

      提示

      官方文档链接：BPMN 2.0 简介
      官方文档链接：BPMN 2.0 结构

      图 2.10 xugu-flowable流程文件
      图 2.11 使用Apifox测试xugu-flowable流程部署

   2. 通过 GET 请求接口http://localhost:8080/expense-process/start-process-instance-by-key 调用 com.xugu.controller.ExpenseProcessController#testStartProcess(java.lang.String, java.lang.Integer, java.lang.String) 方法开启流程实例。

      图 2.12 使用Apifox测试xugu-flowable创建流程实例

   3. 通过 Get 请求接口http://localhost:8080/expense-process/list-task 调用 com.xugu.controller.ExpenseProcessController#list 方法查询任务列表。

      图 2.13 使用Apifox测试xugu-flowable查询任务列表

   4. 通过 Get 请求接口http://localhost:8080/expense-process/apply 调用 com.xugu.controller.ExpenseProcessController#apply 方法批准任务。
      参数money > 500，流程到达老板审批，日志打印相关监听信息：

      2025-07-08 16:07:34.742  INFO 14460 --- [nio-8080-exec-3] com.xugu.listener.BossTaskListener       : 任务创建：name=老板审批,id=9ad55ff8-5bd2-11f0-864c-005056c00001

      图 2.14 使用Apifox测试xugu-flowable通过任务

   5. 重复步骤3，查询任务列表。

      图 2.15 使用Apifox测试xugu-flowable再次查询任务列表

   6. 重复步骤4，批准任务。老板审批通过，日志打印相关监听信息：

      2025-07-08 16:07:34.742  INFO 14460 --- [nio-8080-exec-3] com.xugu.listener.BossTaskListener       : 任务创建：name=老板审批,id=9ad55ff8-5bd2-11f0-864c-005056c00001
      2025-07-08 16:11:05.299  INFO 14460 --- [nio-8080-exec-7] com.xugu.listener.BossTaskListener       : 任务完成：9ad55ff8-5bd2-11f0-864c-005056c00001
      2025-07-08 16:11:05.300  INFO 14460 --- [nio-8080-exec-7] com.xugu.listener.BossTaskListener       : 任务被删除：9ad55ff8-5bd2-11f0-864c-005056c00001

      图 2.16 使用Apifox测试xugu-flowable通过任务节点老板审批

2. 原生 REST API 接口调用

   提示

   官网文档参考：

   v6 REST API 文档

   v5.23.0 REST API 文档

   1. 查询流程部署：GET 请求 http://admin:test@localhost:8080/process-api/repository/deployments

      图 2.17 使用Apifox测试原生REST-API查询流程

   2. 根据 id 删除部署：DELETE 请求 http://admin:test@localhost:8080/process-api/repository/deployments/7432c1b2-5bca-11f0-bce3-005056c00001。

      图 2.18 使用Apifox测试原生REST-API删除流程

   3. 再次查询流程部署：GET 请求 http://admin:test@localhost:8080/process-api/repository/deployments。

      图 2.19 使用Apifox测试原生REST-API查询流程结果为空

   4. 创建新部署：POST 请求 http://admin:test@localhost:8080/process-api/repository/deployments

      图 2.20 使用Apifox测试原生REST-API部署流程

   5. 获取流程定义列表：GET 请求 http://admin:test@localhost:8080/process-api/repository/process-definitions

      图 2.21 使用Apifox测试原生REST-API获取流程定义

   6. 按流程定义 id 启动流程实例：POST 请求 http://admin:test@localhost:8080/process-api/runtime/process-instances

      图 2.22 使用Apifox测试原生REST-API启动流程实例

   7. 任务列表：GET 请求 http://admin:test@localhost:8080/process-api/runtime/tasks

      图 2.23 使用Apifox测试原生REST-API查询任务列表

   8. 任务操作：POST 请求 http://admin:test@localhost:8080/process-api/runtime/tasks/343a3102-5bcc-11f0-bce3-005056c00001

      图 2.24 使用Apifox测试原生REST-API操作任务

3. Flowable-UI 使用

   1. 请求地址： http://localhost:8080/#/ (默认用户名admin,密码test)
      • 任务应用程序：http://localhost:8080/workflow/#/tasks
      • 建模应用程序：http://localhost:8080/modeler/#/processes
      • 管理员应用程序：http://localhost:8080/admin/#/engine
      • 身份管理应用程序：http://localhost:8080/idm/#/user-mgmt
   2. 通过 UI 界面进行流程建模、任务管理和流程监控，可以直观地与 Flowable 引擎进行交互，管理业务流程。
   图 2.25 flowable-ui查看已部署的流程
   图 2.26 flowable-ui查看流程实例

提示

flowable-7.0.1 及以上版本项目中无 ui 模块，使用 v6.8.1 的 ui 组件部分功能可能不兼容

三、常见问题&解决办法

1. 启动报错：相关表不存在，但是又不自动创建表

   • 排查数据库中其它 schema 下是否已存在 Flowable 相关表结构，当前用户是否有权限检索到。
   • 应用使用的数据库用户 spring.datasource.username 确保只在当前 schema 下检索到 Flowable 相关表结构。
   图 3.1 flowable 启动报错：相关表不存在

2. Flowable 引擎使用 Liquibase 来管理数据库表结构的版本控制，必须配合 liquibase-core 虚谷版本使用，且需手动指定版本来区别 spring-boot 中自动引入的版本。