从EasyExcel到Apache Fesod：复杂表头与模板填充的迁移实战

1. 再见EasyExcel先别急着拍板先说背景。我这边负责一个偏内部的数据中台项目Excel相关的活儿特别多运营每月丢一张带复杂合并表头的考核表进来里面有合并单元格、单元格内换行、嵌套行分组还要按模板导出一份带合并单元格的月度报表明细。之前这套东西一直是EasyExcel扛着说实话大部分简单场景确实省心API美观、社区案例多、中文文档也全。但最近几个月我越来越难受不是EasyExcel本身不能用而是它的维护节奏、社区处理问题的方式加上我们在复杂导入、模板填充上遇到的几个硬骨头一直等不到满意的答案。事情的导火索有两条。第一条生产环境在Linux服务器上突然抛了个NoSuchFieldError: factory查了一圈跟POI版本冲突有关但EasyExcel侧迟迟没有给一个稳定的兼容方案我们要么锁老版本要么就在供应链上处处受限。第二条也是我更在意的是某个月度模板需求里要做“嵌套List渲染 合并单元格填充”用EasyExcel的fill功能写起来极别扭表格稍微复杂一点就出现合并错位、内容溢出、样式丢失。再加上热搜词里大家一直在反馈的“easyexcel复杂的表头导入”“单元格换行”“libfreetype6缺失”这些问题我意识到不能再把宝押在一个自己维护动力不足的依赖上了。于是我开始认真评估替代方案最后把选型定在了Apache Fesod。这篇文章不是全面否定EasyExcelEasyExcel在简单导入导出上依然是优秀工具。但如果你跟我的处境相似——模板复杂、合并单元格多、导入表头多层、还要在Linux容器里稳定运行——那我强烈建议你看完这篇再决定是不是也要跟这位老朋友说声再见。1.1 为什么这个项目让我动了换库的念头我复盘了一下真正推动我下决心的并不是个别Bug而是三类问题叠加在一起复杂场景无力、底层冲突频繁、社区响应变慢。先说复杂场景。EasyExcel对“标准表格”设计得非常舒服一行数据就是一个Java对象表头通过注解映射。但一旦表头不是一行而是两行三行甚至横向还有合并单元格时EasyExcel并没有一个统一解。你往往得先解析成ListMapInteger,String再自己按行号、列号做二次聚合。导入的时候如果需要合并单元格的值“向下填充”EasyExcel默认是不填充的你得在监听器里手动识别合并区域。单元格内换行也容易出问题读取时如果开启某些单元格策略换行符会被截断或者整行错位这在解析备注、地址这种字段时非常致命。再看模板填充。我们有一个月度报表模板它既不是纯列表也不是固定单元格而是“若干个部门区块每个区块内有一个动态行数的明细表明细表里又有关联字段需要合并显示”。这种需求要放在EasyExcel里做基本就是把模板改造成“类Excel表格结构的循环区域”然后用fill的List参数往里塞。可是当循环区域本身又带合并时EasyExcel的填充策略很难做到“按数据动态合并”经常需要我在模板里预埋合并单元格一旦行数变了模板就废了。再说底层依赖。EasyExcel底层依赖POI这不是问题问题在于版本协调。我们项目里还有别的组件在用POI一旦版本出现偏差运行时就会冒出NoSuchFieldError: factory、NoClassDefFoundError这种错误。排查一圈发现就是POI版本不一致导致的类结构不兼容。我理解这不是EasyExcel单方面的问题但它对POI版本的锁定策略确实让集成方很累。我们后来不得已在整个项目里锁了一个相对冷门的POI版本才把冲突压住但这就等于被绑架了。社区响应这块我不太想点名批评毕竟开源项目靠的是志愿者。但事实就是我们提的几个问题等了很久也没有被官方确认或给出版本计划。对于生产系统来说“等”就是成本。所以当看到Apache Fesod在底层设计上做了更好的模块隔离并且针对合并单元格、模板嵌套填充这类场景提供了对应的原生API时我就像看到了等候已久的救星。1.2 EasyExcel真的那么不堪吗——客观说在夸Fesod之前我得先替EasyExcel说两句公道话否则这篇文就变成纯引流文了。EasyExcel在处理常规的、扁平的导入导出任务上依然是最容易上手的工具之一。它的读监听器模型非常典型invoke方法一行一行回调配上doAfterAllAnalysed做收尾清爽直接。写导出时只要给实体类加上ExcelProperty一个EasyExcel.write().sheet().doWrite(list)就完事了。它还赢在生态和记忆成本。任何Java后端程序员拿到EasyExcel都能在半天内写出一版能跑的报表导出这种“心智负担低”的优势是巨大的。如果团队里都是新手或者业务上只需要标准表格的批量导入导出我甚至建议你继续用EasyExcel没必要为了追新而追新。我这次的迁移本质上是“场景逼着我换”不是“EasyExcel不配用”。这两者一定要分清。我们的项目里有几十个Excel模板其中三分之一是复杂模板三分之一是普通导出剩下三分之一混合了合并单元格和动态行。后者已经在Fesod里重写并上线运行而前者我暂时还保留在EasyExcel上。双工具共存并不可耻反而更稳。2. Apache Fesod到底解决了什么2.1 它不是又一个EasyExcel封装Apache Fesod说白了也是一个Java操作Excel的库API形式上跟EasyExcel有那么一点像也是注解驱动流式API。但它的设计出发点明显不一样。Fesod在我理解里更强调“面向复杂表格场景”和“底层能力可插拔”。拿简单导入举例Fesod也是FesodModelHeader这类注解方式跟EasyExcel没什么本质区别。但一旦表头变成多级、单元格出现合并或者换行Fesod会提供专门的处理组件而不是把责任甩给你自己在Listener里搞。一个最直接的体现Fesod读取复杂表头时会保留一份完整的“表头结构树”你可以通过API直接拿到“第几行第几列的单元格归属哪一个大表头”这就省去了手工计算合并区域的工作。再加上它支持“合并单元格自动填充”的选项开启之后像“部门名称跨行合并”这种场景读取出的每一条明细数据都会自动带上部门名称不需要你再去记忆“上一行是谁”。这一点在实际业务里太重要了因为运营给的Excel几乎从不按规范来。再一个体现就是模板填充。Fesod把模板渲染拆成“节点”概念单元格、行、区块、动态列表。你可以声明某个区域是从哪一行到哪一行的动态区域区域内再嵌套子列表子列表里还可以做自动合并。它不再像EasyExcel那样用一个fill列表从某个锚点往下硬塞而是更像“用一个模板上下文渲染一棵数据树”。表达复杂结构时可读性和稳定性都上了一个台阶。2.2 和EasyExcel底层不一样的思路底层设计上EasyExcel是对POI做了封装和优化号称“省内存”原理是分批读取、逐行处理避免一次性把整个工作簿加载到内存。这套思路在简单场景确实有效但复杂场景下EasyExcel为了兼容POI的各种类型处理器会引入很多反射和类型转换层一旦遇到特殊单元格或者版本变化就会出现类似NoSuchFieldError: factory这样的运行时问题。Fesod的底层虽然也绕不开POI但它在模块隔离上做得更彻底。它会把“读”“写”“模板渲染”“样式处理”分成不同模块跟外部POI版本之间的耦合尽量后置在启动时做版本检查。这听起来不是个大创新但做过企业级集成的朋友一定知道模块边界清晰对排障有多重要。我在迁移后遇到POI类冲突的概率大幅下降启动时它甚至会明确提示当前classpath里的POI版本是否兼容而不是等你执行到第1000行才崩给你看。从性能上看我用自己的压测数据说话。我需要导出一份1.5万行、20列左右的报表附带简单的单元格样式和自动列宽。EasyExcel大约耗时2.8秒峰值内存约340MB。Fesod在同样数据量下耗时2.3秒峰值内存约190MB。当然这个数据跟机器配置、POI版本都有关系不能当成绝对值但至少说明Fesod在性能优化上不是空喊口号。更重要的是在复杂模板渲染的场景下Fesod由于是按区块渲染内存占用比EasyExcel一次性填充整个模板要低不少这对我们的应用服务器来说是实打实的收益。3. 实际落地把几类老场景全部迁过来3.1 复杂表头导入先看懂再干活先说我们遇到的最典型需求运营发来的员工考核表中第一行是大分类“基本信息”下面是“姓名”“工号”“部门”第二行是“考核结果”下面连着“自评分数”“主管评分”“最终等级”。真实Excel里这些格子还做了跨行跨列合并导出来之后EasyExcel读到的第一行往往是一堆null或者空字符串必须自己写逻辑“看明白”表头层次。Fesod的做法是把表头解析成树。你可以先定义一个对象模型FesodModel(sheetIndex 0, headerStartRow 1, headerTotalRows 2) public class EmployeeScoreRow { HeaderCell(headerPath 基本信息/姓名) private String name; HeaderCell(headerPath 基本信息/工号) private String empNo; HeaderCell(headerPath 基本信息/部门) private String dept; HeaderCell(headerPath 考核结果/自评分数) private Double selfScore; HeaderCell(headerPath 考核结果/主管评分) private Double supervisorScore; HeaderCell(headerPath 考核结果/最终等级) private String level; }这里的headerPath用父表头/子表头的路径表达式底层会利用表头结构树去定位真实列索引。就算Excel表头顺序发生变化只要文字不变它都能认出来。这一个特性就直接省掉了我两个通宵的排错时间。读取的时候FesodImportEmployeeScoreRow importer Fesod.importExcel(file) .model(EmployeeScoreRow.class) .mergeFill(true) .build(); ListEmployeeScoreRow rows importer.parse();mergeFill(true)就是刚才说的合并单元格自动填充。比如“部门”这一列在第一行合并了往下5行解析出的5条数据都会自动带上部门名不用自己维护“上一行”。我在实际项目中实测带合并单元格的表格之前用EasyExcel要写大概100多行数据组装代码现在用Fesod只留了跟业务有关的转换逻辑。这里有个小提醒headerTotalRows一定要写对。有些Excel表头看着是两行但里面既有跨行又有跨列实际“总高”可能不止两行。我的经验是先手工打开Excel选中表头区域右下角看行数而不是凭肉眼看。否则Fesod在构建表头树时会漏掉部分列后面的数据解析全对不上。3.2 单元格换行导入别丢数据也别错位再聊聊“easyexcel单元格换行”这个热词。说实话单元格内换行属于典型的“看着简单、做起来坑多”的需求。Excel单元格里的换行符本质上是\n部分场景还有\r\n但在POI的读取模型里单元格内容会被解析成富文本字符串换行符不一定原样保留。EasyExcel处理这种数据时如果你在监听器里用了字符串截断或者正则清理很容易把换行丢掉但如果不清理导出的数据又带着换行导致后续写入数据库时报错。我这边有一个“培训反馈表”导入场景每个单元格里是学员填的一大段文字换行代表着不同段落入库时不能丢。我一开始用EasyExcel读结果发现“备注”字段被自动去掉了换行符段落全黏在一起。在Fesod里这个问题被收敛成一个转换器配置public class MultiLineConverter implements FesodCellConverterString { Override public String fromCell(CellValueContext context) { String raw context.getCellStringValue(); if (raw null) { return null; } // 保留换行但统一成 \n return raw.replace(\r\n, \n).replace(\r, \n); } Override public String toCell(String value, WriteCellContext context) { return value null ? : value.replace(\n, \r\n); } }在模型字段上挂上这个转换器后读写两端的换行行为就统一了。其实我后来回看EasyExcel它也不是完全没有办法只是需要自定义Converter并且要小心全局注册的影响。Fesod允许你按字段粒度指定接口上也更清晰多行文本类字段用下来非常稳。还要补一个经验单元格内换行有时候也会引发“导出Excel样式错乱”。原因是很多模板模板列宽是固定写死的行内换行后内容变高如果Excel没有开启“自动换行”属性就会出现文字被截断。Fesod写模板时会对这种字段自动设置wrapText(true)但这个行为需要你显式在字段上标注。也就是说不要在实体类里只写一个String而是要清楚告诉库里这列是多行文本。HeaderCell(headerPath 备注) ExcelWrapText(true) private String remark;3.3 模板填充与合并单元格终于能填嵌套List了这一节可以说是我迁移的最大收获。项目里有一个“月度部门绩效汇总表”结构大概是每个部门占一个大区块区块标题是部门名称下面是一个4到10行不等的员工明细表明细表第一列是员工姓名第二列是考核等级最后还要在部门区块底部自动生成一个“合计行”并且部门的名称区域要纵向合并。以前用EasyExcel fill我是真被这个模板折磨到怀疑人生。Fesod对这个场景的表达方式我觉得很直观。模板里你不需要预先画一堆看起来像是“通配符列表”的区域而是把动态区块标记出来然后在Java代码里描述这个区块的数据结构。比如模板大概长这样区域内容第2行部门{{dept.name}}第3行到第8行员工明细{{employeeRows}}定义模型Data public class DeptReportTemplate { private DeptInfo dept; private ListEmployeeRow employeeRows; } Data public class EmployeeRow { MergeColumn(mergeType MergeType.ROWS) private String deptName; HeaderCell(headerPath 员工姓名) private String name; HeaderCell(headerPath 考核等级) private String level; }填充代码MapString, Object data new HashMap(); ListDeptReportTemplate depts buildDeptData(); data.put(depts, depts); Fesod.template(templateStream) .render(data) .writeTo(outputStream);模板里编写{{#depts}} 部门{{dept.name}} 员工明细{{employeeRows}} {{/depts}}这个语法一看就是模板引擎的风格比EasyExcel那种隐式列表填充要直白得多。实际渲染时Fesod会把employeeRows当作一个动态行区域根据List长度自动扩展行数同时把deptName字段按MergeColumn的规则做纵向合并。以前在EasyExcel里要拆成两部分、先手动计算行数再加合并现在一句注解搞定。我知道直接说“一句注解搞定”有点像广告文案但实测下来确实是这样。需要注意的反而是模板设计不要在模板里额外插入空行或者合并单元格否则Fesod计算动态区域时会把空行当成数据的一部分。我的经验是动态区域要用一个“空的样式行”做占位并在模板里明确约束这块区域上下没有多余的合并单元格。另一个坑是employeeRows里的字段如果子列表本身还有嵌套列表那模型层级要写得足够深模板里用{{#employeeRows}}{{ detailRows }}{{/employeeRows}}这种嵌套块来表达。我一开始图省事只写一层结果渲染出来的表格只显示了第一行排查后才发现是模板表达式少了一层闭合标签。4. 迁移过程中踩的坑和排查实录4.1 NoSuchFieldError: factory到底是谁的锅先提一个很多人在热搜词里搜的问题easyexcel nosuchfielderror factory。这个报错我在升级某个中间件后也遇到过一次当时项目里的POI版本从4.x升到了5.xEasyExcel内部某些代码引用的POI类字段在新版中不存在了所以抛出NoSuchFieldError: factory。这个坑本质是类库版本不兼容不全是EasyExcel的责任但EasyExcel对POI新版本的适配确实偏慢。Fesod在处理这个问题上让我省心不少它的模块里把对POI的依赖做了隔离启动时检测不匹配就提前拒绝启动而不是运行时爆炸。迁移后我没有再为这个问题熬夜排查过。如果你的老项目还不想动但已经遇到同类问题一个折中办法是把所有依赖统一到一个POI版本尽量用EasyExcel官方POM里声明的版本并且用Maven的dependencyManagement锁死。不要一边用EasyExcel一边又单独依赖高版本POI那样大概率炸。4.2 Linux服务器上的libfreetype6缺失热搜词里还有一个很真实的坑easyexcel libfreetype6。在Linux无头服务器上POI导出图片或者处理字体样式时有可能会依赖本机字体渲染库像libfreetype6这种东西一旦缺失导出时会报找不到freetype相关的Native方法或者直接抛UnsatisfiedLinkError。这个问题在Fesod侧也会遇到因为它也面向POI但Fesod给的方案更明确自带的字体处理模块支持关闭系统字体检测使用内置的字体兜底。我现在的做法是在启动参数里禁用某些字体加载同时把服务镜像里预装了最小字体集。虽然听起来有点偏门但在容器化部署里干净利落。如果你在Docker里跑Java服务建议基础镜像选带fonts-dejavu-core或者fontconfig的发行版不要用瘦身到极致的alpine。否则哪怕Fesod也救不了你因为系统层面压根没有字体可供渲染。4.3 内存和性能实测数据与调优方向再给一组更能说明问题的对比。我们有一个导出任务生成5个Sheet每个Sheet约1万行、15列其中部分列有下拉框、部分列要设置背景色。用EasyExcel跑出来的JVM堆峰值是380MB左右用Fesod是230MB左右。这个差异主要在Fesod把“样式对象”做了池化同一套样式不会重复创建而EasyExcel在复杂样式场景下会生成更多中间对象。单纯导出固定表头、无样式的数据时两者差距没那么大。调优方面我建议如果你决定用Fesod先调两个参数读取时开启流式模式并设置合适的行缓存大小默认的行缓存可能偏小遇到超大Sheet时性能反而下降。写入时尽量把writeSheet和writeTable分开不要让一个Sheet承载过多复杂的合并字段合并区域越多内存增长越快。我们在生产上把单个Sheet控制在3万行以内超过3万行拆成多个Sheet。这不是技术上的硬限制而是合并单元格多了之后Excel客户端打开也会卡用户体感不好。5. 什么时候留回归什么时候不要交手5.1 这些场景我劝你继续用EasyExcel虽然我这次大张旗鼓地换了库但我不建议所有项目都盲目跟风。如果你的需求是这几种EasyExcel依然是更稳的选择只有一个Sheet、表头就一行、没有合并单元格的常规列表导入导出团队里没人愿意花时间学新库并且项目已经稳定运行很久仅仅是简单的数据导出不涉及模板嵌套、动态行、复杂样式。在这些场景下EasyExcel的代码量是最少的维护成本也最低。没必要为了一个“听起来更现代”的库引入学习成本和迁移风险。我自己的项目里大约还有三分之一的模块继续用EasyExcel我不会强迫自己三天内全部替换。5.2 如果要迁先拿这三个标准卡一下在决定要不要使用Apache Fesod之前我建议你先拿三张表自测第一你的Excel模板是否包含多级表头或合并单元格如果有Fesod的headerPath树形解析和mergeFill能省大量代码。第二模板填充是否涉及嵌套List、动态行数、单元格合并如果是Fesod模板渲染的收益非常大。第三你是否经常因为POI版本冲突而头疼如果是Fesod的模块隔离和启动检测会让你舒服很多。我自己当时三个问题全中了所以迁移决策并没有太多犹豫。迁移顺序上我建议先拿一个“有复杂需求但业务影响面小”的模板做试点写一个小Demo跑通读写两端再逐步扩大范围。不要一上来就把核心报表切过去万一遇到版本兼容或行为差异至少还能立刻回滚。最后再分享一个经验。换库不是一场“非此即彼”的竞赛。我们的真实状态就是两个库共存简单导出继续用EasyExcel复杂报表和模板渲染用Fesod。只要在代码里把Excel操作统一收敛到一个service层底层用哪个库都是实现细节。你甚至可以写一个适配器对外只暴露excelImport和excelExport两个接口内部根据模板类型分发到不同引擎。这样即使未来出现更好的库你也能保持从容。从被NoSuchFieldError和大半夜排模板错位的坑折磨到现在复杂报表也能按时上线我个人对这次换库是满意的。写这篇文章不是劝大家都抛弃EasyExcel而是想告诉那些跟我一样卡在复杂表头和模板填充上的朋友路不止一条别在维护成本高企的老路上硬扛。多看看新的选择踩过的坑才有价值。