Flowable 案例迁移 详解

Flowable 案例迁移是指将基于旧版 Activiti 或早期 Flowable 版本（如 Flowable 5/6）开发的流程应用，升级迁移到新版 Flowable 6+ 或 Flowable 7+ 的过程。迁移不仅是简单的依赖替换，还涉及引擎行为兼容性、API变更、模型调整、数据迁移及周边生态适配。以下是迁移的核心要点与详细步骤：

---

一、迁移驱动因素

1. 技术支持：旧版（Activiti 5/6, Flowable 5）停止维护，安全风险增加。
2. 性能优化：Flowable 6/7+ 在异步处理、批量操作、数据库查询上大幅优化。
3. 新特性需求：如更强大的 DMN 支持、改进的 REST API、云原生部署（Kubernetes）、事件驱动架构（Event Registry）。
4. 生态整合：更好支持 Spring Boot 2/3、Jakarta EE、Quarkus 等现代框架。

---

二、迁移前准备

1. 环境评估

• 当前版本：明确源版本（如 Activiti 5.22.0, Flowable 6.4.1）。
• 依赖分析：检查 pom.xml/build.gradle 中的引擎模块（activiti-engine → flowable-engine）。
• 数据库类型：MySQL/Oracle/PostgreSQL 等（Flowable 7+ 默认使用 flowable-common-engine 抽象层）。

2. 兼容性检查

• 查阅 Flowable 官方迁移指南。
• 重点关注 API 变更（如 RuntimeService.startProcessInstanceByKey() 返回值类型变化）、配置项差异（如异步执行器配置）。

3. 备份关键数据

• 数据库全量备份：ACT_* 表（运行中流程、历史数据、身份信息）。
• 流程定义文件：所有 .bpmn20.xml / .dmn 文件。
• 自定义代码：监听器（Listeners）、委托类（Delegates）、表单解析器等。

---

三、迁移核心步骤

1. 依赖升级

<!-- 旧版 Activiti 依赖 -->
<dependency>
  <groupId>org.activiti</groupId>
  <artifactId>activiti-engine</artifactId>
  <version>5.22.0</version>
</dependency>

<!-- 新版 Flowable 依赖（以 7.0.0 为例） -->
<dependency>
  <groupId>org.flowable</groupId>
  <artifactId>flowable-engine</artifactId>
  <version>7.0.0</version>
</dependency>

• 注意：同时升级相关模块（如 flowable-spring-boot-starter, flowable-dmn-engine）。

2. 流程模型迁移

• BPMN 2.0 文件：
  • Flowable 完全兼容 Activiti 的 BPMN 规范。
  • 使用 Flowable Modeler 或 Eclipse Designer 重新打开验证，修复警告（如命名空间更新）：

    <!-- 旧 Activiti 命名空间 -->
    xmlns:activiti="http://activiti.org/bpmn"
    
    <!-- 新 Flowable 命名空间 -->
    xmlns:flowable="http://flowable.org/bpmn"
    

• DMN 1.3 文件：直接兼容，无需修改。

3. 代码适配

• API 变更：

  // Activiti 5.x
  ProcessInstance instance = runtimeService.startProcessInstanceByKey("loanProcess");
  
  // Flowable 6/7 (返回 ProcessInstance 而非 Execution)
  ProcessInstance instance = runtimeService.createProcessInstanceBuilder()
                                         .processDefinitionKey("loanProcess")
                                         .start();
  

• Service 接口变更：
  • FormService 被拆分为 FlowableFormService。
  • 历史服务方法前缀从 createXXXQuery 改为 createXXXQuery（如 historyService.createHistoricProcessInstanceQuery()）。
• 事件监听器：
  • 包路径更新：org.activiti.engine.delegate.event → org.flowable.common.engine.api.delegate.event。

4. 数据库迁移

• 自动升级：Flowable 首次启动时检测 ACT_GE_PROPERTY 中的 schema.version，自动执行 DDL 升级脚本（需确保数据库用户有 DDL 权限）。
• 手动干预：
  • 检查 flowable-engine-xxx.jar!/org/flowable/db/upgrade 中的升级脚本。
  • 复杂场景（如跨大版本升级）需按顺序执行脚本（如 6.3_to_6.4.sql → 6.4_to_6.5.sql）。
• 数据一致性校验：

  -- 检查未完成流程实例是否正常
  SELECT * FROM ACT_RU_EXECUTION WHERE PROC_INST_ID_ IN (SELECT PROC_INST_ID_ FROM ACT_HI_PROCINST WHERE END_TIME_ IS NULL);
  

5. 配置调整

• Spring Boot 配置：

  # application.yml
  flowable:
    async-executor-activate: true  # 启用异步执行器
    database-schema-update: true   # 启动时更新表结构
    history-level: audit           # 历史记录级别（none/activity/audit/full）
  

• 日志框架：Flowable 7+ 默认使用 SLF4J，移除 Log4j 依赖。

---

四、迁移后验证

1. 单元测试覆盖：
   • 执行所有流程单元测试，重点验证：
     • 流程启动/终止
     • 用户任务分配/完成
     • 网关决策（分支/并行）
     • 服务任务/监听器逻辑
2. 历史数据兼容性：
   • 确保运行中的流程实例（ACT_RU_* 表）迁移后能继续执行。
   • 验证历史流程实例数据（ACT_HI_* 表）查询正常。
3. 性能压测：
   • 对比迁移前后关键接口的 TPS 和响应时间（如流程启动、任务查询）。
4. 监控集成：
   • 整合 Prometheus + Grafana 监控 Flowable 指标（如任务积压数量、异步作业队列深度）。

---

五、常见问题与解决方案

问题类型	表现	解决方案
API 不兼容	编译错误或运行时 NoSuchMethodError	使用 Flowable 官方迁移工具扫描代码，替换废弃 API。
流程无法启动	启动后立即结束或卡在第一个节点	检查 BPMN 文件中的命名空间和服务任务类路径。
历史数据丢失	迁移后历史记录查询为空	确认 flowable.history-level 配置级别 ≥ audit，并执行历史表升级脚本。
异步任务积压	ACT_RU_JOB 表任务堆积	调整 flowable.async-executor.core-pool-size 和 queue-size。
表单渲染失败	动态表单无法加载或提交	迁移自定义表单解析器，适配 FlowableFormService 接口。

---

六、迁移工具推荐

1. Flowable Upgrade Helper：
   官方提供的扫描工具，检测代码中的废弃 API 和配置项。
2. Liquibase/Flyway：
   管理数据库升级脚本，控制多环境一致。
3. Spring Boot Actuator：
   监控迁移后应用健康状态（/actuator/health 和 /actuator/flowable）。

---

七、关键注意事项

1. 零停机迁移：
   • 使用数据库复制技术（如 MySQL Binlog）实现双写，逐步切流。
2. 回滚方案：
   • 备份旧版数据库和应用，确保 15 分钟内可回退。
3. 依赖冲突：
   • 排除传递依赖（如旧版 mybatis、spring-core）：

     <exclusions>
       <exclusion>
         <groupId>org.activiti</groupId>
         <artifactId>activiti-spring</artifactId>
       </exclusion>
     </exclusions>
     

4. 许可证审查：
   • Flowable 7+ 部分高级特性（如批量操作 REST API）需商业许可。

---

通过系统化的评估、渐进式改造和严格验证，Flowable 案例迁移可显著提升流程平台的性能和可维护性。务必在非生产环境充分测试，避免直接升级线上系统！