Flowable 历史模块（History）

Flowable 历史模块History学习笔记一、核心概念1. 历史模块定义历史模块是 Flowable 中捕获流程执行过程中发生的事件并永久存储的核心组件。与运行时数据ACT_RU_*表的区别流程实例完成后运行时数据会被删除而历史数据会持续保留用于审计、统计、追溯等场景。核心价值最小化对运行时数据的访问依赖保障流程执行性能同时支持全链路数据追溯。2. 6种核心历史实体历史实体类核心含义关联数据库表HistoricProcessInstances存储当前和已完成的流程实例信息如启动时间、结束时间、持续时长等ACT_HI_PROCINSTHistoricVariableInstances存储流程变量或任务变量的最新值ACT_HI_VARINSTHistoricActivityInstances存储流程中单个活动节点的执行信息如活动类型、开始/结束时间、负责人等ACT_HI_ACTINSTHistoricTaskInstances存储当前和已完成/删除的任务实例信息如任务名称、受理人、处理时长等ACT_HI_TASKINSTHistoricIdentityLinks存储任务或流程实例上的身份链接信息如用户与任务的关联、组与流程的关联ACT_HI_IDENTITYLINKHistoricDetails存储与流程/活动/任务实例相关的详细信息如变量更新记录、表单属性提交记录ACT_HI_DETAIL二、历史查询 APIHistoryService所有历史数据查询均通过HistoryService提供的方法构建支持多条件组合、排序和分页核心查询方法及示例如下1. 历史流程实例查询HistoricProcessInstanceQuery核心功能查询流程实例的历史记录支持按流程定义、状态已完成/未完成、时间范围、持续时长等条件筛选。示例代码// 示例1查询已完成的、流程定义ID为XXX的流程中耗时最长的10个实例分页 historyService.createHistoricProcessInstanceQuery() .finished() // 筛选已完成的流程实例 .processDefinitionId(XXX) // 指定流程定义ID .orderByProcessInstanceDuration().desc() // 按持续时长降序排序 .listPage(0, 10); // 分页查询页码0每页10条 // 示例2查询指定业务KEY的流程实例历史 historyService.createHistoricProcessInstanceQuery() .processInstanceBusinessKey(BUSINESS-2025-001) .list();2. 历史变量实例查询HistoricVariableInstanceQuery核心功能查询流程变量或任务变量的最新历史值支持按流程实例ID、任务ID、变量名称等条件筛选。示例代码// 查询ID为XXX的已完成流程实例的所有历史变量按变量名降序排序 historyService.createHistoricVariableInstanceQuery() .processInstanceId(XXX) // 关联流程实例ID .orderByVariableName().desc() // 按变量名排序 .list(); // 示例查询指定任务的历史变量 historyService.createHistoricVariableInstanceQuery() .taskId(TASK-123) .variableName(approveResult) // 筛选变量名 .list();3. 历史活动实例查询HistoricActivityInstanceQuery核心功能查询流程中单个活动如服务任务、用户任务、网关等的执行历史支持按活动类型、流程定义、状态等条件筛选。示例代码// 查询流程定义ID为XXX的流程中已完成的最后一个serviceTask类型活动 historyService.createHistoricActivityInstanceQuery() .activityType(serviceTask) // 筛选活动类型serviceTask/userTask/gateway等 .processDefinitionId(XXX) .finished() // 已完成的活动 .orderByHistoricActivityInstanceEndTime().desc() // 按结束时间降序 .listPage(0, 1); // 取第一条最新的4. 历史详情查询HistoricDetailQuery核心功能查询变量更新记录、表单属性提交记录等详细历史信息支持按“变量更新”“表单属性”分类筛选。示例代码// 示例1查询流程实例123的所有变量更新记录按变量名升序 historyService.createHistoricDetailQuery() .variableUpdates() // 仅筛选变量更新记录 .processInstanceId(123) .orderByVariableName().asc() .list(); // 示例2查询流程实例123的所有表单属性提交记录 historyService.createHistoricDetailQuery() .formProperties() // 仅筛选表单属性记录 .processInstanceId(123) .orderByVariableName().asc() .list(); // 示例3查询任务123的所有本地变量更新记录任务级变量非流程级 historyService.createHistoricDetailQuery() .variableUpdates() .taskId(123) // 关联任务ID .orderByVariableName().asc() .list();5. 历史任务实例查询HistoricTaskInstanceQuery核心功能查询任务的历史记录已完成/删除的任务支持按受理人、处理时长、删除原因等条件筛选。示例代码// 示例1查询所有已完成且耗时最长的10个任务实例 historyService.createHistoricTaskInstanceQuery() .finished() // 已完成的任务 .orderByHistoricTaskInstanceDuration().desc() // 按处理时长降序 .listPage(0, 10); // 示例2查询删除原因包含invalid且最后受理人为kermit的任务 historyService.createHistoricTaskInstanceQuery() .finished() .taskDeleteReasonLike(%invalid%) // 模糊匹配删除原因 .taskAssignee(kermit) // 指定受理人 .listPage(0, 10);6. 历史身份链接查询核心功能查询任务或流程实例的身份关联历史如用户、组与任务的关联记录。示例代码// 查询任务123的所有历史身份链接 historyService.getHistoricIdentityLinksForTask(123); // 查询流程实例123的所有历史身份链接 historyService.getHistoricIdentityLinksForProcessInstance(123);三、历史配置History Level1. 配置方式支持编程式配置、XML配置flowable.cfg.xml/Spring 上下文、属性配置application.properties三种方式。示例1编程式配置ProcessEngine processEngine ProcessEngineConfiguration .createProcessEngineConfigurationFromResourceDefault() .setHistory(HistoryLevel.AUDIT.getKey()) // 设置历史级别 .buildProcessEngine();示例2XML配置flowable.cfg.xmlbean idprocessEngineConfiguration classorg.flowable.engine.impl.cfg.StandaloneInMemProcessEngineConfiguration property namehistory valueaudit / !-- 历史级别 -- !-- 其他配置 -- /bean示例3Spring 属性配置application.propertiesflowable.historyaudit2. 4种历史级别从低到高历史级别核心特性性能适用场景none不存储任何历史数据最优仅需运行流程无需追溯/审计activity存储流程实例、活动实例流程结束时复制顶层流程变量最新值到历史变量较好简单流程追溯无需详细信息audit默认级别存储流程实例、活动实例、同步变量值、表单属性用户交互可追溯中等审计、常规追溯推荐生产环境full存储 audit 级所有信息 所有变量更新记录最详细较差复杂追溯、全链路变量审计注意事项历史级别可在引擎重启时修改无需担心数据库兼容性5.11版本不再依赖数据库中ACT_GE_PROPERTY表的historyLevel属性。级别越高历史数据越详细但数据库存储压力和查询性能开销越大需根据业务需求权衡。四、审计场景应用当历史级别配置为audit及以上时支持表单提交数据的全链路审计核心能力如下1. 表单数据审计通过FormService.submitStartFormData()或FormService.submitTaskFormData()提交的表单属性会自动记录到历史详情中。可通过HistoricDetailQuery.formProperties()查询表单提交记录追溯用户交互数据。2. 提交用户审计提交表单前通过IdentityService.setAuthenticatedUserId(String userId)设置认证用户该用户ID会被记录启动表单通过HistoricProcessInstance.getStartUserId()获取提交用户。任务表单通过HistoricActivityInstance.getAssignee()获取提交用户。五、历史数据清理默认情况下历史数据会永久存储可能导致数据库膨胀影响查询性能。Flowable 6.5.0 提供自动清理和手动清理两种机制。1. 自动历史清理推荐配置方式支持编程式、XML、属性配置核心参数包括是否启用、清理周期、清理阈值流程结束时间。示例1编程式配置ProcessEngine processEngine ProcessEngineConfiguration .createProcessEngineConfigurationFromResourceDefault() .setEnableHistoryCleaning(true) // 启用自动清理 .setHistoryCleaningTimeCycleConfig(0 0 1 * * ?) // 清理周期Cron表达式默认每天凌晨1点 .setCleanInstancesEndedAfter(Duration.ofDays(365)) // 清理365天前结束的流程实例 .buildProcessEngine();示例2Spring 属性配置flowable.enable-history-cleaningtrue # 启用自动清理 flowable.history-cleaning-after365d # 清理365天前的历史数据 flowable.history-cleaning-cycle0 0 1 * * ? # 每天凌晨1点执行核心特性基于 Flowable 批处理机制批量删除历史流程实例及关联数据避免单次删除压力。清理记录存储在批处理表中支持监控清理进度。2. 手动删除历史数据通过HistoryService手动构建查询条件批量删除历史数据。示例代码// 示例删除1年前结束的所有历史流程实例及关联数据批量大小10 int batchSize 10; // 每批删除10个流程实例 Calendar cal new GregorianCalendar(); cal.set(Calendar.YEAR, cal.get(Calendar.YEAR) - 1); // 1年前的当前时间 historyService.createHistoricProcessInstanceQuery() .finishedBefore(cal.getTime()) // 筛选1年前结束的流程 .deleteSequentiallyUsingBatch(batchSize, Custom Delete Batch); // 批量删除指定批处理名称六、关键注意事项历史数据关联性删除历史流程实例时会自动删除关联的历史活动、历史任务、历史变量、历史详情等数据无需手动级联删除。性能优化高频查询字段如PROC_INST_ID_、TASK_ID_、END_TIME_建议创建索引。历史数据量大时优先使用分页查询listPage避免全表扫描。变量存储HistoricVariableInstances仅存储变量最新值变量更新记录需通过HistoricDetailQuery.variableUpdates()查询。任务本地变量setVariableLocal的历史记录需通过taskId关联查询。历史级别选择生产环境优先使用audit级别兼顾追溯需求和性能非审计场景可使用activity级别减少存储开销。