若依框架Excel行合并功能深度实战：从注解配置到源码改造全解析

在企业级应用开发中，数据导出是高频需求场景。当面对订单明细、财务报表等需要按主键字段合并展示的数据时，常规的Excel导出往往会导致重复数据冗余，严重影响报表可读性。若依（RuoYi）作为国内流行的快速开发框架，其内置的Excel工具类虽能满足基础导出需求，但面对行合并等高级功能时，开发者往往需要自行扩展。本文将深入剖析如何基于若依框架实现动态行合并功能，提供从注解配置到源码改造的完整解决方案。

1. 行合并需求分析与技术方案选型

1.1 典型业务场景剖析

在以下业务场景中，Excel行合并功能显得尤为重要：

• 订单管理系统：同一订单号下包含多个商品明细，需要合并订单号列展示
• 财务报表系统：相同科目代码的多条记录需要合并显示
• 库存管理系统：同一仓库下的不同批次库存需要合并仓库名称列

传统解决方案通常采用以下两种方式：

1. 前端合并：在浏览器端使用SheetJS等库处理

   • 优点：不依赖后端实现
   • 缺点：大数据量时性能差，无法支持模板导出

2. 后端预处理：在服务端对数据进行分组聚合

   • 优点：导出性能稳定
   • 缺点：破坏原始数据结构，增加业务复杂度

1.2 若依框架原生导出能力分析

若依框架默认提供的ExcelUtil工具类主要具备以下特性：

// 基础导出功能示例 public AjaxResult exportExcel(List<T> list, String sheetName) { this.init(list, sheetName, Type.EXPORT); return exportExcel(); }

原生实现存在三个主要局限：

1. 不支持动态行合并
2. 无法通过注解配置合并规则
3. 合并逻辑需要硬编码实现

2. 注解驱动式合并方案实现

2.1 扩展Excel注解支持合并配置

首先需要扩展@Excel注解，增加合并行配置属性：

public @interface Excel { // 原有注解属性... /** * 合并行配置（格式："主键列,合并列1,合并列2"） */ String mergeLine() default ""; }

实际应用案例：订单导出实体配置

public class OrderExportVO { @Excel(name = "订单编号", mergeLine = "0,1,7,8") private String orderNo; @Excel(name = "商品名称") private String productName; // 其他字段... }

2.2 合并策略核心算法设计

行合并的核心算法需要解决以下关键问题：

1. 连续相同值检测：识别需要合并的连续记录
2. 动态范围计算：确定合并的起始行和结束行
3. 多列同步合并：支持根据主键列合并其他关联列

算法流程图解：

开始导出 ↓ 遍历数据行 ↓ 当前行值 == 上一行值? ├─ 是 → 记录结束行位置 └─ 否 → 执行合并操作并重置起始行 ↓ 处理最后一批待合并数据

3. 改造ExcelUtil工具类实现

3.1 关键改造点说明

在ExcelUtilMerge工具类中，主要改造集中在addCell方法：

public Cell addCell(Excel attr, Row row, T vo, Field field, int column, T vo_previous, int thisLine) { // ...原有单元格处理逻辑 // 合并行处理 String[] mergeLine = attr.mergeLine().split(","); if (mergeLine.length > 0 && !mergeLine[0].isEmpty()) { if (value.equals(value_previous)) { if (this.mergeLine_start == 0) { this.mergeLine_start = thisLine - 1; } this.mergeLine_end = thisLine; } else { executeMerge(mergeLine); } } return cell; } private void executeMerge(String[] mergeColumns) { if (this.mergeLine_start != 0 && this.mergeLine_end != 0) { for (String col : mergeColumns) { CellRangeAddress region = new CellRangeAddress( mergeLine_start, mergeLine_end, Integer.parseInt(col), Integer.parseInt(col)); sheet.addMergedRegion(region); } } resetMergeState(); }

3.2 性能优化关键点

处理大数据量导出时需注意：

1. 内存控制：使用SXSSFWorkbook（流式API）

   this.wb = new SXSSFWorkbook(500); // 保留500行在内存中

2. 批量合并：避免单次合并操作立即刷新

3. 样式复用：提前创建好单元格样式

   private Map<String, CellStyle> createStyles(Workbook wb) { // 样式预创建逻辑... }

4. 实战应用与问题排查

4.1 完整接入流程

1. 引入改造后的工具类

   • 将ExcelUtilMerge放入项目utils包
   • 保持与原ExcelUtil相同的包结构

2. 实体类注解配置

   @Excel(name = "部门", mergeLine = "0,1") private String deptName;

3. Controller层调用

   @GetMapping("/export") public void export(HttpServletResponse response) { List<OrderVO> list = orderService.list(); ExcelUtilMerge<OrderVO> util = new ExcelUtilMerge<>(OrderVO.class); util.exportExcel(list, "订单数据"); }

4.2 常见问题解决方案

问题1：合并后边框样式丢失

解决方案：在合并后重新设置区域样式

RegionUtil.setBorderBottom(BorderStyle.THIN, region, sheet, wb);

问题2：大数据量导出OOM

优化方案：

• 增加分页查询逻辑
• 调整SXSSFWorkbook的windowSize参数
• 添加JVM参数：-XX:+UseG1GC -Xmx1024m

问题3：合并列索引错误

注意要点：

• Excel列索引从0开始计算
• 合并配置中的列号需与导出字段顺序一致
• 可使用fields.stream().sorted()确保字段顺序

5. 高级扩展与最佳实践

5.1 动态合并策略进阶

对于更复杂的业务场景，可扩展支持：

1. 条件合并：基于业务规则动态判断是否合并

   if (shouldMerge(vo, vo_previous)) { // 执行合并逻辑 }

2. 跨Sheet合并：处理分Sheet导出时的连续合并

3. 分组合并：支持按多个字段组合条件合并

5.2 可视化辅助工具开发

为提升配置效率，可以开发：

1. 注解生成器：根据数据库表结构自动生成注解配置

2. 合并预览功能：在导出前提供Web端预览

3. 性能监控面板：实时显示导出耗时和内存占用

// 简单的性能监控示例 StopWatch watch = new StopWatch(); watch.start("export"); // 执行导出... watch.stop(); log.info("导出耗时：{}ms", watch.getTotalTimeMillis());

在实际项目中使用行合并功能时，建议先在小数据量场景验证合并效果，再逐步扩展到全量数据。对于超大规模数据（10万行以上），可考虑采用分批次导出策略，或使用专门的报表引擎处理。