Flowable7.x学习笔记（十八）拾取我的待办

前言

本文从解读源码到实现功能，完整的学习Flowable的【TaskService】-【claim】方法实现的任务拾取功能。

一、概述

当调用 TaskService.claim(taskId, userId) 时，Flowable 会先加载并校验任务实体，再判断该任务是否已被认领；若未被认领，则将 assignee 字段设为传入的 userId（null 则表示“解绑”），并在身份链接（IdentityLink）表中做相应的增删操作；随后触发任务分配事件、写入历史记录（如开启历史配置时），最后将更新结果刷新到数据库。所有这些操作最终都委托给了 TaskServiceImpl 中的 ClaimTaskCmd 来完成。

二、方法签名与定位

claim(String taskId, String userId) 方法在 org.flowable.engine.TaskService 接口中定义，由 TaskServiceImpl 实现，实现层直接调用命令执行器（commandExecutor.execute(new ClaimTaskCmd(taskId, userId))），ClaimTaskCmd 是执行认领逻辑的核心。

ClaimTaskCmd 继承自 NeedsActiveTaskCmd，用于确保任务处于激活状态后再执行认领逻辑。

public class ClaimTaskCmd extends NeedsActiveTaskCmd {
protected String userId;
public ClaimTaskCmd(String taskId, String userId) {
super(taskId);
this.userId = userId;
}
}

构造器保存了要认领的 taskId 和 userId，并由父类处理挂起状态检查，当传入的 userId 非空时，表示要将任务分配给某位用户。

① 设置认领时间与状态

使用引擎的 Clock 获取当前时间，调用 task.setClaimTime(...) 和 task.setClaimedBy(userId) 设置认领元数据。将任务状态更新为 Task.CLAIMED。

② 冲突检查

若该任务已被分配给某人（task.getAssignee()!=null），且与当前 userId 不同，则抛出 FlowableTaskAlreadyClaimedException，避免多用户并发认领。

若已分配给同一用户，则仅记录一次 recordTaskInfoChange(...)，保持历史一致性。

③ 首次分配

当任务尚未有 assignee 时，调用 TaskHelper.changeTaskAssignee(task, userId) 为任务设置新认领者。

如果配置了 UserTaskStateInterceptor，会触发其 handleClaim(...) 回调，用于外部扩展。

④ 写入身份链接历史

最后，无论是首次分配还是重复分配，都通过 HistoryManager.createUserIdentityLinkComment(...) 将 ASSIGNEE 类型的身份链接（认领记录）写入历史审计表。

三、加载与校验任务

① 加载任务实体

命令中首先通过 TaskEntityManager.findById(taskId) 从 ACT_RU_TASK 表中获取 TaskEntity。

② 任务存在性检查

若返回 null，抛出 FlowableObjectNotFoundException，提示“无此任务”。

③ 已认领冲突检查

若 task.getAssignee() 不为 null 且与传入的 userId 不同，则抛出冲突异常（FlowableConflictException），禁止不同用户重复认领.

四、赋值 assignee 与解绑

① 设为认领

当 userId 非空时，调用 TaskEntity.setAssignee(userId) 将任务归属新认领者。

② 设为解绑

当 userId==null 时，等价于 unclaim 操作，相当于将 assignee 设回 null。

五、身份链接（IdentityLink）处理

① 历史遗留机制

Flowable 中“候选人”与“认领人”都存储在 ACT_RU_IDENTITYLINK 表，但 ASSIGNEE 类型在表中常伴随特殊处理（空 TASK_ID 或 PROC_INSTANCE_ID 字段）。

② 若是认领

在命令里会先删除原有与该任务相关的 ASSIGNEE 类型 IdentityLink，再新增一条新的 IdentityLinkType.ASSIGNEE，以确保数据一致。

③ 若是解绑

则只执行删除操作，不新增。

六、事件分发与历史记录

① 事件分发

完成认领后，Flowable 会通过 EventDispatcher 发布 ENTITY_LINK_CREATED（或删除时 ENTITY_LINK_DELETED）以及 TASK_ASSIGNED 等事件，供监听器或审计插件消费。

② 历史记录

若引擎配置 historyLevel ≥ AUDIT，会在 ACT_HI_TASKINST 表中记录任务认领时间、认领者等信息。

七、持久化更新

最后，命令通过 TaskEntityManager.update(taskEntity) 将变更刷回 ACT_RU_TASK 表，并同步提交事务。若配置了异步历史，历史记录写入也可能延迟到异步作业中完成，进一步提升性能。

八、完成后端接口

① 定义请求参数

这里我们只需要传入任务ID即可，用户ID我们从框架的session中获取，一般的脚手架都是这样的，请结合自己的脚手架处理。

package com.ceair.entity.request;import lombok.Data;import java.io.Serial;
import java.io.Serializable;/*** @author wangbaohai* @ClassName PickupMyTaskReq* @description: 拾取我的任务请求参数* @date 2025年05月03日* @version: 1.0.0*/
@Data
public class PickupMyTaskReq implements Serializable {@Serialprivate static final long serialVersionUID = 1L;// 任务编号private String taskId;}

② 定义服务接口

/*** 领取我的任务接口* 此方法允许用户领取属于自己的任务，根据提供的条件和参数** @param pickupMyTaskReq 领取任务的请求对象，包含领取任务所需的信息和条件* @return 返回一个Boolean值，表示任务领取是否成功true表示成功，false表示失败*/
Boolean pickupMyTask(PickupMyTaskReq pickupMyTaskReq);

③ 实现服务接口

/*** 拾取我的待办任务* <p>* 此方法允许当前登录用户拾取一个待办任务通过提供任务ID和当前用户信息，* 系统将该任务分配给当前用户** @param pickupMyTaskReq 包含任务ID的请求对象如果请求对象或任务ID为空，*                        将抛出IllegalArgumentException异常* @return 任务拾取成功返回true，否则抛出异常* @throws BusinessException        如果用户未登录或任务拾取过程中发生业务异常* @throws IllegalArgumentException 如果输入参数不合法，如任务ID为空*/
@Override
public Boolean pickupMyTask(PickupMyTaskReq pickupMyTaskReq) {try {// 参数判空if (pickupMyTaskReq == null || StringUtils.isBlank(pickupMyTaskReq.getTaskId())) {log.error("任务拾取失败：非法的任务ID");throw new IllegalArgumentException("任务拾取失败：非法的任务ID");}// 获取当前登录用户信息UserInfo userInfo = userInfoUtils.getUserInfoFromAuthentication();if (userInfo == null) {log.error("拾取我的待办任务失败，原因：用户未登录");throw new BusinessException("拾取我的待办任务失败，原因：用户未登录");}// 通过 taskService 拾取任务taskService.claim(pickupMyTaskReq.getTaskId(), String.valueOf(userInfo.getId()));return true;} catch (IllegalArgumentException e) {log.error("任务拾取失败，原因：参数错误", e);throw new BusinessException("任务拾取失败，原因：参数错误", e);} catch (BusinessException e) {log.error("任务拾取失败，原因：业务异常", e);throw new BusinessException("任务拾取失败，原因：业务异常", e);} catch (Exception e) {log.error("任务拾取失败，原因：未知异常", e);throw new BusinessException("任务拾取失败，原因：未知异常", e);}
}

④ 定义功能接口

/*** 任务拾取。* <p>* 权限: /api/v1/myTask/pickupMyTask* 参数: pickupMyTaskReq - 包含任务拾取相关信息的请求对象* 返回: Result<Boolean> 表示任务拾取是否成功* <p>* 异常处理：* - 业务层异常  返回任务拾取失败信息* - 其他未知异常  系统异常提示*/
@PreAuthorize("hasAnyAuthority('/api/v1/myTask/pickupMyTask')")
@Parameter(name = "pickupMyTaskReq", description = "任务拾取请求对象", required = true)
@Operation(summary = "任务拾取")
@PostMapping("/pickupMyTask")
public Result<Boolean> pickupMyTask(@RequestBody PickupMyTaskReq pickupMyTaskReq) {try {// 调用业务层方法，将任务分配给当前登录用户return Result.success(mayTaskService.pickupMyTask(pickupMyTaskReq));} catch (Exception e) {log.error("任务拾取失败，原因：{}", e.getMessage());return Result.error("任务拾取失败，原因：" + e.getMessage());}
}

九、完善前端功能按钮

① 定义前端参数类型

// 拾取任务请求参数

export interface PickupMyTaskReq {

taskId: string // 任务编号，对应 Java 中的 String taskId

}

② 封装请求接口

/**

* 拾取任务

*/

export function pickupMyTask(data: PickupMyTaskReq) {

return request.post<any>({

url: '/pm-process/api/v1/myTask/pickupMyTask',

data,

})

}

③ 优化界面按钮

这里把拾取按钮加上权限自定义指令，以及点击事件功能

<el-button v-if="scope.row.status === 1" v-hasButton="`btn.myTask.pickupMyTask`" type="primary" @click="onPickup(scope.row)">
拾取
</el-button>

④ 完成按钮功能

/*** 异步函数用于处理任务拾取操作* @param row 任务对象，包含任务ID等信息*/
async function onPickup(row: TaskVO) {try {// 获取当前任务ID并设置参数const param: PickupMyTaskReq = {taskId: row.taskId,}// 调用后端接口进行拾取操作const result: any = await pickupMyTask(param)// 如果接口调用成功且返回的状态码为200，则显示成功提示信息if (result.success && result.code === 200) {ElMessage({message: '拾取成功',type: 'success',})// 重新加载数据handerPageData()}else {ElMessage({message: `拾取失败: ${result.message}`,type: 'error',})}}catch (error) {// 捕获异常并提取错误信息let errorMessage = '未知错误'if (error instanceof Error) {errorMessage = error.message}// 显示操作失败的错误提示信息ElMessage({message: `拾取失败: ${errorMessage || '未知错误'}`,type: 'error',})}
}