1、概念

流程变量（Process Variables）流程变量是 Flowable 工作流引擎中用于存储、传递和共享与业务流程相关的数据的机制。你可以将它们理解为附着在流程实例（或执行流、任务）上的键值对（Key-Value）数据。

1. 数据驱动流程： 流程的走向（网关决策）、任务处理逻辑、表单内容展示、监听器行为等都可以基于流程变量的值来决定。
2. 状态持久化： Flowable 会自动将流程变量持久化到其数据库中。这意味着即使服务器重启，流程实例的状态（包括变量值）也能被恢复。
3. 作用域（实例关系）： 变量存在于特定的作用域内（流程实例、执行流、任务），这决定了它们的生命周期和可见性（后面详细解释）。
4. 类型丰富： 支持多种 Java 基本类型及其包装类（String, Integer, Long, Double, Boolean, Date）、字节数组、以及实现了 java.io.Serializable 接口的复杂自定义对象。序列化后的自定义对象会以 BLOB 或 CLOB 形式存储在数据库中。
5. 传递与共享： 在流程实例内部，变量可以在不同的活动和任务之间传递和共享（根据作用域规则），使得后续步骤能访问之前步骤产生的数据。

2、流程变量的作用域（实例关系）

这是理解流程变量的关键！变量不是全局存在的，它们总是绑定在一个特定的“容器”上，这个容器决定了变量的生命周期和谁可以访问它。

2.1、流程实例作用域（Process Instance Scope）

1. 容器： 整个流程实例 (ProcessInstance)。

2. 生命周期： 从变量被设置开始，直到整个流程实例结束（完成或被删除）。

3. 可见性： 最高。该流程实例下的所有执行流（Execution）和所有任务（Task）都可以读取和写入这些变量。它们是整个流程实例的“全局”数据。

4. 设置方式：

   1. 启动流程时：runtimeService.startProcessInstanceByKey(..., variables)

   2. 流程实例运行中：runtimeService.setVariable(executionId, variableName, value) 或 runtimeService.setVariables(executionId, variablesMap)

5. 获取方式：

   1. runtimeService.getVariable(executionId, variableName)

   2. runtimeService.getVariables(executionId) (获取该作用域所有变量)

   3. taskService.getVariable(taskId, variableName) (任务也能获取流程实例变量)

   4. taskService.getVariables(taskId) (任务也能获取流程实例变量)

2.2、执行流作用域（Execution Scope）

1. 容器： 一个具体的执行流 (Execution)。执行流代表流程当前正在活动的路径。一个流程实例在并行网关处可能分裂出多个并发执行流。

2. 生命周期： 从变量被设置开始，直到该执行流到达结束事件或流程实例结束。

3. 可见性： 中等。变量只对绑定在该特定执行流上的活动和任务可见。同一个流程实例下的其他并行执行流通常无法直接访问这些变量（除非显式传递）。主要用于保存特定执行路径的临时状态。

4. 设置方式：

   1. runtimeService.setVariableLocal(executionId, variableName, value) 或 runtimeService.setVariablesLocal(executionId, variablesMap) (注意 Local)
5. 获取方式：
   1. runtimeService.getVariableLocal(executionId, variableName) (注意 Local)

   2. runtimeService.getVariablesLocal(executionId) (获取该执行流作用域所有变量)

   3. 任务关联的执行流：taskService.getVariableLocal(taskId, variableName) (如果任务绑定到该执行流)

2.3、任务作用域（Task Scope）

1. 容器： 一个用户任务 (Task)。

2. 生命周期： 从变量被设置开始，直到该任务完成或被删除。

3. 可见性： 最低。变量仅对该任务本身可见。即使是同一个流程实例或同一个执行流下的其他任务也无法直接访问这些变量。通常用于存储仅与该特定任务处理相关的临时数据（如表单提交的草稿、任务备注等）。

4. 设置方式：

   1. taskService.setVariableLocal(taskId, variableName, value) 或 taskService.setVariablesLocal(taskId, variablesMap) (注意 Local)
5. 获取方式：
   1. taskService.getVariableLocal(taskId, variableName) (注意 Local)

   2. taskService.getVariablesLocal(taskId) (获取该任务作用域所有变量)

3、作用域查找规则

当通过 getVariable(variableName) (不带 Local) 方法（无论是在 RuntimeService 还是 TaskService 上）查询一个变量时，Flowable 会按照以下从具体到宽泛的作用域顺序查找：

1. 任务作用域 (Task Scope)： 如果调用方是任务（通过 taskService.getVariable(taskId, name)），先查任务本地变量。
2. 执行流作用域 (Execution Scope)： 如果任务本地没找到（或者调用方直接提供的是 executionId），则查找任务所属的执行流的本地变量。
3. 流程实例作用域 (Process Instance Scope)： 如果执行流本地也没找到，则查找流程实例变量。
4. 父执行流/父流程实例作用域： 如果当前执行流是子流程或调用活动产生的，引擎还会向上查找父执行流（然后是父执行流的流程实例变量）。这实现了变量从父流程到子流程的传递（默认是单向传递，子流程变量不会自动影响父流程）。

3.1、示例

假设一个简单的请假流程： 员工提交请假申请 (Start Event) -> 部门经理审批 (User Task) -> 人事存档 (Service Task) -> 结束 (End Event)。

// 1. **启动流程实例 (设置流程实例变量)**
Map<String, Object> startVariables = new HashMap<>();
startVariables.put("applicant", "张三"); // 申请人 (String)
startVariables.put("startDate", new Date()); // 开始日期 (Date)
startVariables.put("days", 3); // 请假天数 (Integer)
startVariables.put("reason", "回家探亲"); // 原因 (String)
startVariables.put("approvalComment", ""); // 初始化审批意见 (String)

ProcessInstance processInstance = runtimeService.startProcessInstanceByKey(
    "leaveRequestProcess", // 流程定义Key
    businessKey, // 可选业务键 (如请假单号)
    startVariables
);
String processInstanceId = processInstance.getId();

// 此时，变量 `applicant`, `startDate`, `days`, `reason`, `approvalComment` 都是**流程实例作用域**的变量。
// 整个流程实例内部任何地方都可以访问它们。

// 2. **部门经理审批任务 (查询和设置变量)**
// 假设经理查询待办任务
Task managerTask = taskService.createTaskQuery()
    .taskAssignee("李经理")
    .processInstanceId(processInstanceId)
    .singleResult();

// 2.1 **查询流程实例变量** (经理需要看到申请人提交的信息)
String reason = (String) taskService.getVariable(managerTask.getId(), "reason"); // 查找规则：先Task Local -> 无 -> Execution Local (此时任务通常没有Execution本地变量) -> 无 -> Process Instance -> 找到
Integer days = (Integer) taskService.getVariable(managerTask.getId(), "days");

// 2.2 **设置流程实例变量** (经理更新审批意见 - 这个意见后续流程也需要)
taskService.setVariable(managerTask.getId(), "approvalComment", "情况属实，同意请假"); // 没有Local，默认设置到流程实例作用域
// 或者明确设置流程实例变量 (效果同上)
// runtimeService.setVariable(processInstanceId, "approvalComment", "情况属实，同意请假");

// 2.3 **设置任务本地变量** (经理添加一个仅供自己或本次任务使用的临时备注)
taskService.setVariableLocal(managerTask.getId(), "internalNote", "记得提醒张三回来后补交车票复印件");
// 这个 `internalNote` 变量只存在于这个任务上。当经理完成任务后，这个变量通常就不存在了（除非配置了历史记录）。人事存档任务或后续流程无法直接通过 `getVariable` 访问到它。

// 3. **经理完成任务**
taskService.complete(managerTask.getId());
// 完成任务后，任务本地变量 `internalNote` 生命周期结束（除非历史记录）。流程实例变量 `approvalComment` 被更新并继续存在。

// 4. **人事存档服务任务 (查询流程实例变量)**
// 服务任务逻辑通常在 JavaDelegate 的 execute 方法中实现
public class ArchiveTask implements JavaDelegate {
    @Override
    public void execute(DelegateExecution execution) {
        // 获取当前执行流的Execution Id
        String executionId = execution.getId();
        // 获取流程实例ID
        String processInstanceId = execution.getProcessInstanceId();

        // **查询流程实例变量** (获取审批结果和申请信息)
        String applicant = (String) runtimeService.getVariable(processInstanceId, "applicant"); // 直接按流程实例ID查
        String comment = (String) execution.getVariable("approvalComment"); // DelegateExecution 的 getVariable 方法会按作用域查找规则查找
        // ... 执行存档逻辑 (如写入数据库，发送通知等)

        // **设置一个执行流本地变量** (假设存档操作生成了一个存档ID，只在这个执行路径后续可能用到)
        String archiveId = generateArchiveId();
        execution.setVariableLocal("archiveRefId", archiveId);
        // 这个 `archiveRefId` 只在这个特定的执行流（当前存档任务所在的执行流）上可见。如果流程后面还有活动，它们可以访问（如果是同一个执行流）。但如果是并行分支，其他分支看不到它。
    }

}

// 5. **流程结束**
// 当流程到达结束事件，整个流程实例结束。
// 所有流程实例作用域的变量 (`applicant`, `startDate`, `days`, `reason`, `approvalComment`) 的生命周期结束。
// 所有执行流作用域的变量 (`archiveRefId`) 的生命周期也随着其执行流结束而结束。

流程实例 (Process Instance) [ID: proc-123]
├── 流程实例变量 (Scope)
│ ├── applicant: "张三"
│ ├── startDate: 2023-10-27
│ ├── days: 3
│ ├── reason: "回家探亲"
│ └── approvalComment: "情况属实，同意请假"
│
├── 执行流 A (Execution) [ID: exec-100] (主执行流)
│ ├── 执行流本地变量 (Scope) (可能为空)
│ │
│ ├── 用户任务：部门经理审批 [ID: task-789]
│ │ └── 任务本地变量 (Scope)：internalNote: "记得提醒..."
│ │
│ └── 服务任务：人事存档
│ ├── (执行中) 设置执行流本地变量：archiveRefId: "ARC-001"
│ └── (执行完成后) archiveRefId 随执行流结束而消失
│
└── (假设有并行网关) 执行流 B (Execution) [ID: exec-101] (并行分支)
└── ... (无法看到 exec-100 的本地变量 archiveRefId)

4、关键点总结

1. 作用域是核心： 明确变量应该放在哪个作用域（流程实例、执行流、任务）决定了它的生命周期和谁能访问它。优先使用能满足需求的最小作用域（如任务本地变量），避免不必要的“全局”污染。
2. setVariable vs setVariableLocal： setVariable 方法（不带 Local）会尝试设置到流程实例作用域（如果找不到同名的更本地作用域的变量），而 setVariableLocal 则明确设置到当前调用点所属的最小作用域（任务或执行流）。
3. getVariable 的查找规则： 理解 getVariable 方法按照 任务本地 -> 执行流本地 -> 流程实例 -> (父作用域) 的查找顺序非常重要，这解释了为什么任务能访问到流程实例变量。
4. 变量驱动流程： 网关（如排他网关）的条件表达式 ${days > 5} 会使用查找规则找到 days 变量（通常是流程实例变量）的值来决定路径。服务任务、任务监听器、执行监听器都可以读取和设置变量来实现业务逻辑。
5. 序列化： 存储复杂自定义对象时，务必确保它们实现了 java.io.Serializable 接口。
6. 历史： Flowable 的历史服务 (HistoryService) 可以查询历史流程实例变量和历史任务变量，即使流程实例已经结束。这对于审计和报表至关重要。