Activiti 常用类、API 与数据库表笔记

一、核心引擎与服务

类/接口	说明	获取方式
`ProcessEngine`	流程引擎的入口，所有服务都从它获取	`ProcessEngines.getDefaultProcessEngine()`
`RepositoryService`	管理流程定义（部署、查询、删除）	`processEngine.getRepositoryService()`
`RuntimeService`	管理流程实例（启动、推进、变量）	`processEngine.getRuntimeService()`
`TaskService`	管理用户任务（查询、办理、认领、委派）	`processEngine.getTaskService()`
`HistoryService`	查询历史数据（实例、活动、任务）	`processEngine.getHistoryService()`
`ManagementService`	引擎管理与维护（作业、数据库操作）	`processEngine.getManagementService()`

二、流程定义相关（Repository）

类/接口	概念	对应表
`Deployment`	部署单元，将BPMN/XML资源加载到引擎	`ACT_RE_DEPLOYMENT`
`ProcessDefinition`	流程定义（抽象接口）	`ACT_RE_PROCDEF`
`ProcessDefinitionEntity`	流程定义的实体实现，包含BPMN解析后的完整结构	`ACT_RE_PROCDEF`
`TaskDefinition`	任务定义（BPMN中<userTask>的元数据），不是数据库表，而是运行时解析的结构，存储于`ProcessDefinitionEntity`中	无独立表，信息在`ACT_RE_PROCDEF`的字节码资源中

三、流程实例与执行相关（Runtime）

类/接口	概念	对应表
`ProcessInstance`	流程实例（一次具体业务请求）	`ACT_RU_EXECUTION`（根执行对象）
`Execution`	执行对象，流程实例的原子分支	`ACT_RU_EXECUTION`
`Variable`	流程变量，上下文数据	`ACT_RU_VARIABLE`

四、任务相关（Runtime + History）

类/接口	概念	对应表
`Task`	用户任务接口（标准API）	`ACT_RU_TASK`（运行时）<br>`ACT_HI_TASKINST`（历史）
`TaskEntity`	`Task`接口的实体实现类，包含持久化字段	`ACT_RU_TASK`
`TaskDefinition`	任务定义（如任务名称、候选组、表单key），与实例无关	无独立表（存储在`ProcessDefinitionEntity`中）
`IdentityLink`	任务与用户/组的关联（候选人/认领人）	`ACT_RU_IDENTITYLINK`

五、常用API示例（Java）

1. 部署流程

java

ProcessEngine pe = ProcessEngines.getDefaultProcessEngine();
RepositoryService rs = pe.getRepositoryService();
Deployment dep = rs.createDeployment()
    .addClasspathResource("process.bpmn")
    .deploy();

2. 启动流程实例

java

RuntimeService rs = pe.getRuntimeService();
ProcessInstance pi = rs.startProcessInstanceByKey("myProcessKey");

3. 查询并办理任务

java

TaskService ts = pe.getTaskService();
List<Task> tasks = ts.createTaskQuery()
    .taskAssignee("张三")
    .list();
for (Task t : tasks) {
    ts.complete(t.getId());
}

4. 获取流程定义实体

java

ProcessDefinition def = rs.createProcessDefinitionQuery()
    .processDefinitionKey("myKey")
    .latestVersion()
    .singleResult();
// 若需要 ProcessDefinitionEntity（通常无需显式使用）
// 可直接强转或通过内部服务获取

六、核心数据库表清单

分类	表名	说明
通用	`ACT_GE_BYTEARRAY`	存储BPMN、图片等二进制资源
	`ACT_GE_PROPERTY`	引擎属性表（版本、schema等）
流程仓库	`ACT_RE_DEPLOYMENT`	部署记录
	`ACT_RE_PROCDEF`	流程定义（含`ProcessDefinitionEntity`数据）
运行时	`ACT_RU_EXECUTION`	执行对象（流程实例、分支）
	`ACT_RU_TASK`	运行中的任务（对应`TaskEntity`）
	`ACT_RU_VARIABLE`	运行时变量
	`ACT_RU_IDENTITYLINK`	任务参与者关系
	`ACT_RU_JOB`	定时/异步作业
历史	`ACT_HI_PROCINST`	历史流程实例
	`ACT_HI_TASKINST`	历史任务实例
	`ACT_HI_ACTINST`	历史活动实例（每个节点）
	`ACT_HI_VARINST`	历史变量
身份	`ACT_ID_USER` / `ACT_ID_GROUP`	用户/组（可选，常与外部系统集成）

七、对象关系图解

text

ProcessDefinitionEntity (1) ──► 包含多个 ──► TaskDefinition (N)
        │
        │ 实例化
        ▼
ProcessInstance ──► 当前节点 ──► TaskEntity (引用TaskDefinition)
        │                               │
        │                               └─ 对应 ACT_RU_TASK
        ▼
Execution (子分支)

八、注意事项

TaskDefinition 是静态定义，描述了任务应该“长什么样”；TaskEntity 是运行时实例，记录了任务“当前状态”。
通常情况下不需要直接操作 ProcessDefinitionEntity 和 TaskEntity，使用 ProcessDefinition 和 Task 接口即可。
所有 Entity 后缀的类（如 TaskEntity）都是 MyBatis 映射的持久化对象，直接操作可能绕过缓存/校验，不推荐在业务代码中使用。

九、实际流程举例：请假流程各阶段使用的对象

流程定义（BPMN）

xml

<process id="leaveProcess" name="请假流程">
  <startEvent id="start" />
  <userTask id="applyTask" name="填写请假单" assignee="${applicant}" />
  <userTask id="approveTask" name="部门经理审批" assignee="manager" />
  <endEvent id="end" />
</process>

部署后的流程定义ID：leaveProcess:1:101

阶段一：部署流程定义

操作	使用的API/类	核心对象	数据库表
加载BPMN文件并部署	`RepositoryService.createDeployment().addClasspathResource().deploy()`	`Deployment`, `ProcessDefinition`, `ProcessDefinitionEntity`, `ActivityImpl`	`ACT_RE_DEPLOYMENT`, `ACT_RE_PROCDEF`, `ACT_GE_BYTEARRAY`

内部过程：

解析BPMN文件生成 BpmnModel
创建 ProcessDefinitionEntity（流程定义的运行时蓝图）
为每个节点（startEvent, applyTask, approveTask, endEvent）创建 ActivityImpl 对象，并存储于 ProcessDefinitionEntity 中
其中 applyTask 和 approveTask 的 ActivityImpl 内部包含 TaskDefinition（存储assignee等任务属性）

阶段二：启动流程实例

java

runtimeService.startProcessInstanceByKey("leaveProcess", "LEAVE-001");

使用的API/类	核心对象	数据库表
`RuntimeService.startProcessInstanceByKey`	`ProcessInstance`, `Execution`, `ActivityImpl`（起始节点）	`ACT_RU_EXECUTION`, `ACT_RU_TASK`, `ACT_RU_VARIABLE`（如有）

详细步骤与对象：

创建根执行对象：引擎生成一个 Execution 对象（实现类 ExecutionImpl），同时它也是 ProcessInstance 接口的实现。
- 插入 ACT_RU_EXECUTION，ID_ = 2001，PROC_INST_ID_ = 2001，IS_PROCESS_INSTANCE_ = 1
获取起始节点的 ActivityImpl：从 ProcessDefinitionEntity 中根据 startEvent 的id找到对应的 ActivityImpl。
执行起始节点行为：调用 startEvent 的 ActivityImpl 所绑定的 ActivityBehavior（NoneStartEventActivityBehavior），将执行流转到第一个用户任务 applyTask。
创建第一个用户任务：引擎找到 applyTask 对应的 ActivityImpl，其内部包含 TaskDefinition。根据 TaskDefinition 中的assignee表达式（${applicant}）解析出办理人（假设流程变量中传入了applicant=张三），创建 TaskEntity 对象。
- 插入 ACT_RU_TASK，ID_ = 3001，TASK_DEF_KEY_ = 'applyTask'，ASSIGNEE_ = '张三'，EXECUTION_ID_ = 2001，PROC_INST_ID_ = 2001

此时产生的对象：

ProcessInstance（根 ExecutionImpl，ID=2001）
TaskEntity（ID=3001）
两个 ActivityImpl 被引用：起始节点和 applyTask

阶段三：办理第一个任务（填写请假单）

java

taskService.complete("3001");

使用的API/类	核心对象	数据库表
`TaskService.complete`	`TaskEntity`（被完成的任务）, `DelegateTask`, `ActivityImpl`（当前节点）, `Execution`	`ACT_RU_TASK`（删除原任务），可能产生 `ACT_HI_TASKINST`, `ACT_HI_ACTINST`

详细步骤：

查询任务：taskService.createTaskQuery().taskId("3001") 返回 TaskEntity 对象（实际上包含对 ActivityImpl 的引用）。
调用完成任务：
- 引擎删除 ACT_RU_TASK 中 ID=3001 的记录
- 将任务数据归档到 ACT_HI_TASKINST 和 ACT_HI_ACTINST
- 获取当前任务对应的 ActivityImpl（即 applyTask），调用其 ActivityBehavior（UserTaskActivityBehavior）的 leave 方法
流转到下一个节点：根据 applyTask 的出边（transition），找到下一个节点 approveTask 的 ActivityImpl，执行其行为。
创建第二个任务：根据 approveTask 的 ActivityImpl 中的 TaskDefinition（assignee固定为manager），创建新的 TaskEntity。
- 插入 ACT_RU_TASK，ID_ = 3002，ASSIGNEE_ = 'manager'，EXECUTION_ID_ = 2001（同一个执行对象）

此时对象变化：

旧的 TaskEntity（3001）已被删除（历史表中保留）
新的 TaskEntity（3002）被创建
Execution（根执行对象）的当前活动节点变为 approveTask 对应的 ActivityImpl
ActivityImpl（applyTask 和 approveTask）始终存在于 ProcessDefinitionEntity 中，被引用

阶段四：办理第二个任务（经理审批）

java

taskService.complete("3002");

使用的API/类	核心对象	数据库表
`TaskService.complete`	`TaskEntity`, `DelegateTask`, `ActivityImpl`（当前节点）, `Execution`	`ACT_RU_TASK`（删除最后任务），`ACT_RU_EXECUTION`（删除根执行），`ACT_HI_PROCINST`, `ACT_HI_TASKINST`, `ACT_HI_ACTINST`

详细步骤：

完成 approveTask，引擎删除 ACT_RU_TASK 中 ID=3002 的记录。
获取 approveTask 对应的 ActivityImpl，执行其行为，流转到 endEvent。
执行 endEvent 的 ActivityImpl 行为（NoneEndEventActivityBehavior），结束流程实例。
清理运行时数据：
- 删除 ACT_RU_EXECUTION 中 PROC_INST_ID_ = 2001 的所有记录（根执行对象）
- 删除 ACT_RU_VARIABLE 中该实例的变量（如有）
写入历史数据：
- ACT_HI_PROCINST 插入一条记录，记录开始时间、结束时间、businessKey=LEAVE-001 等
- ACT_HI_TASKINST 已有两条任务历史记录
- ACT_HI_ACTINST 记录每个活动的执行轨迹（包括 startEvent, applyTask, approveTask, endEvent）

此时运行时不再有该流程实例的任何数据。所有流程定义对象（ProcessDefinitionEntity, ActivityImpl, TaskDefinition）仍然保留在缓存中，可供新的流程实例使用。

对象生命周期总结表

对象	创建时机	销毁/清理时机	存储位置
`ProcessDefinitionEntity`	部署流程定义	流程定义被删除或引擎重启（缓存可重新加载）	内存缓存 + `ACT_RE_PROCDEF`
`ActivityImpl`	部署流程定义（解析BPMN时）	同 `ProcessDefinitionEntity`	内存缓存（作为`ProcessDefinitionEntity`的一部分）
`TaskDefinition`	部署流程定义（解析用户任务时）	同 `ProcessDefinitionEntity`	内存缓存（被`ActivityImpl`引用）
`Deployment`	部署流程定义	流程定义被删除	`ACT_RE_DEPLOYMENT`
`Execution` / `ProcessInstance`	启动流程实例	流程实例结束	`ACT_RU_EXECUTION`（运行时）<br>`ACT_HI_PROCINST`（历史）
`TaskEntity`	流程流转到用户任务时	任务完成时	`ACT_RU_TASK`（运行时）<br>`ACT_HI_TASKINST`（历史）
`DelegateTask`	任务监听器或办理操作中	临时对象，方法结束后可被GC	无持久化

一句话总结

静态蓝图：ProcessDefinitionEntity 包含所有 ActivityImpl（每个节点一个），用户任务的 ActivityImpl 包含 TaskDefinition。
运行时实例：ProcessInstance（由 ExecutionImpl 实现）代表一次流程执行，TaskEntity 代表当前待办任务，它们都引用了对应的 ActivityImpl 来获取节点行为定义。

Activiti 常用类、API 与数据库表笔记 ​

一、核心引擎与服务 ​

二、流程定义相关（Repository） ​

三、流程实例与执行相关（Runtime） ​

四、任务相关（Runtime + History） ​

五、常用API示例（Java） ​

1. 部署流程 ​

2. 启动流程实例 ​

3. 查询并办理任务 ​

4. 获取流程定义实体 ​

六、核心数据库表清单 ​

七、对象关系图解 ​

八、注意事项 ​

九、实际流程举例：请假流程各阶段使用的对象 ​

流程定义（BPMN） ​

阶段一：部署流程定义 ​

阶段二：启动流程实例 ​

阶段三：办理第一个任务（填写请假单） ​

阶段四：办理第二个任务（经理审批） ​

对象生命周期总结表 ​

一句话总结 ​

Activiti 常用类、API 与数据库表笔记

一、核心引擎与服务

二、流程定义相关（Repository）

三、流程实例与执行相关（Runtime）

四、任务相关（Runtime + History）

五、常用API示例（Java）

1. 部署流程

2. 启动流程实例

3. 查询并办理任务

4. 获取流程定义实体

六、核心数据库表清单

七、对象关系图解

八、注意事项

九、实际流程举例：请假流程各阶段使用的对象

流程定义（BPMN）

阶段一：部署流程定义

阶段二：启动流程实例

阶段三：办理第一个任务（填写请假单）

阶段四：办理第二个任务（经理审批）

对象生命周期总结表

一句话总结