Flowable 自定义属性实战：从UI配置到后端解析全流程指南

最新推荐文章于 2026-05-17 06:50:04 发布

原创

最新推荐文章于 2026-05-17 06:50:04 发布 · 1k 阅读

标签

#Flowable #工作流引擎 #自定义属性 #BPMN

1. 为什么我们需要自定义Flowable属性？

如果你用过Flowable的工作流设计器，肯定遇到过这样的场景：一个用户任务节点，除了基本的“办理人”、“任务名称”这些标准属性，你还想给它加上点“私货”。比如，这个任务允许撤回吗？有没有办理期限？超时了怎么处理？能不能上传附件？这些业务逻辑千变万化，Flowable自带的属性面板根本不够用。

这时候，自定义属性就派上用场了。它就像给你的工作流节点“打标签”或者“挂装备”，把业务特有的规则和数据，直接绑定到流程定义里。这样一来，流程引擎在运行时就能直接读取这些配置，驱动你的业务逻辑，而不是把规则硬编码在代码里。我做过不少项目，从简单的审批流到复杂的工单系统，自定义属性几乎是标配。它能极大地提升流程的灵活性和可配置性，让业务人员也能通过拖拽设计器，直观地配置复杂规则。

但说实话，第一次搞这个的时候，我也踩了不少坑。Flowable的官方文档对这块讲得比较分散，前端怎么加、后端怎么解析、数据怎么流转，得自己一点点摸索。网上能找到的教程要么太旧，要么只讲了一半。所以，今天我就把自己趟过的路，从UI设计器配置到后端Java代码解析，整个流程掰开揉碎了讲给你听。只要你跟着步骤走，保证你能顺利给自己的Flowable加上想要的任何属性。

2. 动手之前：环境与源码准备

工欲善其事，必先利其器。咱们这个实战是基于Flowable 6.8.0版本的源码进行修改的。为什么一定要用源码？因为我们需要修改它的前端配置文件和后端转换逻辑，打包好的jar包可没法改。

第一步，先把源码搞到手。 最直接的方法就是从GitHub上拉取对应版本的分支。打开命令行，执行下面的命令：

git clone -b flowable-release-6.8.0 https://github.com/flowable/flowable-engine.git

这一步如果网络慢，可能需要点耐心。拉取成功后，你就得到了一个完整的Flowable引擎项目，里面包含了我们需要的所有模块。

第二步，把项目跑起来。 重点是启动 flowable-ui 这个模块，它是官方提供的建模器（Modeler）Web应用。进入项目根目录，找到 flowable-ui 模块。因为项目是Maven构建的，你需要确保本地安装了Maven（建议3.6以上版本）和JDK 8或11。

编译并启动的方式有很多，我习惯用Spring Boot的方式直接运行。找到 flowable-ui-modeler 模块下的主启动类 org.flowable.ui.modeler.Application，在IDE里直接运行它就行。第一次启动会下载很多依赖，并且会初始化H2内存数据库，稍等片刻，看到控制台输出类似“Started Application in X seconds”的日志，就成功了。

然后打开浏览器，访问 http://localhost:8080/flowable-ui，默认账号密码是 admin/test。如果能成功登录并看到流程设计器界面，恭喜你，基础环境已经OK了。

这里有个小提示：如果你在编译或启动过程中遇到奇奇怪怪的错误，比如某个依赖下载失败，大概率是网络问题。可以检查一下Maven的settings.xml文件，配置一个速度快点的国内镜像源，比如阿里云的Maven仓库，能省下不少等待时间。

3. 前端改造：在设计器里添加新属性

Flowable的设计器属性配置，核心都在一个叫 stencilset_bpmn.json 的文件里。这个文件可以理解为设计器的“元件库”和“属性面板”的蓝图。它定义了界面上有哪些图形（比如用户任务、网关），以及每个图形可以配置哪些属性。

这个文件的位置在：flowable-engine/modules/flowable-ui/flowable-ui-modeler-logic/src/main/resources/stencilset_bpmn.json。用你顺手的编辑器打开它，我们会发现它的结构非常清晰。

3.1 理解JSON配置文件的结构

文件最外层主要有几个部分：

propertyPackages: 这里定义的是属性包。你可以把它想象成工具箱里的一个个工具抽屉。每个“抽屉”（属性包）里放着同一类或相关的属性项。比如，有一个抽屉专门放“基本属性”（ID、名称），另一个抽屉放“监听器属性”。
stencils: 这里定义的是图形元素，比如“用户任务”、“服务任务”。每个图形元素通过 propertyPackages 字段，来引用上面定义好的那些“工具抽屉”。这样，用户任务就可以展示“基本属性”抽屉和“监听器属性”抽屉里的内容。

举个例子，我们想给“用户任务”添加一个“是否允许催办”的开关属性。这属于业务规则，Flowable本身没有，就需要我们自定义。

3.2 添加一个布尔类型（开关）属性

首先，我们在 propertyPackages 数组里新增一个属性包。找到 propertyPackages 的结束位置，在最后一个已有的属性包后面，加上一个逗号，然后添加我们的新包：

{
  "name": "custombusinesspackage",
  "properties": [{
    "id": "allowurging",
    "type": "Boolean",
    "title": "允许催办",
    "value": false,
    "description": "是否允许对该任务进行催办操作",
    "popular": true
  }]
}

我来解释一下这几个关键字段：

name: 属性包的名字，自己起个有意义的，比如 custombusinesspackage。
id: 属性的唯一标识符，非常重要！后端解析就靠它来匹配。这里我们用 allowurging。
type: 属性类型。Boolean 对应一个复选框（开关）。其他常见类型还有 String（单行文本）、Text（多行文本）。
title: 显示在属性面板上的标签文字，我们写“允许催办”。
value: 属性的默认值，布尔类型就是 true 或 false。
popular: 设为 true，这个属性会出现在属性面板的“常用”栏里，更方便找到。

属性包定义好了，还得把它“分配”给用户任务图形。在 stencils 数组里，找到 id 为 "UserTask" 的那个对象。它里面有一个 propertyPackages 数组，列出了用户任务拥有的所有属性包。我们只需要把刚创建的 custombusinesspackage 加到这个数组里就行。

修改后，用户任务的配置大概会变成这样：

{
  "type": "node",
  "id": "UserTask",
  "title": "用户活动",
  ...
  "propertyPackages": [
    "overrideidpackage",
    "namepackage",
    // ... 其他很多原有的包
    "custombusinesspackage" // 把我们新增的包加到这里
  ],
  ...
}

保存文件，重启你的 flowable-ui