做后端开发或者日常写数据处理脚本的人几乎都会碰到一个绕不开的场景把业务方丢过来的 Excel 文件解析成程序能用的结构化数据。我在 Idea 里用 Hutool 这个工具类库做 Excel 文件读取前后也有好几年了从最开始图省事随手一写到后来在正式项目里封装成通用的导入模块中间踩的坑不算少。这篇文章就把这套东西完整摊开讲一遍——Hutool 是什么、它在 Idea 项目里怎么引入、ExcelReader 的核心 API 怎么用、遇到大文件和多 Sheet 怎么处理、以及那些文档里不会写但实际一定会撞上的问题。不管你是刚接触 Java 没多久、第一次被安排做导入功能的同学还是已经写过几轮导入、想把手里的代码收一收的老手下面这些内容应该都能直接用上。1. Hutool 读 Excel 这件事到底适合放在什么场景里1.1 一个真实需求把工具选型逼到台前先说我最近一次做 Excel 读取的真实背景。运营那边每个月要做一次合作商户的对账商户名单由对方提供格式是 xlsx字段大概有商户编号、商户名称、联系人、手机号、结算周期、开户行、银行账号这么七八列行数不多通常几百行偶尔上千。需求很朴素上传文件解析成列表做一次校验然后批量入库。听起来是个再简单不过的功能但真正动手的时候选项一大堆。用原生 Apache POI 写代码量大光是把单元格类型判断那一堆 if-else 写全就要小半天而且极容易漏掉日期格式和公式单元格。用 EasyExcel流式读取内存友好但对几百行的小文件来说有点杀鸡用牛刀而且它的 API 风格和 POI 差别不小团队里没写过的人要重新学。用 Hutool引入一个依赖三四行代码就能把整张表读成 List字段映射也不难。最后我选了 Hutool理由很简单这个场景的瓶颈不在性能而在开发速度和可读性。1.2 几种常见方案摆在一起对比把常见的几种 Excel 读取方案摊开对比一下选型思路会清晰很多。下面这张表是我根据自己实际用过的情况整理的不是绝对结论但能反映各自的性格。方案上手难度内存表现代码量适合的场景原生 Apache POI偏高DOM 模式吃内存多需要精细控制单元格、公式、样式的场景EasyExcel中等流式内存好中几十万行级别的大文件导入Hutool底层封 POI低DOM 模式随文件增长少中小文件、快速开发、内部工具JXL低一般少只处理老的 xls且不想引 POI直接当 CSV 读最低极好极少文件结构简单、无合并单元格、无样式看完这张表就能明白Hutool 的位置很明确它不跟你抢大文件导入的活它赢在中小文件上的开发效率。如果你手里的文件动不动几十万行那我建议直接上流式方案Hutool 全量载入的模式会让你在内存上很难受。1.3 Hutool 凭什么被我留下真正让我一直用 Hutool 的是几个很具体的细节。第一ExcelUtil.getReader()支持文件、输入流、路径三种入参接收前端上传的MultipartFile时直接拿getInputStream()传进去就行不用先落盘。第二read()方法会自动把首行当表头返回ListMapString, Object拿到之后按列名取值代码读起来像是在操作一个简易的数据表。第三setHeaderAlias()能把中文表头映射成英文字段业务方改个列名不用动代码逻辑。还有一点容易被忽略Hutool 的 Excel 模块本质是对 POI 的一层轻封装意味着底层能力并没有被剥夺。真遇到需要精细控制的单元格你随时可以通过reader.getWorkbook()拿到原生Workbook对象混着写。这种高层省事、底层可控的双层结构是它在实际项目里比很多纯封装库更耐用的原因。2. 在 Idea 里把 Hutool 装进项目2.1 Maven 依赖怎么写为什么建议拆开写最省事的写法是引全量包dependency groupIdcn.hutool/groupId artifactIdhutool-all/artifactId version5.8.25/version /dependency但我更推荐只引 POI 模块尤其是项目本身依赖已经比较多的时候dependency groupIdcn.hutool/groupId artifactIdhutool-poi/artifactId version5.8.25/version /dependency为什么建议拆开hutool-all把所有模块打包在一起虽然方便但在依赖分析阶段会让 Idea 的 Maven 面板里多出一堆用不到的传递依赖而且如果项目里同时引了别的工具库排查冲突时干扰项更多。hutool-poi只带 Excel 和 Word 相关的类传递引入 POI 的poi和poi-ooxml体积小、依赖链清楚。版本号这块Hutool 5.x 系列目前是主流5.8.x 的 API 相对稳定选一个较新的小版本即可不必追最新。注意如果你项目里已经通过别的途径引入了 POI比如为了做 Word 导出那么hutool-poi传递进来的 POI 版本可能和你原本的不一致这时候要在自己的dependencyManagement里统一锁定 POI 版本避免出现两份同名类。2.2 Gradle 项目的引入姿势用 Gradle 的话对应的写法是dependencies { implementation cn.hutool:hutool-poi:5.8.25 }Kotlin DSL 写成dependencies { implementation(cn.hutool:hutool-poi:5.8.25) }Gradle 有个比 Maven 更需要注意的点它默认会做依赖版本冲突解析选版本更高的那个。如果hutool-poi传递进来的 POI 版本比项目里其他地方引的高Gradle 会静默替换掉表面看不出来实际运行时可能出现方法找不到。排查的办法是在 Idea 的 Gradle 面板里执行dependencies任务看runtimeClasspath那棵树里org.apache.poi下面的版本到底是哪一个。2.3 在 Idea 里确认依赖真的进来了依赖写完点一下 Idea 右上角的刷新Maven 是那个带循环箭头的 Reload 按钮Gradle 是刷新图标。不确定有没有生效最直接的验证方式是在代码里敲ExcelUtil看能不能自动补全出来能补全说明索引到了。如果补全不出来去 External Libraries 下面找找有没有hutool-poi这一项。还有一种情况是依赖明明在但编译报程序包 cn.hutool.poi.excel 不存在。这种九成是 Idea 的缓存问题File菜单里做一次 Invalidate Caches 重启一般就恢复了。我第一次遇到的时候折腾了好久最后发现就是缓存没刷新白白怀疑了半天的网络。3. 把 ExcelReader 的核心用法拆开讲3.1 三种构造方式对应三种数据来源Hutool 读 Excel 的入口是ExcelUtil.getReader()它有几种重载对应不同的数据来源// 1. 从本地文件路径读 ExcelReader reader1 ExcelUtil.getReader(D:/data/merchant.xlsx); // 2. 从 File 对象读 ExcelReader reader2 ExcelUtil.getReader(new File(D:/data/merchant.xlsx)); // 3. 从输入流读接收前端上传文件时最常用 ExcelReader reader3 ExcelUtil.getReader(multipartFile.getInputStream());从输入流读这个能力在处理 Web 上传时特别顺手。前端传上来的文件往往是MultipartFile你不需要先transferTo存到临时目录再读直接取流就能解析。少了落盘这一步既省了磁盘 IO也避免了清理临时文件的问题。不过这里有个需要注意的点输入流读完之后一定要关闭。Hutool 的ExcelReader实现了Closeable正确做法是用 try-with-resources 包起来或者显式在 finally 里reader.close()。不关的话在 Windows 环境下文件句柄会一直被占着后续想删除或者覆盖这个文件就会失败。3.2 read 与 readAll 的区别什么时候用哪个ExcelReader上最常用的两个方法是read()和readAll()名字很像返回结构完全不同。readAll()返回ListListObject是一个纯粹的二维表每一行是一个 List按列的顺序排布。它不关心表头从第一行开始全部读进来。ExcelReader reader ExcelUtil.getReader(file); ListListObject rows reader.readAll(); // rows.get(0) 是第一行通常是表头 // rows.get(1) 开始才是数据 reader.close();read()返回ListMapString, Object它默认把第一行当作表头后续每一行组装成一个 Mapkey 是表头文字value 是单元格的值。取值的时候按列名取语义清晰。ExcelReader reader ExcelUtil.getReader(file); ListMapString, Object list reader.read(); for (MapString, Object row : list) { String name (String) row.get(商户名称); // 处理每一行 } reader.close();什么时候用哪个如果你的表结构固定、列顺序不会变readAll()更快更直接纯粹按位置取。如果列可能会调整顺序、或者表头文字对业务有意义read()更稳因为它靠列名而不是列索引定位。我自己的习惯是内部固定格式的模板文件用readAll()外部提供的、格式不完全可控的文件用read()。3.3 表头别名和数据类型处理read()用中文列名取值有个明显问题代码里到处是中文 key后期重构或者国际化会很别扭。Hutool 提供了setHeaderAlias()来解决ExcelReader reader ExcelUtil.getReader(file); MapString, String alias new LinkedHashMap(); alias.put(商户编号, merchantNo); alias.put(商户名称, merchantName); alias.put(联系人, contact); alias.put(手机号, mobile); reader.setHeaderAlias(alias); ListMapString, Object list reader.read();设置别名之后返回的 Map 里 key 就变成了你定义的英文字段名中文列名到字段名的映射关系集中在一处维护改起来也方便。数据类型这块Hutool 返回的值默认是 POI 解析出来的原始类型文本是 String数字可能是 Double日期是 Date布尔是 Boolean。这里有个我踩过不止一次的坑手机号、身份证号这类看起来像数字的字段如果 Excel 里没有明确按文本格式存储POI 会读成 Double。一个 13800138000 读出来变成 1.3800138E10直接存库就废了。解决办法有两个要么在读取时用CellEditor把这一列强制转成字符串要么在业务层判断类型后手动格式化。ExcelReader reader ExcelUtil.getReader(file); // 关闭默认的数字格式化让数值保持原样 reader.disableDefaultStyle();disableDefaultStyle()这个方法是用来关闭 Hutool 对样式的默认处理的在某些格式化场景下有用但要注意它影响的是样式输出不是值类型别搞混了。4. 从零实现一个能上生产的读取工具4.1 先把结果对象的字段定下来不管后面逻辑怎么写第一步一定是把 Excel 里的数据映射成一个明确的 Java 对象而不是在业务代码里到处Map.get()。我一般会定义这样一个类public class MerchantImportDTO { private String merchantNo; private String merchantName; private String contact; private String mobile; private String bankName; private String bankAccount; private Date settleDate; // getter / setter 省略 }有人会说直接BeanUtil.copyProperties一行就转过去了。确实可以Hutool 的BeanUtil配合read()返回的 Map 能自动填充字段代码短得惊人ListMapString, Object rows reader.read(); ListMerchantImportDTO list BeanUtil.copyToList(rows, MerchantImportDTO.class);但我要提醒一句自动拷贝虽然爽字段类型不匹配的时候它不一定报错可能静默给你塞个 null 或者类型转换失败后留空。生产环境的导入我还是建议老老实实逐字段赋值顺带做校验控制权在自己手里出问题也好定位。4.2 读取主流程代码逐段说明下面这个方法是封装好的完整读取流程把校验、转换、异常处理都串起来public ListMerchantImportDTO readMerchantExcel(InputStream inputStream) { ListMerchantImportDTO result new ArrayList(); try (ExcelReader reader ExcelUtil.getReader(inputStream)) { // 1. 指定别名把中文表头映射为英文字段 MapString, String alias new LinkedHashMap(); alias.put(商户编号, merchantNo); alias.put(商户名称, merchantName); alias.put(联系人, contact); alias.put(手机号, mobile); alias.put(开户行, bankName); alias.put(银行账号, bankAccount); alias.put(结算日期, settleDate); reader.setHeaderAlias(alias); // 2. 从第二行开始读第一行是表头 ListMapString, Object rows reader.read(0, 1); // 3. 逐行转换与校验 for (int i 0; i rows.size(); i) { MapString, Object row rows.get(i); MerchantImportDTO dto new MerchantImportDTO(); dto.setMerchantNo(StrUtil.trim(Convert.toStr(row.get(merchantNo)))); dto.setMerchantName(StrUtil.trim(Convert.toStr(row.get(merchantName)))); dto.setContact(StrUtil.trim(Convert.toStr(row.get(contact)))); dto.setMobile(formatMobile(row.get(mobile))); dto.setBankName(StrUtil.trim(Convert.toStr(row.get(bankName)))); dto.setBankAccount(formatAccount(row.get(bankAccount))); dto.setSettleDate(Convert.toDate(row.get(settleDate))); // 4. 必填校验 if (StrUtil.isBlank(dto.getMerchantNo())) { throw new IllegalArgumentException(第 (i 2) 行商户编号为空); } if (StrUtil.isBlank(dto.getMerchantName())) { throw new IllegalArgumentException(第 (i 2) 行商户名称为空); } result.add(dto); } } catch (IOException e) { throw new RuntimeException(读取 Excel 失败, e); } return result; }这里有几个值得展开说的点。reader.read(0, 1)这个重载第一个参数是表头所在行索引第二个参数是数据起始行索引。默认read()就是从第 0 行当表头、第 1 行开始是数据本质上等价。但显式写出来看代码的人一眼就知道你的表结构比默认行为更清楚。formatMobile()和formatAccount()是专门处理数字精度问题的两个小方法。手机号、银行账号这类超长数字POI 读出来可能是 Double也可能是科学计数法字符串统一格式化才能保证入库正确private String formatMobile(Object value) { if (value null) { return null; } if (value instanceof Double) { return new BigDecimal(value.toString()).toPlainString(); } return Convert.toStr(value).trim(); }用BigDecimal的toPlainString()而不是直接Double.toString()就是为了避免再冒出来科学计数法。这个细节不注意13800138000 会在某一步又变回 1.38E10。4.3 大文件与多 Sheet 的处理策略前面说过 Hutool 是全量载入所以文件大了必须换思路。我的判断标准大概是一万行以内Hutool 的read()完全够用内存占用在可接受范围内到了一万到十万行这个区间就要开始留意 JVM 堆大小必要时调大-Xmx超过十万行就别硬扛了改用 POI 的 SAX 事件模式或者别的流式方案。如果确实要用 Hutool 处理偏大的文件有一个操作能帮上忙只读数据、跳过样式处理。Excel 里如果数据量不大但带了一堆格式样式解析反而是大头。读取前可以调reader.disableDefaultStyle()减少一部分处理开销。不过这只是缓解不是根治。多 Sheet 是另一个高频场景。Hutool 的ExcelReader默认只读第一个 Sheet要读其他 Sheet 需要先切ExcelReader reader ExcelUtil.getReader(file); int sheetCount reader.getSheetCount(); for (int i 0; i sheetCount; i) { reader.setSheet(i); ListMapString, Object sheetData reader.read(); // 处理第 i 个 Sheet } reader.close();setSheet()既可以传索引也可以传 Sheet 名reader.setSheet(2024年1月);按名字切适合 Sheet 名有明确业务含义的情况比如按月份分 Sheet 的对账单。按索引切则适合 Sheet 名不固定、但顺序有约定俗成含义的场景。这里要注意一个顺序问题setSheet()必须写在read()之前写完read()之后再切 Sheet 是无效的因为数据已经读出来了。我第一次用的时候就犯过这个错切了 Sheet 发现数据没变还以为方法坏了。5. 踩过的坑与排查清单5.1 依赖冲突引发的 NoClassDefFoundError这是最容易在项目集成阶段卡住人的一类问题。表现是代码编译通过运行时报NoClassDefFoundError或者NoSuchMethodError堆栈里指向org.apache.poi下面的某个类。根本原因通常是项目里存在多份 POI或者 POI 的版本和 Hutool 期望的不一致。排查顺序我一般是这样走先在 Idea 的 Maven/Gradle 面板里看依赖树搜索org.apache.poi确认最终生效的是哪个版本。如果发现有多个版本被不同路径引进来就在dependencyManagement里统一锁死。dependencyManagement dependencies dependency groupIdorg.apache.poi/groupId artifactIdpoi-ooxml/artifactId version5.2.3/version /dependency /dependencies /dependencyManagement锁版本之后一定要重新刷新依赖再跑一次。很多人锁完不刷新还以为问题没解决。另外POI 5.x 相比 4.x 有一些包路径调整从老项目升级过来时特别注意这个,如果代码里直接用了 POI 的类可能也要跟着改。5.2 日期、精度和空单元格三个高频陷阱这三个问题我几乎每做一个新项目就会碰到一两个做成长度、类型、空值三张清单会直观很多问题现象根本原因解决办法日期读出来是数字 45000 这种Excel 内部日期存的是序列号格式决定显示用Convert.toDate()转换或自定义 CellEditor手机号变成 1.38E10数字被当作 Double 处理用 BigDecimal 转字符串或用文本格式列空单元格读成 null 或空字符串POI 对空白单元格不创建对象读取后统一用StrUtil.isBlank()判断整数 100 读成 100.0POI 数字类型统一是 Double业务层判断后取整或单元格本身设为整数格式日期这个问题尤其容易迷惑人。一个看起来正常的日期列程序读出来却是 45000 这样的数字因为 Excel 底层把日期存成从 1900 年某个基准日算起的天数显示成日期只是格式渲染的结果。Hutool 的Convert.toDate()能处理大部分情况但如果你拿到的本来就是数字它可能转不明白这时候要靠单元格的格式信息来判断。5.3 内存溢出与线程安全内存溢出的典型症状是OutOfMemoryError: Java heap space堆栈指向 POI 的XSSFWorkbook或者 SAX 解析那块。前面反复说了Hutool 全量载入文件大了必然吃内存。有一次我接了个用户上传的 Excel单看行数才两万但里面塞了大量的样式和批注读的时候直接 OOM。后来把读取逻辑拆成校验行数、分片处理先看文件大小和 Sheet 数超过阈值就提示用户拆分上传问题就没了。线程安全这块ExcelReader不是线程安全的一个实例同时在多个线程里 read 会出问题。多线程处理多个文件时每个线程各自创建自己的ExcelReader不要复用。如果要做并发读取用线程池把任务拆开每个任务内部独立开 reader、独立关闭。提示处理不可信来源的 Excel 时最好限制单次上传的文件大小和 Sheet 数量。既有安全考虑也能避免单个请求把服务内存拖垮。5.4 排查速度清单把上面这些整理成一个快速排查清单遇到问题时对着过一遍能省不少时间。编译不过、包找不到先刷新依赖再 Invalid Caches 重启 Idea。运行时报 POI 相关异常查依赖树统一 POI 版本。数字精度不对检查单元格类型用 BigDecimal 转字符串。日期不对确认是序列号还是 Date用Convert.toDate()或自定义编辑器。空值报错所有取值处统一做 null 和空字符串判断。内存溢出评估文件规模超过阈值换流式方案或限制上传大小。数据只读到一部分确认setSheet()在read()之前调用确认数据起始行参数没写错。最后分享一个我在实际封装里养成的小习惯任何一次 Excel 导入都在读取的同一层记一条日志写清楚文件大小、Sheet 数、解析行数、耗时。看着不起眼但线上真出问题的时候这条日志往往是定位到底是文件问题还是逻辑问题的第一手依据。导入功能这东西写起来快出事的时候没有可观测的线索才是最要命的。