Warm-Flow 1.7.0工作流引擎全指南：从入门到精通

文档概述

本文档是针对Dromara Warm-Flow工作流引擎1.7.0版本的全面技术指南，该版本于2025年4月发布，带来了多项重要功能更新，包括撤销、驳回和拿回等实用功能。Warm-Flow作为国产轻量级工作流引擎，以简洁轻量、灵活扩展为核心优势，适合中小型项目快速集成企业级工作流能力。

一、环境准备与安装

1. 版本更新与依赖配置

重要提示 ：当前最新版本为 1.7.0（2025年4月发布），相比原文档中1.3.1版本有重大更新，建议立即升级以获取最新特性。

Maven依赖配置（更新为最新版本）

XML 复制代码

<dependency>
    <groupId>org.dromara</groupId>
    <artifactId>warm-flow-mybatis-sb-starter</artifactId>
    <version>1.7.0</version>
</dependency>

<!-- 流程设计器集成（可选） -->
<dependency>
    <groupId>org.dromara</groupId>
    <artifactId>warm-flow-plugin-ui-sb-web</artifactId>
    <version>1.7.0</version>
</dependency>

数据库脚本更新

全量脚本 ：从官方仓库获取最新MySQL脚本：warm-flow_1.7.0.sql
升级脚本 ：如果从旧版本升级，需执行增量脚本：warm-flow_1.3.1_to_1.7.0_upgrade.sql

2. 新增功能支持

JSON格式支持（替代XML）

新版本已将XML导入导出功能改为JSON格式，推荐使用以下API：

java 复制代码

// 导入JSON格式流程定义 
defService.importJson(jsonContent); 
// 导出JSON格式流程定义 
String json = defService.exportJson(definitionId);

数据库与ORM支持扩展

新增支持：SQL Server、PostgreSQL（通过官方提供的全量脚本）
ORM框架：MyBatis-Plus扩展包（独立维护），使用方式：

XML 复制代码

<dependency>  
  <groupId>org.dromara</groupId>  
  <artifactId>warm-flow-mybatis-plus-starter</artifactId>  
  <version>1.7.0</version> 
</dependency>

3. 配置文件更新

新增全局配置项（application.yml）：

XML 复制代码

warm-flow:
  banner: true  # 是否显示banner图
  orm:
    type: mybatis-plus  # 可选：mybatis-plus, mybatis, jpa
  tenant:
    column: tenant_id  # 多租户字段名
  logic-delete:
    column: is_deleted  # 逻辑删除字段

二、核心概念与新特性

1. 流程操作新增功能

1.1 撤销功能

XML 复制代码

// 撤销任务（新增于1.7.0） 
TaskService.revoke(taskId, operator);

1.2 驳回到上一任务

XML 复制代码

// 驳回到上一个任务 
TaskService.rejectLast(taskId, operator);

1.3 拿回功能

XML 复制代码

// 拿回到最近办理的任务 
TaskService.takeBack(taskId, operator);

2. 流程设计器增强

2.1 节点扩展属性

设计器支持：节点扩展属性配置（如颜色自定义、状态标签）
实现方式 ：通过HandlerSelectService接口扩展：

XML 复制代码

public class CustomHandlerService implements HandlerSelectService {
    @Override
    public List<String> getHandlerType() {
        return Arrays.asList("用户", "角色", "部门", "自定义角色"); // 新增自定义角色类型
    }
}

2.2 流程图渲染优化

ChartService接口：新增流程图查询与渲染接口：

XML 复制代码

// 获取流程实例图表
String chartData = chartService.chartIns(instanceId);
// 获取流程定义图表
String defChart = chartService.chartDef(definitionId);

3. API重大变更

3.1 核心服务接口调整

旧API（已废弃）	新API（1.7.0推荐）	说明
insService.skipByInsId()	taskService.skipByInsId()	任务处理接口迁移至TaskService
insService.start()	taskService.start()	流程启动接口迁移
defService.importXml()	defService.importJson()	XML格式已废弃，使用JSON

3.2 新增核心API示例

java 复制代码

// 1. 部署流程（JSON格式）
String jsonContent = "{\"nodes\": [...]}";
defService.importJson(jsonContent);

// 2. 启动流程实例
TaskService taskService = applicationContext.getBean(TaskService.class);
Instance instance = taskService.start("leaveFlow", getUser())
    .variable("amount", 3)
    .variable("reason", "年度休假");

// 3. 任务审批（通过）
TaskService.skip(taskId, operator)
    .skipType(SkipType.PASS.getKey())
    .permissionFlag(Arrays.asList("role:manager"));

// 4. 撤销任务
taskService.revoke(taskId, operator);

// 5. 驳回到上一任务
taskService.rejectLast(taskId, operator);

三、进阶功能与最佳实践

1. 多租户与软删除配置

java 复制代码

@Configuration
public class WarmFlowConfig {
    @Bean
    public WarmFlowConfigurer warmFlowConfigurer() {
        return new WarmFlowConfigurer()
            .tenantColumn("tenant_id")
            .logicDeleteColumn("is_deleted")
            .logicDeleteValue("1")
            .logicNotDeleteValue("0");
    }
}

2. 监听器新特性

2.1 新增监听器类型

全局监听器：监控所有流程实例
节点监听器：针对特定节点的生命周期事件

2.2 监听器示例（新增撤销事件）

java 复制代码

@Component
public class CustomListener implements GlobalListener {
    @Override
    public void onRevoke(TaskEvent event) {
        log.info("任务被撤销: {}", event.getTaskId());
        // 自定义业务逻辑：发送通知给流程发起人
    }
}

3. 条件表达式增强

3.1 新增运算符

in：判断是否包含在集合中
matches：正则匹配
containsAll：全包含验证

3.2 示例：复杂条件表达式

java 复制代码

// 条件表达式示例：金额大于1000且部门为财务
String condition = "amount > 1000 && dept == 'finance'";

四、迁移指南与注意事项

1. 版本升级步骤

备份数据 ：执行mysqldump备份现有数据库
执行升级脚本 ：warm-flow_1.3.1_to_1.7.0_upgrade.sql
更新依赖版本：修改pom.xml中的版本号至1.7.0
替换废弃API ：
- 将insService.skipByInsId()替换为taskService.skipByInsId()
- 将XML相关操作替换为JSON API
验证功能：重点测试撤销、驳回和拿回功能

2. 常见问题解决

2.1 JSON导入失败

原因：JSON格式错误或缺少必填字段
解决：使用官方提供的JSON Schema验证工具

2.2 流程设计器空白

排查：检查warm-flow-ui依赖是否正确引入，前端路由是否配置/warm-flow-ui/**放行

2.3 多租户配置冲突

解决：确保warm-flow.tenant.column与业务系统租户字段一致

五、官方资源与支持

官方文档 ：V1.7.0 | Warm-Flow官网
演示地址 ：http://www.hhzai.top（账号：admin/admin123）
社区支持 ：QQ群 778470567
GitHub仓库 ：https://gitee.com/dromara/warm-flow

提示：建议先通过官方Demo项目快速上手，重点关注TaskServiceTest.java中的新API使用示例。对于复杂场景，可参考RuoYi-Vue-Warm-Flow集成案例中的最佳实践。