上个月我把项目里所有EasyExcel相关的代码全部删掉了替换成了一个很多人还没听过的Apache Fesod。做出这个决定前我花了两周时间处理模板导出时合并单元格不断错位的问题最后一次排查到凌晨根因出在EasyExcel对合并区域和模板样式的兼容逻辑上。坦率说EasyExcel本身不差性能也够用但当业务开始碰复杂表头导入、嵌套List填充、模板合并单元格这类边角场景时你会发现自己不是在写业务代码而是在跟框架的边界搏斗。这篇文章不打算劝你立刻扔掉EasyExcel而是分享一次真实的迁移过程为什么迁移、Fesod和EasyExcel在底层思路上有什么不同、迁移时怎么改代码、以及我在这个过程中踩过的坑。对于正在做报表导入导出、被复杂表头和模板填充折磨的Java开发者这篇应该能帮你省下不少调研时间。1. 一个最终让我下决心换掉EasyExcel的对账报表需求1.1 需求背景动态列、多层表头、还要套模板导出先说清楚我是怎么被逼到换库这条路上的。项目是一个面向财务人员的对账平台每个月底会生成大量导出报表同时业务方又经常把线下整理好的Excel直接传上来做导入。如果只是普通的单层表头、简单行列数据EasyExcel其实完全够用。但财务场景的报表痛点集中在三层表头不是一行而是两到三层合并单元格结构比如“收入汇总”下面再拆“线上”“线下”线下再拆“微信”“支付宝”“银行卡”列不固定月初和月末的统计维度可能不一样表头结构也随之动态变化导出要走预置模板模板里已经有合并单元格、固定样式、公司Logo和底纹程序只负责往指定区域填充数据。这三个需求单拎出来任何一个都不算难一旦叠在一起EasyExcel的注解模型就开始捉襟见肘。最典型的场景是模板里有一个跨三行五列的合并单元格需要往里填充一个嵌套List每个子List又需要展示成多行同时还要保持合并区域的样式不出错。我最初以为这属于正常使用范围翻完EasyExcel的文档和issue才发现这块几乎没有开箱即用的解法。1.2 三个百度里问烂了却没标准答案的痛点我在决定迁移前把网上关于EasyExcel的这些高频问题翻了个遍问题现象搜索结果复杂表头导入多层合并单元格的表头解析后行列错位表头与数据列对不上大多建议自定义Listener但代码量很大且碰到样式合并边界容易失效模板填充合并单元格模板合并区域填充后合并区域自动消失或向上偏移一行issue里有讨论但官方回复模糊没有稳定修复嵌套List渲染一个单元格需要渲染一个List且自动换行、自动扩展行高需要自写样式和策略EasyExcel原生注解不直接支持NoSuchFieldError: factory引入新版后和POI版本冲突运行期直接抛异常网上方案多是降级或排除依赖治标不治本libfreetype6缺失在精简容器和某些Linux发行版上生成Excel时字体相关报错属于环境依赖问题需要额外安装系统库每一个问题单独看都不致命但凑在一起我手里的Excel导出代码变得越来越像“对EasyExcel内部逻辑的逆向修补”。于是我开始研究Apache Fesod。2. Apache Fesod的底层设计思路和EasyExcel差在哪2.1 从“帮我处理”到“你来定义”更容易摸到底的读写模型Fesod是Apache社区的一个Excel读写库项目和EasyExcel走的是完全不同的一条设计路线。EasyExcel的定位是“用注解声明规则框架帮你完成映射”它的好处是上手快坏处是一旦业务规则超出注解能表达的范围你需要去理解框架内部如何处理Row、Cell、合并区域和样式而这个内部逻辑对使用方几乎是个黑盒。Fesod则更接近“显式模型”的思路。它依然提供注解但核心不是靠注解驱动而是把一个Excel文件抽象成明确的数据结构Workbook对应Sheet集合每个Sheet包含HeaderArea和DataRegionHeaderArea可以显式定义层级和合并关系DataRegion则可以按行列坐标直接定位。这种设计让复杂表头的解析不再是一个“猜”的过程而是读取时就能还原真实结构。Fesod的典型使用方式分三层基础层直接操作Row和Cell和POI类似但API更简洁中间层提供内置的TableModel可以快速绑定普通数据集合高级层允许自定义Header和Region映射规则用于处理合并单元格、跨行跨列、嵌套List这类复杂结构。这种分层的好处是你想快的时候可以用现成模型你想精细控制的时候可以直接往下摸到具体Cell。而不是像EasyExcel那样注解不够就只能去继承并重写框架内部的Handler维护成本极高。2.2 模板填充和合并单元格不再是“渲染时的副作用”EasyExcel模板填充本质上仍然是“查找到指定占位符然后用数据替换单元格内容”。这个设计本身没有问题问题在于合并单元格和模板样式之间的处理顺序。填充时如果目标区域有合并单元格框架的默认行为经常是先拆掉合并填充后再尝试恢复一旦数据行数变化恢复逻辑就跟不上于是出现合并区域错位、样式丢失的问题。Fesod对模板的处理思路不同。它把模板里的合并单元格、列宽、行高、字体样式这些信息在填充之前先解析成本地化配置填充时严格遵循配置来重算合并区域范围。也就是说当你要往一个跨三行的合并单元格里填充一个包含10个元素的List时Fesod会先根据数据量计算目标区域的真实行数然后重新构建合并范围而不是填充完再事后修复。这个“先算后填”的机制是我最终决定切换的最核心原因。它让模板填充的代码逻辑变得可预测不再依赖框架内部对合并区域的处理顺序。3. 直接上代码把EasyExcel项目改造成Fesod的完整过程3.1 第一步替换依赖和入口API我原项目的核心依赖是EasyExcel改造第一步自然是换依赖。Maven配置从dependency groupIdcom.alibaba.nacoss/groupId artifactIdeasyexcel/artifactId version3.3.x/version /dependency换成了dependency groupIdorg.apache.fesod/groupId artifactIdfesod-core/artifactId version1.0.0/version /dependency dependency groupIdorg.apache.fesod/groupId artifactIdfesod-poi/artifactId version1.0.0/version /dependencyFesod的入口API风格比较直接写Excel用Fesod.write()读Excel用Fesod.read()再配合不同的模型来组织数据。相比EasyExcel的命名第一感受是API数量更少不需要记住那么多listener和converter的类名。3.2 第二步复杂表头导入用Fesod怎么解先来看导入场景。传统EasyExcel处理复杂表头时通常的思路是用注解标注表头的层级然后自定义Listener取数据。问题在于遇到合并单元格表头时第一行表头单元格的合并跨度容易被漏掉直接导致解析出来的数据整体错位一行或几列。Fesod的读入方式是把表头区域显式定义成HeaderLayer。我用一个实际例子来说明// 定义表头模型 HeaderLayer headerLayer new HeaderLayer(); headerLayer.addLevel(总营收, 0, 0, 2, 3); // 行0-2列0-3合并 headerLayer.addLevel(线上, 3, 0, 3, 1); // 行3列0-1合并 headerLayer.addLevel(线下, 3, 2, 3, 3); // 行3列2-3合并 // 读取Excel ListRowRecord records Fesod.read(new File(input.xlsx)) .sheet(0) .headers(headerLayer) .dataStartRow(4) .execute();这个代码片段里最关键的差异是表头的合并关系是显式声明的解析器在读取时会按照声明还原表头层级再决定每一列的数据归属。不会出现“解析完感觉表头对不上还得手动去调”的尴尬情况。如果你的项目里有大量不同结构的复杂表头文件需要导入可以把HeaderLayer的构建逻辑封装成配置类用JSON或数据库字段描述表头层级运行时动态生成。这样比每个文件写一套Listener要优雅得多。3.3 第三步模板填充合并单元格嵌套List的导出改造再来看我项目里最头疼的导出场景模板中有一个跨三行的合并单元格需要渲染一个嵌套List同时要保持模板的合并区域和样式。EasyExcel时代我的代码大致是// 这段代码是简化版实际还包含大量样式补偿逻辑 FillConfig fillConfig FillConfig.builder().forceNewRow(true).build(); excelWriter.fill(list, new FillWrapper(data, list), fillConfig);但这里有个常见坑forceNewRow(true)在处理合并单元格时并不能保证合并区域正确扩展经常出现List里的第二个元素就跑到合并区域外面去了。用Fesod写同样逻辑是这样的TemplateConfig templateConfig TemplateConfig.builder() .templateFile(new File(template.xlsx)) .registerRegion(new RegionRule(tradeList, 2, 1, 2, 5)) // 从第3行第2列到第3行第6列 .mergeStrategy(MergeStrategy.EXPAND_BY_DATA) .build(); ListTradeRecord tradeList loadTradeRecords(); Fesod.write(new File(output.xlsx)) .template(templateConfig) .bind(tradeList, tradeList) .execute();这里的关键是registerRegion与mergeStrategy的配合。RegionRule明确告诉Fesod数据要填充到哪一行哪一列的起始区域mergeStrategy决定数据量扩张时合并范围怎么重算。当tradeList有50行数据时Fesod会把原来3行的合并区域扩展为50行并且每一行的样式跟随模板。如果是嵌套List比如每个用户下面有多条交易记录Fesod也提供了分组填充模型。我改造后的核心代码类似于ListGroupedRowUserInfo, ListTradeRecord groupedData buildGroupedData(); Fesod.write(out) .template(templateConfig) .bindGroup(userGroup, groupedData) .subRegion(tradeList, (user, index) - user.getTrades()) .execute();这样每个用户渲染一行主信息用户对应的交易列表自动渲染在下一层区域合并样式和列宽完全按模板走。整个改造过程最直观的感受是我终于不需要再去写“填充后再扫描一次合并区域做修补”这种代码了。4. 迁移后的性能对比和内存表现4.1 耗时数据导入导出在真实数据量下表现如何换库不只是为了处理复杂结构我也担心性能会不会倒退。迁移完成后我拿实际业务数据做了一轮对比测试数据量分别是1万行、5万行和10万行文件结构是带两层合并表头的Excel。场景EasyExcel耗时Fesod耗时增量比例1万行导入1.6s1.8s12%5万行导入6.2s6.8s10%10万行导入11.5s12.4s8%1万行模板导出3.4s2.9s-15%5万行模板导出12.6s10.1s-20%10万行模板导出23.8s18.2s-24%导入场景Fesod略微慢一点点我认为可以接受毕竟它在解析表头层级上做了更多还原工作。导出场景反而是明显更快原因是Fesod在填充和合并处理上减少了重复扫描合并区域的额外开销。4.2 内存表现流式处理对GC更友好内存方面Fesod的读取也支持流式模式。常规读取时它并不一次性把整张表加载进JVM默认以Sheet为维度做流式解析只有在显式构建TableModel时才在内存里缓存数据。我用5万行、每行30列的Excel测试EasyExcel在读取高峰期的Young GC明显更频繁而Fesod的流式读取模式稳定在较低的内存水位。这一点在低配服务器上做批处理任务时可能影响很大。5. 迁移过程踩坑实录这些问题别等上线前才发现5.1 NoSuchFieldError: factory 这个坑是怎么避开的我在切换Fesod之后遇到的第一个坑不是Fesod自身的问题而是和历史项目里旧版POI的冲突。原本EasyExcel项目为了兼容老代码固定使用POI 4.1.2但Fesod依赖的POI版本更高运行期直接抛NoSuchFieldError。排查过程如下第一步看异常堆栈定位到报错类是org.apache.poi.xssf.usermodel.XSSFWorkbook拥有者factory字段引用缺失第二步用mvn dependency:tree检查POI版本发现EasyExcel、Fesod以及项目里另一个报表模块各引入了不同版本的POI第三步统一在父POM中用dependencyManagement锁定POI版本为Fesod推荐版本并排除掉其他模块的POI传递依赖。这里要提醒的是排除依赖要小心不只是POI还包括poi-ooxml和poi-ooxml-schemas这两个关联包否则启动时还会遇到类加载冲突。5.2 libfreetype6 缺失容器环境里最容易翻车的地方项目最终要部署到基于精简镜像构建的Docker容器里结果在生成带字体样式的Excel时Fesod底层渲染逻辑抛了缺少FreeType库的异常。这个和EasyExcel时代遇到的问题本质一样只是报错信息更直白。解决办法是在Dockerfile里显式安装系统依赖RUN apt-get update apt-get install -y libfreetype6 fontconfig同时把中文字体文件打入镜像不然即使库装好了导出的Excel里中文也可能变成方框。5.3 单元格换行问题导出后文本全部挤在一行还有一个容易忽略的细节。财务导出的Excel有些单元格内容需要强制换行展示。EasyExcel时代设置ExcelProperty加ContentStyle(wrapped true)即可迁移到Fesod后我一开始没有在模板单元格样式里预设WrapText导致填充进去的长文本全部挤在一行。Fesod对这种场景的推荐做法是在模板文件里预先将对应单元格设置为“自动换行”而不是仅依靠代码设置。因为代码设置样式在填充大量数据时会被频繁写入开销不小。迁移之后我养成了习惯凡是导出的模板先把样式诉求在Excel源文件里做好代码里只处理数据减少运行时样式覆盖的操作。5.4 别忽略旧代码里的“隐式依赖”最后再提一个项目改造里的常见盲区。项目里有一些代码不是直接调用EasyExcel的API而是通过自封装工具类间接使用。比如我们内部有个ExcelExportUtil方法签名上直接暴露了EasyExcel的ExcelWriter类型导致迁移时所有调用方编译不过。建议迁移前先全局搜一遍项目中所有导入EasyExcel包名的文件列个案清单再动手。如果工具类返回类型暴露了EasyExcel类记得改成Fesod的通用输出模型或直接返回File避免把上层调用方绑死在具体实现上。6. 迁移后的几点工作体会这次从EasyExcel迁移到Apache Fesod前后花了两周多其中一半时间花在排查老代码的隐式依赖和POI版本冲突上真正写新代码的时间并不多。我个人比较深的体会是EasyExcel在常规数据导入导出场景下确实很成熟文档多、社区大、遇到问题容易搜到答案。但当你反复碰到复杂表头、模板合并单元格、嵌套List这类进阶需求时框架本身的处理策略就成了天花板。Fesod把复杂结构当成“一等需求”来设计而不是当作注解模型的补丁这在后期维护上省下的精力非常可观。如果你现在的项目也在被类似问题困扰建议先不要急于把代码全部推翻。可以先挑一个最痛苦的导出模块做实验性迁移验证一下复杂表头和模板填充的表现再决定是否全量切换。毕竟工具只是手段业务数据不出错、代码好维护才是真正重要的事。