告别杂乱报表！手把手教你为若依(RuoYi)前后端分离项目添加Excel智能合并行功能

若依(RuoYi)前后端分离项目Excel智能合并行功能深度实践

在企业级管理系统开发中，数据导出是高频需求场景。当面对包含大量重复分组数据（如按部门、日期分类）的报表时，传统导出方式会产生大量冗余内容，严重影响报表的专业性和可读性。本文将基于若依(RuoYi)前后端分离框架，完整呈现一套Excel智能合并行解决方案。

1. 需求分析与技术选型

1.1 典型业务场景痛点

在CRM、ERP等系统中，我们经常遇到这样的数据导出需求：

• 销售报表按订单号分组显示商品明细
• 考勤统计按部门合并相同日期记录
• 库存流水按商品ID合并相同操作类型

原始导出效果存在三大核心问题：

1. 视觉冗余：相同分组值重复显示，占用大量空间
2. 信息割裂：人工合并易出错，破坏数据关联性
3. 维护困难：每次调整需重新处理Excel模板

1.2 技术实现方案对比

本方案选择基于POI的后端合并策略，因其具有：

• 动态适应：自动识别重复项
• 配置灵活：注解驱动合并规则
• 一次开发：全项目复用

2. 核心实现原理剖析

2.1 合并行算法设计

合并行的核心逻辑是相邻行值比对，关键技术点包括：

1. 值相等判断：处理各类数据类型（字符串、数字、日期等）
2. 合并区域计算：记录连续相同值的起始/结束行号
3. 样式继承：合并后单元格保持原有样式

// 核心合并逻辑代码片段 if (value.equals(value_previous)) { if (this.mergeLine_start == 0) { this.mergeLine_start = thisLine - 1; } this.mergeLine_end = thisLine; } else { if (this.mergeLine_start != 0 && this.mergeLine_end != 0) { if (this.mergeLine_start != this.mergeLine_end) { // 执行实际合并操作 CellRangeAddress region = new CellRangeAddress( this.mergeLine_start, this.mergeLine_end, column, column); sheet.addMergedRegion(region); } this.mergeLine_start = 0; this.mergeLine_end = 0; } }

2.2 注解驱动配置

扩展若依原有的@Excel注解，新增mergeLine属性：

@Excel(name = "订单编号", mergeLine = "0,6,7") // 合并第1、7、8列 private String orderNo;

参数说明：

• 多列支持：逗号分隔要合并的列索引（从0开始）
• 主键原则：建议选择具有明确分组意义的列作为主合并列

2.3 性能优化要点

1. 批量处理：避免单行操作，利用POI的批处理机制
2. 样式缓存：提前创建样式对象，减少重复构建
3. 内存控制：对于大数据量使用SXSSFWorkbook模式

提示：万级以上数据导出时，建议增加分页合并处理，避免OOM

3. 完整实现步骤

3.1 环境准备

确保项目包含以下依赖：

<!-- POI --> <dependency> <groupId>org.apache.poi</groupId> <artifactId>poi</artifactId> <version>5.2.2</version> </dependency> <dependency> <groupId>org.apache.poi</groupId> <artifactId>poi-ooxml</artifactId> <version>5.2.2</version> </dependency>

3.2 注解扩展

在若依的Excel注解类中添加新属性：

public @interface Excel { // ...原有属性 String mergeLine() default ""; // 新增合并行配置 }

3.3 工具类增强

改造ExcelUtil类，主要新增功能：

1. 合并状态跟踪：记录当前合并区域
2. 边界处理：最后一批数据的合并提交
3. 异常处理：合并冲突时的回滚机制

关键修改点：

public class ExcelUtilMerge<T> { private int mergeLine_start = 0; private int mergeLine_end = 0; // 在fillExcelData方法末尾添加 if (mergeLine_start != 0 && mergeLine_end != 0) { // 提交最后的合并区域 executeMerge(); } }

3.4 前端对接

保持原有导出接口不变，合并逻辑完全后端实现：

// 前端调用示例 exportExcel() { this.$confirm('确认导出所有数据?', "警告", { confirmButtonText: "确定", cancelButtonText: "取消", type: "warning" }).then(() => { this.loading = true; exportData(this.queryParams).then(response => { this.download(response.msg); this.loading = false; }) }) }

4. 高级应用场景

4.1 多级合并策略

对于需要多级分组的情况（如先按部门再按日期），可采用：

1. 复合主键：合并多列值的哈希结果
2. 顺序处理：先处理大分组再处理子分组

// 多列联合判断示例 String compositeKey = vo.getDept() + "|" + vo.getDate(); if (compositeKey.equals(prevCompositeKey)) { // 执行合并 }

4.2 动态合并配置

通过DTO实现运行时合并规则配置：

@Data public class ExportConfigDTO { private List<Integer> mergeColumns; private boolean mergeEnabled; } // 在Controller中动态接收配置 @PostMapping("/export") public void export(@RequestBody ExportConfigDTO config) { // 应用配置到导出逻辑 }

4.3 样式自定义

合并后单元格的样式处理建议：

1. 边框优化：合并后只保留外边框
2. 居中显示：合并内容垂直居中
3. 背景色标记：不同分组使用交替底色

CellStyle mergedStyle = wb.createCellStyle(); mergedStyle.setAlignment(HorizontalAlignment.CENTER); mergedStyle.setVerticalAlignment(VerticalAlignment.CENTER); mergedStyle.setBorderBottom(BorderStyle.THIN); cell.setCellStyle(mergedStyle);

5. 效果对比与性能数据

5.1 视觉对比示例

合并前：

合并后：

5.2 性能测试数据

测试环境：Intel i7-10700, 16GB RAM, 导出1万条记录

注意：实际性能损耗主要来自POI的合并区域计算，建议合并列控制在5个以内

6. 异常处理与调试技巧

6.1 常见问题排查

1. 合并错位：

   • 检查列索引是否从0开始计数
   • 验证数据排序是否符合预期

2. 样式丢失：

   • 确认合并后重新应用样式
   • 检查样式缓存是否被意外修改

3. 性能骤降：

   • 检查是否在循环中重复创建样式
   • 确认是否启用SXSSF模式处理大数据

6.2 调试日志配置

建议增加以下日志输出点：

log.debug("合并区域: {}行到{}行的{}列", mergeLine_start, mergeLine_end, column);

日志级别建议配置：

# application.yml logging: level: com.ruoyi.common.utils.poi: DEBUG

7. 工程化建议

7.1 组件封装

将合并逻辑抽象为独立模块：

ruoyi-common └── src/main/java/com/ruoyi/common/utils/poi ├── ExcelMergeStrategy.java # 合并策略接口 ├── SimpleMergeStrategy.java # 基础实现 └── ChainMergeStrategy.java # 多列链式合并

7.2 单元测试覆盖

重点测试场景：

1. 空数据集合
2. 单条记录边界情况
3. 全部记录相同值的极端情况
4. 交替不同的数据模式

测试示例：

@Test public void testSingleColumnMerge() { List<DemoData> list = Arrays.asList( new DemoData("A100", "北京"), new DemoData("A100", "北京"), new DemoData("B200", "上海") ); ExcelUtilMerge<DemoData> util = new ExcelUtilMerge<>(DemoData.class); util.exportExcel(list, "测试合并"); // 验证合并区域 Sheet sheet = util.getSheet(); assertEquals(1, sheet.getNumMergedRegions()); }

7.3 文档沉淀

建议在项目Wiki中记录：

1. 注解使用示例
2. 性能优化checklist
3. 常见问题解决方案
4. 版本兼容性说明

在若依实际项目中，该方案已稳定支持日均300+次导出操作。一个特别实用的技巧是：对于需要合并的日期列，建议先统一格式化后再进行合并判断，避免因时间戳精度差异导致合并失败