流程变量表

引用文件

本文档引用的文件

简介

本文件围绕流程变量表(bpm_process_variable)进行深入解析，系统阐述流程变量在工作流中的关键作用、字段设计考量、生命周期管理策略、作用域划分（流程实例级与任务级）、在表达式计算与条件判断中的应用方式，以及最佳实践与常见陷阱。通过对代码库中实际实现的分析，帮助读者建立对流程变量从概念到落地的完整认知。

项目结构

与流程变量直接相关的核心文件分布如下：

数据库脚本：包含流程相关表结构定义，为流程变量的持久化提供基础
枚举常量：集中定义流程实例与任务级别的变量键名，确保全局一致性
表达式与工具类：提供变量类型转换、表达式求值、变量查询等能力
服务实现：封装流程变量的创建、更新、删除与查询逻辑

Mermaid Diagram Code:

graph TB
subgraph "数据库层"
BPM["bpm.sql<br/>流程相关表结构"]
end
subgraph "枚举常量"
BV["BpmnVariableConstants<br/>流程变量键名"]
AV["ApiVariableConstants<br/>业务变量键名"]
end
subgraph "表达式与工具"
VC["VariableConvertByTypeExpressionFunction<br/>变量类型转换函数"]
FU["FlowableUtils<br/>表达式求值与过滤"]
QU["QueryUtils<br/>变量查询工具"]
end
subgraph "服务实现"
PI["BpmProcessInstanceServiceImpl<br/>流程实例变量管理"]
TS["BpmTaskServiceImpl<br/>任务变量管理"]
end
BPM --> PI
BV --> PI
AV --> BV
VC --> FU
FU --> PI
QU --> PI
PI --> TS

图表来源

章节来源

核心组件

流程变量键名常量：统一管理流程实例与任务级别的变量键，保证跨模块一致性和可维护性
表达式与类型转换：支持在表达式中按变量类型进行安全转换，提升条件判断的可靠性
变量查询工具：提供运行中与历史流程变量的统一查询接口
服务实现：封装变量的增删改查、状态同步与事件触发逻辑

章节来源

架构概览

流程变量贯穿于流程的创建、执行、查询与销毁全过程，形成“键名规范—表达式求值—持久化—查询—事件”的闭环。

Mermaid Diagram Code:

sequenceDiagram
participant Caller as "调用方"
participant PI as "流程实例服务"
participant RT as "RuntimeService"
participant EV as "事件发布"
participant HIS as "HistoryService"
Caller->>PI : 创建/更新流程变量
PI->>RT : setVariables/setVariable/removeVariables
PI->>EV : 流程完成后状态事件
Caller->>PI : 查询流程变量
PI->>RT : getVariables(运行中)
PI->>HIS : getVariables(历史)
HIS-->>PI : 返回历史变量
PI-->>Caller : 返回变量集合

图表来源

详细组件分析

流程变量键名常量体系

流程实例变量：状态、理由、发起用户ID、跳过表达式开关、是否跳过发起人节点、流程开始时间、流程定义名称等
任务变量：状态、理由、签名图片URL、操作记录等
业务变量：规则业务信息、业务更新主要原因等

这些键名统一定义在常量类中，便于全局引用与版本演进。

Mermaid Diagram Code:

classDiagram
class ApiVariableConstants {
+PROCESS_INSTANCE_RULE_BUSINESS_INFO
+PROCESS_INSTANCE_VARIABLE_BUSINESS_UPDATE_TYPE
}
class BpmnVariableConstants {
+PROCESS_STATUS
+PROCESS_REASON
+PROCESS_START_USER_ID
+PROCESS_START_USER_SELECT_ASSIGNEES
+PROCESS_APPROVE_USER_SELECT_ASSIGNEES
+PROCESS_SKIP_START_USER_NODE
+PROCESS_START_TIME
+PROCESS_DEFINITION_NAME
+TASK_STATUS
+TASK_REASON
+TASK_SIGN_PIC_URL
+OP_RECORD_TASK
}
BpmnVariableConstants --|> ApiVariableConstants

图表来源

章节来源

表达式与类型转换

表达式求值：通过表达式管理器创建表达式并求值，支持从变量容器或Map变量容器中取值
类型转换：根据变量的实际类型对传入参数进行转换，确保比较与判断的准确性
任务表单变量过滤：移除状态与理由等内部变量，避免污染表单数据

Mermaid Diagram Code:

flowchart TD
Start(["进入表达式求值"]) --> GetContainer["获取变量容器"]
GetContainer --> HasConfig{"存在引擎配置?"}
HasConfig --> |是| CreateExpr["创建表达式"]
HasConfig --> |否| Fallback["通过ManagementService命令执行"]
CreateExpr --> Eval["求值表达式"]
Fallback --> Eval
Eval --> Convert["按变量类型转换参数"]
Convert --> Filter["过滤任务表单变量"]
Filter --> End(["返回结果"])

图表来源

章节来源

变量查询与生命周期管理

运行中变量：通过RuntimeService获取流程实例当前变量
历史变量：通过HistoryService查询历史流程变量，合并处理空值
生命周期：创建（启动流程时注入）、更新（审批过程动态调整）、销毁（流程完成后清理或删除）

Mermaid Diagram Code:

sequenceDiagram
participant Caller as "调用方"
participant Q as "QueryUtils"
participant RT as "RuntimeService"
participant HIS as "HistoryService"
Caller->>Q : getInstanceVariableByProcessInstanceId
Q->>RT : getVariables(运行中)
alt 运行中存在
RT-->>Q : 返回变量
else 运行中不存在
Q->>HIS : 查询历史变量
HIS-->>Q : 返回变量
end
Q-->>Caller : 返回变量集合

图表来源

QueryUtils.java

章节来源

QueryUtils.java

作用域与管理策略

流程实例级变量：影响整个流程生命周期，如状态、发起人、跳过策略等
任务级变量：仅限当前任务使用，如任务状态、审批理由、签名图片等
管理策略：通过统一的键名常量与工具类，确保变量在不同作用域内的正确读写与隔离

章节来源

在表达式计算与条件判断中的应用

条件节点：通过表达式函数对变量进行类型转换后再参与条件判断
表单过滤：在任务表单渲染前移除内部变量，避免干扰用户界面
动态赋值：在任务完成或流程推进时，根据业务规则动态设置变量

章节来源

依赖关系分析

常量依赖：业务变量常量继承自API常量，流程变量常量继承自业务常量，形成清晰的层次结构
工具依赖：表达式工具依赖Flowable引擎配置；查询工具依赖运行时与历史服务
服务依赖：流程实例服务依赖运行时与历史服务，同时触发事件与消息通知

Mermaid Diagram Code:

graph LR
AV["ApiVariableConstants"] --> BV["BpmnVariableConstants"]
VC["VariableConvertByTypeExpressionFunction"] --> FU["FlowableUtils"]
Q["QueryUtils"] --> RT["RuntimeService"]
Q --> HIS["HistoryService"]
PI["BpmProcessInstanceServiceImpl"] --> RT
PI --> HIS
PI --> EV["事件发布"]

图表来源

章节来源

性能考量

变量查询优化：优先使用运行时服务查询当前变量，历史变量查询仅在必要时进行
表达式求值：尽量减少复杂表达式层级，避免频繁创建表达式对象
事件与消息：流程完成后触发事件与消息应异步处理，避免阻塞流程推进

故障排除指南

变量类型不匹配：使用类型转换函数确保比较对象类型一致
表达式求值异常：检查引擎配置是否可用，必要时通过ManagementService兜底
历史变量缺失：确认历史服务查询条件与数据保留策略

章节来源

结论

流程变量是工作流系统的核心数据载体，贯穿流程的全生命周期。通过统一的键名常量、可靠的表达式与类型转换、完善的查询与事件机制，系统实现了变量在表达式计算、条件判断与数据传递中的高效协同。遵循本文的最佳实践与注意事项，可显著提升流程变量使用的稳定性与可维护性。

目录​

简介​

项目结构​

核心组件​

架构概览​

详细组件分析​

流程变量键名常量体系​

表达式与类型转换​

变量查询与生命周期管理​

作用域与管理策略​

在表达式计算与条件判断中的应用​

依赖关系分析​

性能考量​

故障排除指南​

结论​

目录

简介

项目结构

核心组件

架构概览

详细组件分析

流程变量键名常量体系

表达式与类型转换

变量查询与生命周期管理

作用域与管理策略

在表达式计算与条件判断中的应用

依赖关系分析

性能考量

故障排除指南

结论