最近在做报表导出模块时需求方提了一个特别“折腾人”的要求导出的Excel列不是固定的要根据用户在前端勾选的维度动态生成。用户今天选3个门店导出的Excel就是4列明天选30个门店直接变31列。这个需求在报表后台、运营分析系统、企业管理系统里太常见了解决方案也已经很成熟——用EasyExcel做动态列导出。这篇文章我会把动态列的设计思路、横向循环生成表头与数据的方式以及我实际测试时踩过的坑都整理出来希望对正在被“表头怎么不固定啊”折磨的读者有帮助。内容偏实战适合有一定Java基础、正在做导出功能的同学参考。1. 动态列到底在解决什么问题以及为什么选EasyExcel1.1 实际业务里动态列长什么样先别急着写代码我们把场景还原清楚。动态列导出最典型的是下面两类业务。第一类是“维度枚举型”报表。比如电商大促效果对比表用户勾选了“618第一波”“618第二波”“双11预热”三个活动期导出的Excel第一列是商品名称后面每一列是一个活动期的销量。明天用户勾选了五个活动期那Excel就多出两列。这个列集合是运行时确定的根本没有办法在代码里写死一个DTO加注解去处理。第二类是“主数据驱动型”报表。最典型的就是多门店销售汇总第一列是商品后面每个门店一列门店列表来自主数据配置。今天新增了两家门店导出的列就自动增加两列。我甚至遇到过列数超过80列的需求把门店、月份、指标三个维度全部展开成一行。这类场景有一个共同特征表格的“列名集合”是一个动态列表业务数据需要按照“主记录 动态属性值”的方式横向铺开。如果你还在用传统思路写一个固定字段的OOP对象然后用ExcelProperty注解映射字段那动态列就完全没法做因为注解在编译期就确定了运行期根本改不了。1.2 为什么是EasyExcel而不是原生POI既然是Java生态里的Excel处理很多人第一反应是POI。POI并不是不能用而是做动态列这种需求时成本明显偏高。拿原生POI写动态列你需要自己维护Workbook、Sheet、Row、Cell所有单元格都要手动创建。表头合并要调addMergedRegion列宽要逐列设置数据行还要按列索引挨个set。这些代码不是写不出来而是维护起来太痛苦尤其是换了个Excel模板或者新增了分组维度大片代码要跟着改。EasyExcel是阿里开源的一个库底层虽然也是POI但做了大量封装。它有几个特点是专门“对症”动态列的支持ListListString直接作为表头列集合可以在运行期自由构建写文件时采用流式写入相对原生POI内存占用小很多大数据量场景不容易OOM表头合并、单元格样式这些高频操作通过内置策略和WriteHandler就能实现不需要每个Cell都手控。我做了一张对比表方便你直观感受对比维度原生POIEasyExcel动态表头支持需要手动建Row/Cell代码量很大直接传ListList 非常直接内存占用写大量数据时对象全在内存容易OOM流式写入内存占用明显低合并单元格手动调addMergedRegion相同表头自动合并或WriteHandler控制学习成本需要熟悉整套POI对象模型API层面主要理解Writer、WriteSheet、Head三个概念社区活跃度老牌稳定但Excel导出这块资料偏底层国内使用人数多问题基本都能搜到我们在项目里引入EasyExcel不是因为它比POI“高级”而是因为动态列场景下它能节省大量不必要的重复代码出问题也好排查。选型不用太纠结如果你的目标是“快速把一个动态报表做出来并且长期维护”EasyExcel是当前的最佳选择之一。2. 横向循环的建模思路先画表头再组织数据2.1 表头在EasyExcel里到底是什么结构做动态列第一步要改变思维不要把Excel表头想成一个二维表格在EasyExcel里表头本质上是ListListString。最外层的List代表“表头的行”内层List代表“每一行的所有列”。举个例子最简单的单层表头比如“商品名称、销量、销售额”它就是一行表头ListListString head new ArrayList(); head.add(Arrays.asList(商品名称, 销量, 销售额));如果你只需要单层表头那这个结构很简单。但实际业务里尤其是报表导出极少是单层表头。最常见的是这种带分组的两级表头商品名称华东大区华东大区华南大区1月2月1月这个表头在EasyExcel里怎么写很多人第一次会写错因为他们觉得“商品名称”下面没有子列所以第二行就不需要占位。实际上头部每一行的List长度必须完全一致否则单元格会对不齐。正确写法是这样的ListListString head new ArrayList(); ListString row0 new ArrayList(); ListString row1 new ArrayList(); row0.add(商品名称); row0.add(华东大区); row0.add(华东大区); row0.add(华南大区); row1.add(); // 商品名称这列在第二行用空字符串占位 row1.add(1月); row1.add(2月); row1.add(1月); head.add(row0); head.add(row1);注意两个细节。第一华东大区在第一行出现了两次EasyExcel会根据相邻单元格内容相同的规则把它自动合并成一个跨两列的大单元格不需要你手动调addMergedRegion。第二占位符建议用空字符串而不是null因为某些版本的EasyExcel在对null表头做处理时可能抛出空指针。这个坑我踩过后面常见问题里会细说。搞懂了这个结构你就会发现动态列的“横向循环”其实就两件事确定一共有多少列确定表头有多少行。然后把每一行的列名填进去。列名集合一旦确定了剩下的就是简单的循环填充。2.2 从业务数据到横向行的转换思路表头是“横向循环”的上半场下半场是数据行。业务系统里存的数据绝大部分是一行行明细。比如销售记录表里每条记录是一个商品在一个门店一个月份下的销量。你要导出的却是每个商品一行门店和月份展开成多列。这个转换本质上就是把纵向明细“旋转”成横向宽表。我的做法是先按固定列分组然后动态列用“维度枚举组合”作为key构建一个二维索引。举个简单例子源数据对象是SaleRecord有product、region、month、amount四个字段。要生成“商品 × (门店月份)”的横向报表就先定义一个复合key比如region _ month然后把明细折算成按product分组的map。后续循环product列表外层循环固定列内层循环动态列集合一行一行取数。核心代码大概长这样MapString, MapString, Integer productMap new LinkedHashMap(); for (SaleRecord record : records) { String key record.getRegion() _ record.getMonth(); productMap.computeIfAbsent(record.getProduct(), k - new LinkedHashMap()) .put(key, record.getAmount()); } ListString dynamicKeys new ArrayList(); for (String region : regionList) { for (String month : monthList) { dynamicKeys.add(region _ month); } } ListListObject dataRows new ArrayList(); for (Map.EntryString, MapString, Integer entry : productMap.entrySet()) { ListObject row new ArrayList(); row.add(entry.getKey()); // 固定列商品名称 for (String key : dynamicKeys) { row.add(entry.getValue().getOrDefault(key, 0)); // 动态列缺省补0 } dataRows.add(row); }这里有一个特别重要的点构建表头时的动态列顺序必须和构建数据行时的动态列顺序完全一致。我习惯把“动态列集合”抽成一个公共变量表头生成和数据行生成都遍历它而不是在两边分别写循环避免两处顺序不一致导致数据错位。数据错位这个问题在动态列场景里是最高频的问题而且很隐蔽。表头明明看着对数据也能写进去但某一列的表头和市场数据对不上。出现这种情况八成就因为表头和数据行用了两套不同的顺序逻辑。3. 实战一个可复用的动态列导出工具3.1 引入依赖与基础配置项目用的Spring Boot直接引入EasyExcel的Maven依赖。3.x是目前的主线版本功能稳定对动态表头的支持也更友好。我用的是3.3.x下面的代码都以3.x为准。dependency groupIdcom.alibaba/groupId artifactIdeasyexcel/artifactId version3.3.2/version /dependency如果你还在用2.x版本接口大体兼容但动态表头部分有些细节行为不一样比如表头占位符的处理逻辑建议升级到3.x再跑。3.2 定义通用列元数据动态列的“列”不能只是一个字符串它至少需要两个信息表头显示什么、数据按什么key取。我习惯定义一个ColumnMeta对象把列的属性封装好public class ColumnMeta { /** * 表头显示名称 */ private String headName; /** * 数据取值key对应数据Map的key */ private String fieldKey; /** * 分组名用于多级表头 */ private String groupName; /** * 列宽默认-1不设置 */ private Integer columnWidth -1; public ColumnMeta(String headName, String fieldKey) { this.headName headName; this.fieldKey fieldKey; } public ColumnMeta(String headName, String fieldKey, String groupName) { this.headName headName; this.fieldKey fieldKey; this.groupName groupName; } // getter、setter省略 }为什么要加fieldKey而不是直接传一个表头字符串是因为数据行我统一用MapString, Object承载列顺序完全由ColumnMeta列表控制而key只是取值依据。这样数据来源无论是数据库查询结果、内存对象还是第三方接口返回都能用一套逻辑处理。3.3 构建动态表头核心的横向循环构建表头时核心逻辑是判断有无分组。没有分组就是单行表头有分组就生成两行并且要处理第二行的占位符。我先贴这段工具代码再解释为什么这么写private ListListString buildHead(ListColumnMeta columns) { boolean hasGroup columns.stream().anyMatch(c - c.getGroupName() ! null); ListString row0 new ArrayList(); ListString row1 new ArrayList(); for (ColumnMeta column : columns) { if (hasGroup) { if (column.getGroupName() ! null) { row0.add(column.getGroupName()); row1.add(column.getHeadName()); } else { // 该列没有分组第一行直接显示列名第二行用空字符串占位 row0.add(column.getHeadName()); row1.add(); } } else { row0.add(column.getHeadName()); } } ListListString head new ArrayList(); head.add(row0); if (hasGroup) { head.add(row1); } return head; }这段代码解决了一个常见的混合场景部分列有分组部分列没有分组。比如“商品名称”没有分组直接放在第一行“华东大区”下面还有“1月、2月”所以第一行显示“华东大区”第二行显示子列名。没有分组的列在第二行必须加一个空字符串否则row1的长度就会比row0短EasyExcel写入时会因为表头行数不一致而报错或者错乱。这里还要说一个EasyExcel的自动合并规则它只合并相邻且内容相同的单元格。也就是说如果两个“华东大区”中间夹了一个“华南大区”它们不会跨列合并成一个更宽的大单元格。如果业务上有这种“不连续分组但想合并”的需求那就得扩展WriteHandler去自定义合并策略了这个后面单独说。3.4 构建动态数据行并完成导出数据行的构建相对简单遍历每个业务主记录固定列先放动态列按ColumnMeta列表顺序取数。下面这个export方法是一个可以直接用的最小工具public void exportDynamicExcel(ListColumnMeta columns, ListMapString, Object dataList, OutputStream outputStream) { ListListString head buildHead(columns); ListListObject dataRows new ArrayList(); for (MapString, Object data : dataList) { ListObject row new ArrayList(); for (ColumnMeta column : columns) { row.add(data.get(column.getFieldKey())); } dataRows.add(row); } EasyExcel.write(outputStream) .head(head) .sheet(动态列数据) .doWrite(dataRows); }如果是Spring MVC的下载接口只需要把OutputStream换成HttpServletResponse的输出流再配上Content-Type和文件名编码就能直接下载。这里有一个容易踩的坑导出结束后doWrite方法已经会关闭流吗不会完全替你管理Servlet输出流所以如果你在Controller里手动关了response.getOutputStream()后续再写东西就会报错。我的习惯是下载场景下只设置响应头不手动关闭输出流交给EasyExcel的finish逻辑处理。3.5 多级表头和自定义列策略的进阶写法两级表头能覆盖大部分业务但偶尔会遇到三级甚至更多层级的需求。原理是一样的表头有几级就在head列表里加几行每一行的长度必须相等没有子列的位置统一用空字符串占位。可以这样构建三级表头的行数private ListListString buildMultiLevelHead(ListColumnMeta columns, int levelCount) { ListListString head new ArrayList(); for (int i 0; i levelCount; i) { head.add(new ArrayList()); } for (ColumnMeta column : columns) { // 假设ColumnMeta有level0、level1、level2三级名称 head.get(0).add(column.getLevel0Name()); head.get(1).add(column.getLevel1Name() null ? : column.getLevel1Name()); head.get(2).add(column.getLevel2Name() null ? : column.getLevel2Name()); } return head; }三级表头最容易出的问题就是占位符漏填每一级的List长度不齐写出来的Excel表头会歪。我自己写多级表头时都会先在Excel里把目标表头画出来数一数每一行有几个单元格再回来写代码。除了表头动态列场景还经常需要处理列宽。EasyExcel内置了一个LongestMatchColumnWidthStyleStrategy可以根据内容长度自动调整列宽。但注意这个策略在列数很多、数据量很大的时候性能比较差因为它会扫描所有单元格的内容长度。如果动态列超过50列我不建议用这个策略可以在ColumnMeta里显式设置一个合理的列宽或者干脆交给前端去自适应。EasyExcel.write(outputStream) .head(head) .registerWriteHandler(new LongestMatchColumnWidthStyleStrategy()) .sheet(动态列数据) .doWrite(dataRows);4. 不能不说的坑动态列导出的常见问题与性能优化4.1 高频报错速查表下面这些问题是动态列导出里最高频的我整理成了一张速查表方便你直接排查报错信息或现象原因解决方案提示重复表头或表头合并异常表头列表中存在完全相同的相邻字符串EasyExcel自动合并后影响了列数对重复表头追加空格或特殊字符让字符串唯一表头行数与数据行数不一致或单元格错位不同层级表头的List长度不相等用空字符串补位保证每行列数一致空指针异常涉及head或cell表头中存在null且未做兼容占位符统一用空字符串不要用null导出后数据列与表头顺序不对表头生成和数据生成各自维护了一套顺序统一使用同一个ListColumnMeta遍历并发导出时表头串数据多个线程共用了同一个head列表对象每次导出前new新的head列表不要全局复用大数据量导出OOMList一次性装载了所有数据分批写入或改用CSV导出4.2 复杂表头导入的处理思路动态列不止导出需要导入同样会遇到。我用EasyExcel做导入时如果Excel表头很复杂就不会使用带Class模型的方式去映射了而是直接用NoModelDataListener读取原始行列数据。这样简单高效因为没有预先定义实体类读取时每一行就是一个MapInteger, Stringkey是列索引。你可以先读表头行解析出列名对应的业务含义再从后续数据行里按索引取值。用这种方式任何复杂的动态表头在导入时都能被“降维”成一堆行列坐标业务层再自己组装对象。4.3 大数据量导出的性能优化经验动态列导出一旦列数多、行数多性能问题就来了。第一个建议是“能分批就分批”。EasyExcel虽然支持流式写但如果你一次性把几十万行数据全部组装成ListObject再调用doWrite内存压力还是在的。更稳妥的做法是使用ExcelWriter手动控制写入批次每处理完一批就write一次最后finish。示例代码如下ExcelWriter writer EasyExcel.write(outputStream).build(); WriteSheet sheet EasyExcel.writerSheet().build(); for (ListMapString, Object batch : batchDataList) { ListListObject rows convertToRows(batch); writer.write(rows, sheet); } writer.finish();第二个建议是“慎用自动列宽”。LongestMatchColumnWidthStyleStrategy在列少的时候很省心列一多就成了性能杀手。我的经验是超过50列的动态导出列宽统一固定或者让前端处理不在后端做自适应。第三个建议是“给Excel设置一个列数上限”。Excel本身虽然支持很多列但用户端打开一个上百列的Excel体验极差。我在项目里定了一个约定动态列超过80列时强制拆分导出或者转成CSV。CSV本质就是纯文本拼接没有单元格对象导出速度比写xlsx快不少适合数据量大但不需要样式的场景。4.4 动态列项目的几个土办法最后分享几个我在项目里总结出来的经验不算高深但能少走很多弯路。第一写动态列表头之前先在纸上画出目标Excel的样子。Excel表头一旦有分组、合并和占位符逻辑很容易绕晕。画出每个单元格在第几行第几列再去写buildHead准没错。第二做极端测试。我每次写完动态列导出都会准备两组数据一组是极端的1列1行验证边界一组是80列乘1万行验证性能和稳定性。很多隐藏bug都是在这两种数据下暴露出来的。第三表头命名要规范。尽量不要让动态列的表头出现直接重复。如果业务上确实需要重复的列名你可以在列名后面拼一个不可见的全角空格或者下划线序号保证字符串唯一。第四动态情况下的数据源查询一定要控制内存。查询数据库时不要一把梭查所有明细能按维度聚合就聚合能只查必要的字段就只用必要字段。动态列导出的瓶颈往往不在EasyExcel本身而在于你把多少数据先装进了内存。我个人在实际项目里的体会是动态列导出最核心的不是技术本身而是“列是运行期才确定”这个认知是否真正贯彻到了代码里。只要你坚持“表头集合 数据列集合 同一个List ”这个原则大部分问题都会迎刃而解。最后再分享一个小技巧测试动态列导出时把数据量调小但把列数调到很大这样能最快暴露表头长度不齐、占位符漏写这类问题。别问我怎么知道的调试了三天之后你会感谢这个建议的。
EasyExcel动态列导出实战：从表头建模到大数据量优化
最近在做报表导出模块时需求方提了一个特别“折腾人”的要求导出的Excel列不是固定的要根据用户在前端勾选的维度动态生成。用户今天选3个门店导出的Excel就是4列明天选30个门店直接变31列。这个需求在报表后台、运营分析系统、企业管理系统里太常见了解决方案也已经很成熟——用EasyExcel做动态列导出。这篇文章我会把动态列的设计思路、横向循环生成表头与数据的方式以及我实际测试时踩过的坑都整理出来希望对正在被“表头怎么不固定啊”折磨的读者有帮助。内容偏实战适合有一定Java基础、正在做导出功能的同学参考。1. 动态列到底在解决什么问题以及为什么选EasyExcel1.1 实际业务里动态列长什么样先别急着写代码我们把场景还原清楚。动态列导出最典型的是下面两类业务。第一类是“维度枚举型”报表。比如电商大促效果对比表用户勾选了“618第一波”“618第二波”“双11预热”三个活动期导出的Excel第一列是商品名称后面每一列是一个活动期的销量。明天用户勾选了五个活动期那Excel就多出两列。这个列集合是运行时确定的根本没有办法在代码里写死一个DTO加注解去处理。第二类是“主数据驱动型”报表。最典型的就是多门店销售汇总第一列是商品后面每个门店一列门店列表来自主数据配置。今天新增了两家门店导出的列就自动增加两列。我甚至遇到过列数超过80列的需求把门店、月份、指标三个维度全部展开成一行。这类场景有一个共同特征表格的“列名集合”是一个动态列表业务数据需要按照“主记录 动态属性值”的方式横向铺开。如果你还在用传统思路写一个固定字段的OOP对象然后用ExcelProperty注解映射字段那动态列就完全没法做因为注解在编译期就确定了运行期根本改不了。1.2 为什么是EasyExcel而不是原生POI既然是Java生态里的Excel处理很多人第一反应是POI。POI并不是不能用而是做动态列这种需求时成本明显偏高。拿原生POI写动态列你需要自己维护Workbook、Sheet、Row、Cell所有单元格都要手动创建。表头合并要调addMergedRegion列宽要逐列设置数据行还要按列索引挨个set。这些代码不是写不出来而是维护起来太痛苦尤其是换了个Excel模板或者新增了分组维度大片代码要跟着改。EasyExcel是阿里开源的一个库底层虽然也是POI但做了大量封装。它有几个特点是专门“对症”动态列的支持ListListString直接作为表头列集合可以在运行期自由构建写文件时采用流式写入相对原生POI内存占用小很多大数据量场景不容易OOM表头合并、单元格样式这些高频操作通过内置策略和WriteHandler就能实现不需要每个Cell都手控。我做了一张对比表方便你直观感受对比维度原生POIEasyExcel动态表头支持需要手动建Row/Cell代码量很大直接传ListList 非常直接内存占用写大量数据时对象全在内存容易OOM流式写入内存占用明显低合并单元格手动调addMergedRegion相同表头自动合并或WriteHandler控制学习成本需要熟悉整套POI对象模型API层面主要理解Writer、WriteSheet、Head三个概念社区活跃度老牌稳定但Excel导出这块资料偏底层国内使用人数多问题基本都能搜到我们在项目里引入EasyExcel不是因为它比POI“高级”而是因为动态列场景下它能节省大量不必要的重复代码出问题也好排查。选型不用太纠结如果你的目标是“快速把一个动态报表做出来并且长期维护”EasyExcel是当前的最佳选择之一。2. 横向循环的建模思路先画表头再组织数据2.1 表头在EasyExcel里到底是什么结构做动态列第一步要改变思维不要把Excel表头想成一个二维表格在EasyExcel里表头本质上是ListListString。最外层的List代表“表头的行”内层List代表“每一行的所有列”。举个例子最简单的单层表头比如“商品名称、销量、销售额”它就是一行表头ListListString head new ArrayList(); head.add(Arrays.asList(商品名称, 销量, 销售额));如果你只需要单层表头那这个结构很简单。但实际业务里尤其是报表导出极少是单层表头。最常见的是这种带分组的两级表头商品名称华东大区华东大区华南大区1月2月1月这个表头在EasyExcel里怎么写很多人第一次会写错因为他们觉得“商品名称”下面没有子列所以第二行就不需要占位。实际上头部每一行的List长度必须完全一致否则单元格会对不齐。正确写法是这样的ListListString head new ArrayList(); ListString row0 new ArrayList(); ListString row1 new ArrayList(); row0.add(商品名称); row0.add(华东大区); row0.add(华东大区); row0.add(华南大区); row1.add(); // 商品名称这列在第二行用空字符串占位 row1.add(1月); row1.add(2月); row1.add(1月); head.add(row0); head.add(row1);注意两个细节。第一华东大区在第一行出现了两次EasyExcel会根据相邻单元格内容相同的规则把它自动合并成一个跨两列的大单元格不需要你手动调addMergedRegion。第二占位符建议用空字符串而不是null因为某些版本的EasyExcel在对null表头做处理时可能抛出空指针。这个坑我踩过后面常见问题里会细说。搞懂了这个结构你就会发现动态列的“横向循环”其实就两件事确定一共有多少列确定表头有多少行。然后把每一行的列名填进去。列名集合一旦确定了剩下的就是简单的循环填充。2.2 从业务数据到横向行的转换思路表头是“横向循环”的上半场下半场是数据行。业务系统里存的数据绝大部分是一行行明细。比如销售记录表里每条记录是一个商品在一个门店一个月份下的销量。你要导出的却是每个商品一行门店和月份展开成多列。这个转换本质上就是把纵向明细“旋转”成横向宽表。我的做法是先按固定列分组然后动态列用“维度枚举组合”作为key构建一个二维索引。举个简单例子源数据对象是SaleRecord有product、region、month、amount四个字段。要生成“商品 × (门店月份)”的横向报表就先定义一个复合key比如region _ month然后把明细折算成按product分组的map。后续循环product列表外层循环固定列内层循环动态列集合一行一行取数。核心代码大概长这样MapString, MapString, Integer productMap new LinkedHashMap(); for (SaleRecord record : records) { String key record.getRegion() _ record.getMonth(); productMap.computeIfAbsent(record.getProduct(), k - new LinkedHashMap()) .put(key, record.getAmount()); } ListString dynamicKeys new ArrayList(); for (String region : regionList) { for (String month : monthList) { dynamicKeys.add(region _ month); } } ListListObject dataRows new ArrayList(); for (Map.EntryString, MapString, Integer entry : productMap.entrySet()) { ListObject row new ArrayList(); row.add(entry.getKey()); // 固定列商品名称 for (String key : dynamicKeys) { row.add(entry.getValue().getOrDefault(key, 0)); // 动态列缺省补0 } dataRows.add(row); }这里有一个特别重要的点构建表头时的动态列顺序必须和构建数据行时的动态列顺序完全一致。我习惯把“动态列集合”抽成一个公共变量表头生成和数据行生成都遍历它而不是在两边分别写循环避免两处顺序不一致导致数据错位。数据错位这个问题在动态列场景里是最高频的问题而且很隐蔽。表头明明看着对数据也能写进去但某一列的表头和市场数据对不上。出现这种情况八成就因为表头和数据行用了两套不同的顺序逻辑。3. 实战一个可复用的动态列导出工具3.1 引入依赖与基础配置项目用的Spring Boot直接引入EasyExcel的Maven依赖。3.x是目前的主线版本功能稳定对动态表头的支持也更友好。我用的是3.3.x下面的代码都以3.x为准。dependency groupIdcom.alibaba/groupId artifactIdeasyexcel/artifactId version3.3.2/version /dependency如果你还在用2.x版本接口大体兼容但动态表头部分有些细节行为不一样比如表头占位符的处理逻辑建议升级到3.x再跑。3.2 定义通用列元数据动态列的“列”不能只是一个字符串它至少需要两个信息表头显示什么、数据按什么key取。我习惯定义一个ColumnMeta对象把列的属性封装好public class ColumnMeta { /** * 表头显示名称 */ private String headName; /** * 数据取值key对应数据Map的key */ private String fieldKey; /** * 分组名用于多级表头 */ private String groupName; /** * 列宽默认-1不设置 */ private Integer columnWidth -1; public ColumnMeta(String headName, String fieldKey) { this.headName headName; this.fieldKey fieldKey; } public ColumnMeta(String headName, String fieldKey, String groupName) { this.headName headName; this.fieldKey fieldKey; this.groupName groupName; } // getter、setter省略 }为什么要加fieldKey而不是直接传一个表头字符串是因为数据行我统一用MapString, Object承载列顺序完全由ColumnMeta列表控制而key只是取值依据。这样数据来源无论是数据库查询结果、内存对象还是第三方接口返回都能用一套逻辑处理。3.3 构建动态表头核心的横向循环构建表头时核心逻辑是判断有无分组。没有分组就是单行表头有分组就生成两行并且要处理第二行的占位符。我先贴这段工具代码再解释为什么这么写private ListListString buildHead(ListColumnMeta columns) { boolean hasGroup columns.stream().anyMatch(c - c.getGroupName() ! null); ListString row0 new ArrayList(); ListString row1 new ArrayList(); for (ColumnMeta column : columns) { if (hasGroup) { if (column.getGroupName() ! null) { row0.add(column.getGroupName()); row1.add(column.getHeadName()); } else { // 该列没有分组第一行直接显示列名第二行用空字符串占位 row0.add(column.getHeadName()); row1.add(); } } else { row0.add(column.getHeadName()); } } ListListString head new ArrayList(); head.add(row0); if (hasGroup) { head.add(row1); } return head; }这段代码解决了一个常见的混合场景部分列有分组部分列没有分组。比如“商品名称”没有分组直接放在第一行“华东大区”下面还有“1月、2月”所以第一行显示“华东大区”第二行显示子列名。没有分组的列在第二行必须加一个空字符串否则row1的长度就会比row0短EasyExcel写入时会因为表头行数不一致而报错或者错乱。这里还要说一个EasyExcel的自动合并规则它只合并相邻且内容相同的单元格。也就是说如果两个“华东大区”中间夹了一个“华南大区”它们不会跨列合并成一个更宽的大单元格。如果业务上有这种“不连续分组但想合并”的需求那就得扩展WriteHandler去自定义合并策略了这个后面单独说。3.4 构建动态数据行并完成导出数据行的构建相对简单遍历每个业务主记录固定列先放动态列按ColumnMeta列表顺序取数。下面这个export方法是一个可以直接用的最小工具public void exportDynamicExcel(ListColumnMeta columns, ListMapString, Object dataList, OutputStream outputStream) { ListListString head buildHead(columns); ListListObject dataRows new ArrayList(); for (MapString, Object data : dataList) { ListObject row new ArrayList(); for (ColumnMeta column : columns) { row.add(data.get(column.getFieldKey())); } dataRows.add(row); } EasyExcel.write(outputStream) .head(head) .sheet(动态列数据) .doWrite(dataRows); }如果是Spring MVC的下载接口只需要把OutputStream换成HttpServletResponse的输出流再配上Content-Type和文件名编码就能直接下载。这里有一个容易踩的坑导出结束后doWrite方法已经会关闭流吗不会完全替你管理Servlet输出流所以如果你在Controller里手动关了response.getOutputStream()后续再写东西就会报错。我的习惯是下载场景下只设置响应头不手动关闭输出流交给EasyExcel的finish逻辑处理。3.5 多级表头和自定义列策略的进阶写法两级表头能覆盖大部分业务但偶尔会遇到三级甚至更多层级的需求。原理是一样的表头有几级就在head列表里加几行每一行的长度必须相等没有子列的位置统一用空字符串占位。可以这样构建三级表头的行数private ListListString buildMultiLevelHead(ListColumnMeta columns, int levelCount) { ListListString head new ArrayList(); for (int i 0; i levelCount; i) { head.add(new ArrayList()); } for (ColumnMeta column : columns) { // 假设ColumnMeta有level0、level1、level2三级名称 head.get(0).add(column.getLevel0Name()); head.get(1).add(column.getLevel1Name() null ? : column.getLevel1Name()); head.get(2).add(column.getLevel2Name() null ? : column.getLevel2Name()); } return head; }三级表头最容易出的问题就是占位符漏填每一级的List长度不齐写出来的Excel表头会歪。我自己写多级表头时都会先在Excel里把目标表头画出来数一数每一行有几个单元格再回来写代码。除了表头动态列场景还经常需要处理列宽。EasyExcel内置了一个LongestMatchColumnWidthStyleStrategy可以根据内容长度自动调整列宽。但注意这个策略在列数很多、数据量很大的时候性能比较差因为它会扫描所有单元格的内容长度。如果动态列超过50列我不建议用这个策略可以在ColumnMeta里显式设置一个合理的列宽或者干脆交给前端去自适应。EasyExcel.write(outputStream) .head(head) .registerWriteHandler(new LongestMatchColumnWidthStyleStrategy()) .sheet(动态列数据) .doWrite(dataRows);4. 不能不说的坑动态列导出的常见问题与性能优化4.1 高频报错速查表下面这些问题是动态列导出里最高频的我整理成了一张速查表方便你直接排查报错信息或现象原因解决方案提示重复表头或表头合并异常表头列表中存在完全相同的相邻字符串EasyExcel自动合并后影响了列数对重复表头追加空格或特殊字符让字符串唯一表头行数与数据行数不一致或单元格错位不同层级表头的List长度不相等用空字符串补位保证每行列数一致空指针异常涉及head或cell表头中存在null且未做兼容占位符统一用空字符串不要用null导出后数据列与表头顺序不对表头生成和数据生成各自维护了一套顺序统一使用同一个ListColumnMeta遍历并发导出时表头串数据多个线程共用了同一个head列表对象每次导出前new新的head列表不要全局复用大数据量导出OOMList一次性装载了所有数据分批写入或改用CSV导出4.2 复杂表头导入的处理思路动态列不止导出需要导入同样会遇到。我用EasyExcel做导入时如果Excel表头很复杂就不会使用带Class模型的方式去映射了而是直接用NoModelDataListener读取原始行列数据。这样简单高效因为没有预先定义实体类读取时每一行就是一个MapInteger, Stringkey是列索引。你可以先读表头行解析出列名对应的业务含义再从后续数据行里按索引取值。用这种方式任何复杂的动态表头在导入时都能被“降维”成一堆行列坐标业务层再自己组装对象。4.3 大数据量导出的性能优化经验动态列导出一旦列数多、行数多性能问题就来了。第一个建议是“能分批就分批”。EasyExcel虽然支持流式写但如果你一次性把几十万行数据全部组装成ListObject再调用doWrite内存压力还是在的。更稳妥的做法是使用ExcelWriter手动控制写入批次每处理完一批就write一次最后finish。示例代码如下ExcelWriter writer EasyExcel.write(outputStream).build(); WriteSheet sheet EasyExcel.writerSheet().build(); for (ListMapString, Object batch : batchDataList) { ListListObject rows convertToRows(batch); writer.write(rows, sheet); } writer.finish();第二个建议是“慎用自动列宽”。LongestMatchColumnWidthStyleStrategy在列少的时候很省心列一多就成了性能杀手。我的经验是超过50列的动态导出列宽统一固定或者让前端处理不在后端做自适应。第三个建议是“给Excel设置一个列数上限”。Excel本身虽然支持很多列但用户端打开一个上百列的Excel体验极差。我在项目里定了一个约定动态列超过80列时强制拆分导出或者转成CSV。CSV本质就是纯文本拼接没有单元格对象导出速度比写xlsx快不少适合数据量大但不需要样式的场景。4.4 动态列项目的几个土办法最后分享几个我在项目里总结出来的经验不算高深但能少走很多弯路。第一写动态列表头之前先在纸上画出目标Excel的样子。Excel表头一旦有分组、合并和占位符逻辑很容易绕晕。画出每个单元格在第几行第几列再去写buildHead准没错。第二做极端测试。我每次写完动态列导出都会准备两组数据一组是极端的1列1行验证边界一组是80列乘1万行验证性能和稳定性。很多隐藏bug都是在这两种数据下暴露出来的。第三表头命名要规范。尽量不要让动态列的表头出现直接重复。如果业务上确实需要重复的列名你可以在列名后面拼一个不可见的全角空格或者下划线序号保证字符串唯一。第四动态情况下的数据源查询一定要控制内存。查询数据库时不要一把梭查所有明细能按维度聚合就聚合能只查必要的字段就只用必要字段。动态列导出的瓶颈往往不在EasyExcel本身而在于你把多少数据先装进了内存。我个人在实际项目里的体会是动态列导出最核心的不是技术本身而是“列是运行期才确定”这个认知是否真正贯彻到了代码里。只要你坚持“表头集合 数据列集合 同一个List ”这个原则大部分问题都会迎刃而解。最后再分享一个小技巧测试动态列导出时把数据量调小但把列数调到很大这样能最快暴露表头长度不齐、占位符漏写这类问题。别问我怎么知道的调试了三天之后你会感谢这个建议的。
