Flowable-Engine表单引擎详解：动态表单设计与数据处理

Flowable-Engine作为轻量级工作流与业务流程管理（BPM）平台，其表单引擎模块提供了灵活的动态表单设计与数据处理能力。本文将从核心架构、表单定义、数据流转到实际应用场景，全面解析Flowable表单引擎的技术实现与使用方法。

表单引擎核心架构

Flowable表单引擎采用分层设计，主要包含API层、模型层和服务层三个核心部分：

• API层：提供表单定义、部署和实例管理的标准化接口，主要接口定义在modules/flowable-form-api/src/main/java/org/flowable/form/api/FormRepositoryService.java和modules/flowable-form-api/src/main/java/org/flowable/form/api/FormService.java中。

• 模型层：定义表单数据结构，包括表单模型（FormModel）、表单字段（FormField）等核心实体，如modules/flowable-form-model/src/main/java/org/flowable/form/model/FormField.java中定义了基础表单字段的属性。

• 服务层：实现表单部署、数据验证、实例管理等业务逻辑，通过modules/flowable-form-api/src/main/java/org/flowable/form/api/FormInfo.java关联表单定义与模型数据。

核心类关系

classDiagram
    class FormRepositoryService {
        +createDeployment() FormDeploymentBuilder
        +getFormModelById(String) FormInfo
        +getFormModelByKey(String) FormInfo
    }
    
    class FormService {
        +validateFormFields(FormInfo, Map) void
        +getVariablesFromFormSubmission(FormInfo, Map) Map
        +createFormInstance(Map, FormInfo) FormInstance
    }
    
    class FormInfo {
        -String id
        -String key
        -FormModel formModel
        +getFormModel() FormModel
    }
    
    class FormModel {
        <<interface>>
    }
    
    class SimpleFormModel {
        -List<FormField> fields
        +getFields() List<FormField>
    }
    
    class FormField {
        -String id
        -String type
        -Object value
        -boolean required
        -Map<String, Object> params
    }
    
    FormRepositoryService --> FormInfo
    FormService --> FormInfo
    FormInfo --> FormModel
    FormModel <|-- SimpleFormModel
    SimpleFormModel "1" --> "*" FormField

动态表单定义模型

FormField核心属性

表单字段是表单设计的基础单元，在FormField类中定义了以下核心属性：

属性名	类型	描述
id	String	字段唯一标识
name	String	显示名称
type	String	字段类型（文本、数字、下拉等）
value	Object	默认值
required	boolean	是否必填
readOnly	boolean	是否只读
params	Map<String, Object>	扩展参数（如最大长度、正则表达式等）

这些属性在modules/flowable-form-model/src/main/java/org/flowable/form/model/FormField.java中定义，支持通过params字段扩展自定义属性。

字段类型体系

Flowable表单引擎支持多种字段类型，通过type属性区分，主要包括：

• 基础类型：文本（text）、数字（number）、日期（date）、布尔值（boolean）
• 选择类型：下拉框（dropdown）、单选框（radio）、复选框（checkbox），对应modules/flowable-form-model/src/main/java/org/flowable/form/model/OptionFormField.java
• 容器类型：表格（table）、分组（group），对应modules/flowable-form-model/src/main/java/org/flowable/form/model/FormContainer.java
• 动态类型：表达式字段（expression），支持流程变量动态计算，定义在modules/flowable-form-model/src/main/java/org/flowable/form/model/ExpressionFormField.java

表单定义示例

以下是一个包含文本框、下拉框和容器的表单定义JSON示例：

{
  "id": "leave-application-form",
  "name": "请假申请表",
  "key": "leaveApplication",
  "version": 1,
  "fields": [
    {
      "id": "employeeName",
      "name": "员工姓名",
      "type": "text",
      "required": true,
      "readOnly": false
    },
    {
      "id": "leaveType",
      "name": "请假类型",
      "type": "dropdown",
      "required": true,
      "params": {
        "options": [
          {"id": "annual", "name": "年假"},
          {"id": "sick", "name": "病假"},
          {"id": "personal", "name": "事假"}
        ]
      }
    },
    {
      "id": "dateRange",
      "name": "请假时间",
      "type": "container",
      "fields": [
        [
          {
            "id": "startDate",
            "name": "开始日期",
            "type": "date",
            "required": true
          },
          {
            "id": "endDate",
            "name": "结束日期",
            "type": "date",
            "required": true
          }
        ]
      ]
    }
  ]
}

表单数据处理流程

表单部署与版本管理

通过FormRepositoryService实现表单定义的部署与版本控制：

// 部署表单定义
FormDeployment deployment = formRepositoryService.createDeployment()
    .name("请假申请表单")
    .addClasspathResource("forms/leave-application.form")
    .deploy();

// 获取最新版本表单定义
FormInfo formInfo = formRepositoryService.getFormModelByKey("leaveApplication");

部署操作会将表单定义存储到Flowable的部署表中，支持通过版本号和租户ID进行多版本管理。

数据验证机制

FormService提供了表单提交前的数据验证功能，通过modules/flowable-form-api/src/main/java/org/flowable/form/api/FormService.java中的validateFormFields方法实现：

// 表单数据验证
Map<String, Object> submittedData = new HashMap<>();
submittedData.put("employeeName", "张三");
submittedData.put("leaveType", "annual");

formService.validateFormFields(formInfo, submittedData);

验证规则包括：

• 必填字段校验（required属性）
• 数据类型校验（type属性）
• 自定义正则表达式校验（通过params中的pattern参数定义）

表单实例创建与数据流转

表单提交后，通过FormService创建表单实例并转换为流程变量：

// 创建表单实例
FormInstance formInstance = formService.createFormInstance(
    submittedData, 
    formInfo, 
    taskId, 
    processInstanceId, 
    processDefinitionId,
    tenantId,
    "submit"
);

// 转换为流程变量
Map<String, Object> processVariables = formService.getVariablesFromFormSubmission(
    formInfo, 
    submittedData, 
    "submit"
);

创建的表单实例包含完整的提交数据，可通过modules/flowable-form-api/src/main/java/org/flowable/form/api/FormService.java中的getFormInstanceModelById方法查询历史数据。

高级特性与扩展

动态字段权限控制

通过FormField的readOnly属性和FormFieldHandler接口实现动态权限控制：

public class CustomFormFieldHandler implements FormFieldHandler {
    @Override
    public void enrichFormFields(FormInfo formInfo) {
        SimpleFormModel formModel = (SimpleFormModel) formInfo.getFormModel();
        for (FormField field : formModel.getFields()) {
            // 根据当前用户角色设置字段只读属性
            if ("salary".equals(field.getId()) && !SecurityUtils.getCurrentUser().hasRole("HR")) {
                field.setReadOnly(true);
            }
        }
    }
}

表达式字段应用

ExpressionFormField支持使用Flowable表达式动态计算字段值，例如根据开始日期和结束日期自动计算请假天数：

{
  "id": "leaveDays",
  "name": "请假天数",
  "type": "expression",
  "expression": "${(endDate - startDate).days + 1}",
  "readOnly": true
}

多租户表单管理

通过FormRepositoryService的租户隔离方法实现多租户表单管理：

// 获取租户专属表单定义
FormInfo tenantFormInfo = formRepositoryService.getFormModelByKey(
    "leaveApplication", 
    "tenant123", 
    true // 当租户表单不存在时是否回退到默认租户
);

实际应用场景

流程驱动的动态表单

在请假流程中，根据请假类型动态显示不同字段：

• 年假：显示剩余年假天数（通过表达式字段计算）
• 病假：显示医院证明上传字段（文件类型）

实现方式是在流程中通过表单字段的visibility属性动态控制，或通过FormFieldHandler接口动态修改表单结构。

表单数据版本追溯

Flowable表单引擎自动记录表单实例的创建和修改历史，可通过以下代码查询某流程实例关联的所有表单数据：

List<FormInstance> instances = formService.createFormInstanceQuery()
    .processInstanceId(processInstanceId)
    .orderByCreateTime()
    .asc()
    .list();

每个表单实例包含完整的提交数据和操作时间，支持审计和追溯需求。

总结与最佳实践

Flowable表单引擎通过灵活的模型设计和完善的服务接口，为BPM应用提供了强大的动态表单能力。在实际使用中，建议：

1. 表单设计：基础字段使用内置类型，复杂场景通过FormContainer组合布局
2. 性能优化：高频访问的表单定义使用缓存，避免重复部署
3. 权限控制：通过FormFieldHandler实现数据级权限控制
4. 版本管理：重大变更使用新的表单key，避免版本冲突
5. 数据安全：敏感字段通过自定义参数加密存储

更多表单引擎的高级用法可参考官方文档docs/docusaurus/docs/和示例项目modules/flowable-spring-boot/flowable-spring-boot-samples/。