搞懂 Flowable 中的流程定义和流程实例

[TOC]

本文为稀土掘金技术社区首发签约文章，14天内禁止转载，14天后未获授权禁止转载，侵权必究！

本专栏第二篇已发布，尚未看过的小伙伴请移步这里：

1. Flowable 开篇，流程引擎扫盲
2. 通过 Flowable-UI 来体验一把 Flowable 流程引擎

流程定义和流程实例是两个不同的概念哦。

1. 捋清三个概念

首先我们需要先捋清三个概念：

• 流程定义 ProcessDefinition
• 流程实例 ProcessInstance
• 执行实例 Execution

流程定义

流程定义 ProcessDefinition 这个好说，将一个流程 XML 文件部署到 flowable 中，这就是一个定义好的流程了，基于这个定义好的流程，我们可以开启很多流程实例。

流程实例

流程实例 ProcessInstance 就是通过流程定义启动的一个流程，他表示一个流程从开始到结束的最大的流程分支，在一个流程中，只存在一个流程实例，流程实例和流程定义的关系就类似于 Java 对象和 Java 类之间的关系。

执行实例

执行实例 Execution 稍微有点难以理解。

首先从类的关系上来看，ProcessInstance 就是 Execution 的子类。

流程实例通常是执行实例的根结点，即在一个流程中，出口和入口可以算是一个流程实例的节点，而中间的过程则是执行实例。

假如流程本身就是一条线，那么流程实例和执行实例基本上是一样的，但是如果流程中包含多条线，例如下图：

这张图中有并行网关，并行任务执行的时候，每一个并行任务就是一个执行实例，这样大家就好理解了。

结论就是，在一个流程实例中，除了开始和结束之外，其他的都是执行实例。即使流程只有一条线，中间的也都是执行实例，只不过此时的执行实例等于流程实例而已。

好啦，三个基本概念先捋清楚。

接下来我们就分别来学习这三个东西。

当我们使用了 Spring Boot 之后，默认情况下流程是会自动部署的，基本上不需要我们额外做什么事情。不过这些操作里还是有不少细节，今天松哥就来带大家一起来梳理一下。

2. 默认行为

首先我们先来梳理一下默认行为。

默认情况下，我们放在 resources/processes 目录下的所有流程文件会自动被部署，流程文件的后缀有两种形式 bpmn20.xml 或者 bpmn。当然，无论是存放流程文件的位置，还是流程文件的格式，都是可以定制的，涉及到的属性主要有三个，可在 application.properties 中进行配置：

flowable.check-process-definitions=false
flowable.process-definition-location-prefix=classpath*:/processes/
flowable.process-definition-location-suffixes=**.bpmn20.xml,**.bpmn

• flowable.check-process-definitions：这个表示是否在项目启动的时候，去检查文件目录是否有对应的流程文件，该属性为 true 表示如果有流程文件就自动部署，false 表示不检查，那么也就不会自动部署。
• flowable.process-definition-location-prefix：这个是流程文件的位置，默认就是 classpath*:/processes/，当然开发者也可以进行配置。
• flowable.process-definition-location-suffixes：这个是流程文件的后缀，默认有两个，分别是 **.bpmn20.xml 和 **.bpmn，当然开发者也可以进行配置。

这个配置应该没啥好说的。

3. 动态部署

有的时候，我们的流程可能并不是提前设计好的，而是项目启动之后，动态部署的，例如项目启动成功之后，动态上传一个流程的 XML 文件进行部署，这也是一种比较常见的场景，对于这种情况，我们可以按照如下方式进行部署：

@RestController
public class ProcessDeployController {

    @Autowired
    RepositoryService repositoryService;

    @PostMapping("/deploy")
    public RespBean deploy(MultipartFile file) throws IOException {
        DeploymentBuilder deploymentBuilder = repositoryService.createDeployment()
                .category("javaboy的工作流分类")
                .name("javaboy的工作流名称")
                .addInputStream(file.getOriginalFilename(), file.getInputStream())
                .key("javaboy的工作流key");
        Deployment deployment = deploymentBuilder
                .deploy();
        return RespBean.ok("部署成功",deployment.getId());
    }
}

我这里给了一个简单的文件上传接口，关于文件上传部分我就不多说了。我们来看下流程部署：

• 首先通过 repositoryService.createDeployment() 方法来创建一个流程部署构建器，即 DeploymentBuilder。
• 接下来为 DeploymentBuilder 设置分类、名称以及 key 等属性。
• 关键的方法是 addInputStream，通过该方法去指定流程文件。官方的提供的指定流程文件的方式有好几种；除了 addInputStream 之外，另外还有一个 addString，这个就是将流程文件转为一个字符串传入进来；addBytes 是将流程文件转为字节数组传进来；addClasspathResource 方法则是直接从 classpath 目录下去加载流程文件，这几个方法根据自己的使用场景选择一个合适的方法去调用即可。
• **这里有一个需要跟大家强调的地方，就是 addInputStream/addBytes/addString 等方法都需要设置资源名，这个名称是可以随意设置的，但是注意名称的后缀，需要是 bpmn20.xml 或者 bpmn，否则流程没有部署。**为什么流程名后缀要是 bpmn20.xml 或者 bpmn 呢？参考第一小节。

4. 表分析

在我们的流程部署过程中，一共有三张表参与到我们的工作中了，虽然松哥之前已经写过文章和大家梳理 flowable 中各个数据表的作用，不过当时只是大致上介绍了一下，没有细说，这次我们就先来看看这次涉及到的三张表。

ACT_RE_DEPLOYMENT

这个表是流程部署表，每部署一个流程，这张表中就会新增一条记录，用来描述我们刚刚定义好的流程：

这里的 ID_、NAME_、CATEGORY_ 等等，就是我们在部署流程的时候设置的参数。

ACT_RE_PROCDEF

这是流程定义表，我们每定义的一个流程，都会记录在这张表中：

这张表中的字段比较多，我这里只是列出来了其中一部分。这这表中有一个 DEPLOYMENT_ID 字段，和 ACT_RE_DEPLOYMENT 表进行关联，所以 ACT_RE_DEPLOYMENT 和 ACT_RE_PROCDEF 表的关系，其实是一对一的关系，部署表中的一条记录对应定义表中的一条记录。

另外，该表中有一个 CATEGORY_ 的字段，这个字段表示流程的分类，注意这个和部署的分类可不一样，流程部署的分类参数第二小节的代码，流程的分类，说白了其实就是我们流程定义 XML 文件中的 targetNamespace 属性，如下图：

大家可根据自己的实际需求去修改 targetNamespace 属性的值，这个值改了之后，ACT_RE_PROCDEF 表中的 CATEGORY_ 字段也会跟着发生变化。

另外，该表中还有一个 VERSION_ 字段，这个看名字就知道是描述记录的版本号，当我们修改了流程的内容之后，重新部署的时候，ACT_RE_DEPLOYMENT 表和 ACT_RE_PROCDEF 表均会自动增加一条记录数，其中，流程定义表 ACT_RE_PROCDEF 中的记录的 VERSION_ 字段的值会自动加 1，这样我们就能够看到不同历史版本的流程定义。

那么系统是怎么识别修改后的流程和前一个流程是同一个呢？主要是靠流程的 id 属性，如下图：

这个流程的 id 属性，对应到表中，就是 ACT_RE_PROCDEF 表的 KEY_ 字段。

ACT_GE_BYTEARRAY

涉及到的第三张表是这个通用数据存储表，这个表的字段比较少，如下图：

小伙伴们看到，这个表中有一个 DEPLOYMENT_ID 字段，这个就是跟 ACT_RE_DEPLOYMENT 表关联的字段，一条流程部署记录在 ACT_GE_BYTEARRAY 表中对应两条记录，分别是记录 XML 文件和记录流程图片。

这个表中有一个 BYTES_ 字段，我们部署的流程的 XML 文件就保存在这里，同时，系统默认还会根据 XML 文件生成一张流程图片，也保存在这里，图片就像下面这种：

所以一个流程部署，在这张表中对应两条记录，一条记录 XML 文件，一条记录流程图片。

好啦，这就是流程部署涉及到的三张表。

5. 查询操作

接下来，强烈建议大家在 Spring Boot 的 application.properties 中添加如下配置，开启 flowable 日志：

logging.level.org.flowable=debug

这个配置表示开启 flowable 的日志，开启日志的好处是我们可以看到底层的 SQL，学习 flowable，调用 API 的时候，不能只掌握 API 的使用，调用 API 的时候，心里想着这是操作哪张表，学起来更快。

5.1 查询部署信息

例如我们现在想要查询流程的部署信息，如下：

@Test
void test01() throws IOException {
    List<Deployment> list = repositoryService.createDeploymentQuery().list();
    for (Deployment deployment : list) {
        logger.info("id:{}；key:{}", deployment.getId(), deployment.getKey());
    }
}

创建一个查询器，然后返回所有的流程部署信息并打印出来，我们看下此时 IDEA 控制台打印出来的 SQL 信息：

可以看到，底层执行的 SQL 其实就是去查询 ACT_RE_DEPLOYMENT 表。

现在我们再去看一些查询的方法，应该就很容易明白其含义了：

小伙伴们看到，我们可以利用流程部署的名字、分类、ID 等各种信息去查询，可以精确匹配也可以模糊匹配。

例如我想查询 key 为 javaboy的工作流key 的流程部署文件，但是这个流程我之前部署过多次（版本升级），现在我想查询最近一次的流程部署信息，查询方式如下：

@Test
void test01() throws IOException {
    Deployment deployment = repositoryService.createDeploymentQuery().deploymentKey("javaboy的工作流key").latest().singleResult();
    logger.info("id:{}；key:{}", deployment.getId(), deployment.getKey());
}

我们来看下控制台打印出来的 SQL：

--- [           main] i.p.e.D.selectDeploymentsByQueryCriteria : ==>  Preparing: SELECT RES.* from ACT_RE_DEPLOYMENT RES WHERE RES.KEY_ = ? and RES.DEPLOY_TIME_ = (select max(DEPLOY_TIME_) from ACT_RE_DEPLOYMENT where KEY_ = RES.KEY_ and DERIVED_FROM_ is null and ( (TENANT_ID_ IS NOT NULL and TENANT_ID_ = RES.TENANT_ID_) or (TENANT_ID_ IS NULL and RES.TENANT_ID_ IS NULL) ) ) order by RES.ID_ asc
--- [           main] i.p.e.D.selectDeploymentsByQueryCriteria : ==> Parameters: javaboy的工作流key(String)
--- [           main] i.p.e.D.selectDeploymentsByQueryCriteria : <==      Total: 1

这个 SQL 写的有点复杂，但是仔细看就一个意思，给定查询的 key 是 javaboy的工作流key，查询时间是一个最大的时间，这就很好懂了。

5.2 查询流程定义信息

接下来我们再来看看查询流程的定义信息。查询所有的流程定义信息，如下：

@Test
void test02() {
    List<ProcessDefinition> list = repositoryService.createProcessDefinitionQuery().list();
    for (ProcessDefinition pd : list) {
        logger.info("id:{};key:{};version:{};",pd.getId(),pd.getKey(),pd.getVersion());
    }
}

来看看控制台打印的 SQL：

可以看到，就是去流程定义表 ACT_RE_PROCDEF 去查看所有。

基于此，其他的查询 API 就都好理解了，例如根据流程定义的 KEY 去查询所有的流程定义，这个 KEY 其实就是流程定义 XML 文件中的 id：

@Test
void test02() {
    List<ProcessDefinition> list = repositoryService.createProcessDefinitionQuery().processDefinitionKey("javaboy_submit_an_expense_account").list();
    for (ProcessDefinition pd : list) {
        logger.info("id:{};key:{};version:{};",pd.getId(),pd.getKey(),pd.getVersion());
    }
}

我们来看下查询 SQL：

其他的查询 API 我就不挨个演示了，方法基本上都是见名知意的。

5.3 原生查询

要是觉得用 API 查询 不过瘾，我们也可以自己写 SQL 查询。

跟前面一样，例如我想查询 key 为 javaboy的工作流key 的流程部署文件，但是这个流程我之前部署过多次（版本升级），现在我想查询最近一次的流程部署信息，查询方式如下：

@Test
void test03() {
    Deployment deployment = repositoryService.createNativeDeploymentQuery().sql("SELECT RES.* from ACT_RE_DEPLOYMENT RES WHERE RES.KEY_ = #{key} and RES.DEPLOY_TIME_ = (select max(DEPLOY_TIME_) from ACT_RE_DEPLOYMENT where KEY_ = RES.KEY_) order by RES.ID_ asc").parameter("key", "javaboy的工作流key").singleResult();
    logger.info("id:{}；key:{}", deployment.getId(), deployment.getKey());
}

自己写 SQL 即可，参数的占位符用 #，因为这里底层的 SQL 操作实际上是 MyBatis。

相同的道理，我想根据流程定义的 KEY 去查询流程定义信息，使用原生查询方式如下：

@Test
void test04() {
    List<ProcessDefinition> list = repositoryService.createNativeProcessDefinitionQuery()
            .sql("SELECT RES.* from ACT_RE_PROCDEF RES WHERE RES.KEY_ = #{key} order by RES.ID_ asc")
            .parameter("key", "javaboy_submit_an_expense_account").list();
    for (ProcessDefinition pd : list) {
        logger.info("id:{};key:{};version:{};", pd.getId(), pd.getKey(), pd.getVersion());
    }
}

好啦，关于流程的部署和定义就和大家聊这么多，接下来我们来看流程实例。

部署之后的流程，这个还不能直接运行，例如我们部署了一个请假流程，现在 zhangsan 想要请假，他就需要开启一个请假流程，lisi 想请假，他也需要开启一个请假流程，这一个一个开启的请假流程就是流程实例，而我们一开始部署的请假流程，则类似于一个模版，基于此模版，我们可以开启很多个具体的流程实例。从这个角度来说，前面我们定义的 ProcessDefinition 就类似于一个 Java 类，而 ProcessInstance 则相当于一个 Java 对象。

6. 五种流程启动方式

当我们将流程部署好之后，接下来启动流程，我们有五种不同的方式去启动一个流程。

1. 通过流程定义的 id 去启动

首先就是通过流程定义的 id 去启动一个流程，对应的方法名称就是 RuntimeService#startProcessInstanceById，该方法有好几个重载的方法，不同的重载方法只是传递的参数不同而已，其他基本上都是一样的。

1. 通过流程的 key 去启动

也可以通过流程定义的 key 去启动一个流程，根据上篇文章的介绍，大家知道，这个流程定义的 key 其实就是流程 XML 文件中的 id，这个对应的方法名是 RuntimeService#startProcessInstanceByKey。

1. 通过流程的 key+tenantId 去启动

有这样一种情况，例如我有两个子系统 A 和 B，A 和 B 中都有一个请假流程的定义，现在当我想要启动一个流程的时候，怎么知道是启动 A 的请假流程还是启动 B 的请假流程呢？此时我们可以通过租户 ID 即 tenantId 去区分，所以，流程启动就还有一个方法 RuntimeService#startProcessInstanceByKeyAndTenantId。

1. 通过流程的 message 去启动

通过消息去启动一个流程，对应的方法是 RuntimeService#startProcessInstanceByMessage。

1. 通过流程的 message+tenanId 去启动

通过消息+租户 ID 去启动一个流程，对应的方法是 RuntimeService#startProcessInstanceByMessageAndTenantId。

7. 简单实践

首先我们绘制一个简单的流程图，然后进行部署，流程图如下：

流程 XML 文件如下：

<process id="leave" name="请假流程" isExecutable="true">
  <startEvent id="startEvent1" flowable:formFieldValidation="true" flowable:initiator="INITIATOR"></startEvent>
  <userTask id="sid-EF721F14-B1F1-4B3B-8018-608757EF5391" name="提交请假申请" flowable:assignee="${INITIATOR}" flowable:formFieldValidation="true">
    <extensionElements>
      <modeler:activiti-idm-initiator xmlns:modeler="http://flowable.org/modeler"><![CDATA[true]]></modeler:activiti-idm-initiator>
    </extensionElements>
  </userTask>
  <sequenceFlow id="sid-9C18B4D2-127C-40FD-BC81-1E947628D316" sourceRef="startEvent1" targetRef="sid-EF721F14-B1F1-4B3B-8018-608757EF5391"></sequenceFlow>
  <userTask id="sid-CC8E2905-C524-4C32-86DE-8C76102EBDF2" name="主管审批" flowable:assignee="zhangsan" flowable:formFieldValidation="true">
    <extensionElements>
      <modeler:initiator-can-complete xmlns:modeler="http://flowable.org/modeler"><![CDATA[false]]></modeler:initiator-can-complete>
    </extensionElements>
  </userTask>
  <sequenceFlow id="sid-62E837FF-DF33-414C-AC21-2DA84E478856" sourceRef="sid-EF721F14-B1F1-4B3B-8018-608757EF5391" targetRef="sid-CC8E2905-C524-4C32-86DE-8C76102EBDF2"></sequenceFlow>
  <userTask id="sid-D033E54B-4388-46B1-A8F9-472ABD2E1435" name="经理审批" flowable:assignee="lisi" flowable:formFieldValidation="true">
    <extensionElements>
      <modeler:initiator-can-complete xmlns:modeler="http://flowable.org/modeler"><![CDATA[false]]></modeler:initiator-can-complete>
    </extensionElements>
  </userTask>
  <sequenceFlow id="sid-7EDE624F-1D8F-4DF3-BB97-F8D9066A7A75" sourceRef="sid-CC8E2905-C524-4C32-86DE-8C76102EBDF2" targetRef="sid-D033E54B-4388-46B1-A8F9-472ABD2E1435"></sequenceFlow>
  <endEvent id="sid-FB77ACAC-DB24-4F44-9925-2FE2EAE09EF8"></endEvent>
  <sequenceFlow id="sid-21345500-1FCF-4356-9FB1-834C09BEA9CB" sourceRef="sid-D033E54B-4388-46B1-A8F9-472ABD2E1435" targetRef="sid-FB77ACAC-DB24-4F44-9925-2FE2EAE09EF8"></sequenceFlow>
</process>

这个 XML 文件我跟大家说一句，在启动节点上我设置了 flowable:initiator="INITIATOR"，相当于定义了流程发起人的变量为 INITIATOR，这个变量名是自定义的，定义好之后，将来我就可以在其他节点中就可以使用这个变量了。

很简单的流程，其中：

• 提交请假申请是由流程的发起人完成。
• 主管是 zhangsan。
• 经理是 lisi。

好了，先按照前面小节我们介绍的方式部署流程。

接下来我们要启动流程，假设我们用流程定义的 key 来启动一个流程实例：

@SpringBootTest
public class RuTest {
    @Autowired
    RuntimeService runtimeService;

    private static final Logger logger = LoggerFactory.getLogger(RuTest.class);

    @Test
    void test01() {
        Authentication.setAuthenticatedUserId("wangwu");
        ProcessInstance pi = runtimeService.startProcessInstanceByKey("leave");
        logger.info("id:{},activityId:{}",pi.getId(),pi.getActivityId());
    }
}

启动的代码其实很简单，当流程启动成功之后，流程中的每一步都会记录在 ACT_RU_EXECUTION 表中，同时，如果这个节点是一个用户任务节点（UserTask），那么同时还会在 ACT_RU_TASK 表中添加一条记录。

Authentication.setAuthenticatedUserId("wangwu"); 表示设置流程的发起人。

另外一种设置流程发起人的方式如下：

@Autowired
IdentityService identityService;
@Test
void test01() {
    identityService.setAuthenticatedUserId("wangwu");
    ProcessInstance pi = runtimeService.startProcessInstanceByKey("leave");
    logger.info("id:{},activityId:{}", pi.getId(), pi.getActivityId());
}

对于我们上面的流程来说，启动之后，就会进入到提交请假申请这个节点中，所以一共走了两个节点，那么 ACT_RU_EXECUTION 表中应该有两条记录了，如下图：

再来看看 ACT_RU_TASK 表中的内容：

可以看到，该表中有一条记录，这条记录其实就是提交请假申请这个节点，现在流程就停在这一步了，需要用户手动操作，才会继续向下走。

从这两张表中我们也可以大致上看出来，EXECUTION 和 ProcessInstance 之间的关系，ACT_RU_EXECUTION 表中的每一条记录就是一个 EXECUTION，多个 EXECUTION 对应同一个 PROC_INST_ID_，而 ACT_RU_TASK 表中的每一条 Task 记录也都对应了一个 EXECUTION。

现在我们就先去查询 wangwu 需要完成的 Task（wangwu 是流程的发起人）：

@Autowired
TaskService taskService;
@Test
void test02() {
    List<Task> list = taskService.createTaskQuery().taskAssignee("wangwu").list();
    for (Task task : list) {
        logger.info("id:{}；name:{}；taskDefinitionKey:{}",task.getId(),task.getName(),task.getTaskDefinitionKey());
    }
}

根据前面的介绍，我们知道，这个查询肯定是去 ACT_RU_TASK 表中进行查询的，我们来看下执行的 SQL：

可以看到，这里就是根据 ASSIGNEE_ 字段去查询任务的。

查询到任务之后，接下来去完成任务：

@Test
void test03() {
    List<Task> list = taskService.createTaskQuery().taskAssignee("wangwu").list();
    for (Task task : list) {
        taskService.complete(task.getId());
    }
}

这个表示查询到 wangwu 的任务然后完成，这个方法执行完成之后，首先会在 ACT_RU_TASK 表中插入一条新的需要 zhangsan 完成的 Task，然后会更新 ACT_RU_EXECUTION 表中对应的执行实例信息，最后再从 ACT_RU_TASK 表中删除需要 wangwu 完成的记录，这些操作是在同一个事务当中完成的。

好了，现在再去执行 test02 的查询方法，就会发现查不到了，因为没有 wangwu 需要完成的 task 了，接下来应该去查询 zhangsan 需要完成的 task。

当一个流程实例完成后，ACT_RU_TASK 和 ACT_RU_EXECUTION 表中的记录都会被删除，所以我们可以通过查询 ACT_RU_EXECUTION 表中是否还有记录，去判断一个一个流程目前是处于执行状态还是完成状态，代码如下：

@Test
void test04() {
    String pId = "9c8557dd-3727-11ed-9404-acde48001122";
    ProcessInstance pi = runtimeService.createProcessInstanceQuery().processInstanceId(pId).singleResult();
    if (pi == null) {
        logger.info("{} 流程执行结束", pId);
    }else{
        logger.info("{} 流程正在执行中", pId);
    }
}

最后，如果你想要去 ACT_RU_EXECUTION 表中查询执行实例也是 OK 的，方式如下：

@Test
void test05() {
    List<Execution> list = runtimeService.createExecutionQuery().processInstanceId("6d0341c7-3729-11ed-8e4e-acde48001122").list();
    for (Execution execution : list) {
        logger.info("id:{};processInstanceId:{};name:{}",execution.getId(),execution.getProcessInstanceId(),execution.getName());
    }
}

查看执行的 SQL 如下：

: ==>  Preparing: SELECT RES.* , P.KEY_ as ProcessDefinitionKey, P.ID_ as ProcessDefinitionId, P.NAME_ as ProcessDefinitionName, P.VERSION_ as ProcessDefinitionVersion, P.DEPLOYMENT_ID_ as DeploymentId from ACT_RU_EXECUTION RES inner join ACT_RE_PROCDEF P on RES.PROC_DEF_ID_ = P.ID_ WHERE RES.PROC_INST_ID_ = ? order by RES.ID_ asc
: ==> Parameters: 6d0341c7-3729-11ed-8e4e-acde48001122(String)
: <==      Total: 2

可以看到，就是去 ACT_RU_EXECUTION 表中查询的。

8. 删除流程实例

如果我们想删除一个流程实例，操作方式如下：

@Test
void test06() {
    runtimeService.deleteProcessInstance("65ab0b38-38f3-11ed-b103-acde48001122", "javaboy想删除了");
}

注意这个是删除正在执行的流程实例信息，并不会删除历史流程信息。

9. 获取运行的活动节点

可以根据执行实例的 ID 去查询活动节点的 ID，方式如下：

@Test
void test07() {
    List<Execution> list = runtimeService.createExecutionQuery().list();
    for (Execution execution : list) {
        List<String> activeActivityIds = runtimeService.getActiveActivityIds(execution.getId());
        for (String activeActivityId : activeActivityIds) {
            System.out.println("activeActivityId = " + activeActivityId);
        }
    }
}

这里查询的其实就是 ACT_RU_EXECUTION 表，查询到的 activeActivityId 其实就是该表的 ACT_ID 字段，我们来看下查询的 SQL：

好啦，流程实例先聊这么多，下篇文章我们继续～