1. 批量导入这件事为什么值得单独拿出来聊做过后台系统的人大概率都碰过这个需求运营或者业务方丢过来一个 Excel几百上千行数据要求批量导入到系统里。表面上看这就是个读文件、写数据库的活儿但真正落地的时候坑远比想象中多。用户传上来的表格里可能有空行、有格式错乱、有手机号少一位、有必填字段没填、有重复数据、有外键对不上的脏数据。你如果只是简单粗暴地全量插入要么整批失败回滚用户一脸懵不知道哪行错了要么部分成功部分失败数据状态混乱事后根本没法追溯。所以一个成熟的批量导入功能核心诉求从来不是能读 Excel而是能读、能校验、能反馈、能追溯。具体来说就是四件事第一把 Excel 里的数据准确读出来第二逐行做业务校验区分出哪些能入库、哪些不能第三给用户一个明确的反馈——成功多少条、失败多少条、每条失败的原因是什么第四把失败的那些行原样导出成一个新 Excel放到指定路径让用户下载下来改完再传。这个标题描述的正是这样一套完整的闭环方案技术选型用的是 EasyExcel。为什么是 EasyExcel 而不是 Apache POI因为 POI 的 DOM 解析模式会把整个文件加载进内存一个几万行的 Excel 就能把 JVM 撑爆而 EasyExcel 基于 SAX 的事件驱动模型逐行读取内存占用极低这是它在批量导入场景里几乎成为默认选择的原因。这套方案适合谁适合所有正在做后台管理系统、数据中台、运营工具的后端开发尤其是那些被导入失败用户天天来问哪行错了折磨过的同学。下面我把这套东西从设计思路到落地细节完整拆一遍包括我踩过的坑和最后沉淀下来的写法。2. 整体方案设计与核心思路拆解2.1 为什么要把读取和校验分开很多人写导入功能习惯在 EasyExcel 的AnalysisEventListener的invoke方法里直接做校验加插入读一行处理一行。这个写法在数据量小、逻辑简单的时候没问题但一旦校验规则变复杂代码就会变成一坨意大利面而且有个致命问题你没法做批量优化。比如你想用insertBatch一次性插 500 条读一行插一行就完全用不上批量插入的性能优势。我的做法是把流程拆成三段读取阶段只负责把 Excel 每一行映射成 Java 对象不做任何业务判断校验阶段遍历这批对象逐行跑校验规则把通过的和失败的分别收集到两个集合里落库与导出阶段把通过的整体批量入库失败的写回一个新 Excel。这样拆的好处是每一段职责单一校验规则可以随时增删批量插入也能用上。代价是内存里会同时持有全量数据所以如果单次导入量特别大比如超过 5 万行需要额外做分批处理这个后面会讲。2.2 成功/失败数量与原因的数据结构设计反馈给用户的结果不能只是一个导入完成的提示得是一个结构化的对象。我一般会定义一个ImportResult类里面包含总条数totalCount、成功条数successCount、失败条数failCount、失败明细列表failList、失败文件路径failFilePath。失败明细里每一条包含行号rowIndex和失败原因errorMsg。这里有个细节值得说行号一定要记录。用户拿到失败文件后最想知道的就是我原表格的第几行错了。EasyExcel 在读取时可以通过AnalysisContext拿到当前行号但要注意它默认是从 0 开始算的而用户眼里的行号是从 1 开始而且第一行通常是表头所以实际展示给用户的行号要做context.readRowHolder().getRowIndex() 1这样的换算否则用户按你给的行号去找永远差一行体验极差。2.3 失败文件为什么要落到系统路径而不是直接返回流标题里明确说了导出到系统路径中这是个很务实的选择。直接返回文件流给前端下载适合小文件即时下载但批量导入的失败文件往往需要用户稍后处理甚至需要留档追溯落到服务器指定目录比如/data/import/fail/或者项目下的upload/fail/更合适。系统路径下可以按时间戳或业务类型建子目录文件名带上时间戳避免覆盖同时把路径存到数据库的导入记录表里用户随时能回来下载。注意落盘路径一定要做权限控制和目录存在性检查。我见过因为目标目录不存在导致FileNotFoundException把整个导入流程搞挂的案例写文件前先mkdirs()是基本操作。3. 核心细节解析与实操要点3.1 EasyExcel 读取模型的几个关键配置EasyExcel 读取的核心是EasyExcel.read()配合一个继承自AnalysisEventListenerT的监听器。这里有几个参数必须搞清楚否则会踩坑。第一个是headRowNumber指定表头占几行。默认是 1如果你的 Excel 表头有两行比如合并单元格的大标题加字段名就要设成 2否则第一行数据会被当成表头吃掉。第二个是sheetNo或sheetName指定读哪个 sheet多 sheet 的 Excel 不指定会读错。第三个是doReadSync()和doRead()的区别doReadSync()会同步返回一个 List代码写起来简单适合中小数据量doRead()是异步回调配合监听器自己收集数据适合大数据量做流式处理。我一般用doReadSync()因为后面要做批量校验本来就需要拿到全量数据。实体类上用ExcelProperty注解映射列这里有个强烈建议用列名映射而不是列索引。用ExcelProperty(手机号)比ExcelProperty(index 3)稳得多因为用户调整列顺序是常事用索引一旦列顺序变了就全错位用列名则不受影响。当然前提是表头文字要固定如果表头也会变那就得用自定义的head匹配策略了。3.2 校验规则的分类与执行顺序校验规则我习惯分三类按顺序执行因为后面的规则可能依赖前面的结果格式校验字段是否为空、长度是否超限、手机号/邮箱/身份证格式是否正确、数字是否能解析。这类校验不依赖数据库纯内存判断最快。业务校验枚举值是否合法比如状态字段只能是启用/禁用、日期范围是否合理、金额是否为正数。这类也不依赖数据库。数据校验手机号是否已存在、关联的部门 ID 是否存在、编码是否重复。这类需要查库最慢所以放最后前面能拦掉的就不查库了。这个顺序的意义在于性能。假设 1000 行数据格式校验能拦掉 300 行业务校验再拦掉 100 行最后只有 600 行需要查库比一上来就 1000 行全查库省了 40% 的数据库压力。别小看这个优化导入高峰期这点差距很关键。3.3 失败 Excel 的导出实现失败文件的导出本质上是把失败的行重新写成一个 Excel。这里有两种做法一种是把原始行数据原样保留加上一列失败原因另一种是只导出关键字段加失败原因。我推荐第一种因为用户需要对照原始数据修改字段越全越好。实现上用 EasyExcel 的写功能定义一个导出用的实体类字段和导入实体一致额外加一个errorMsg字段。把失败列表写进去EasyExcel.write(filePath, FailExcelVO.class).sheet(失败数据).doWrite(failList)一行搞定。文件名建议用导入失败数据_业务类型_yyyyMMddHHmmss.xlsx这种格式既清晰又不会重名。实操心得导出实体类的字段顺序要和导入模板保持一致用户改完直接重新上传不用再调整列顺序。另外失败原因那一列建议放在最后一列不要插在中间否则用户改完再传容易因为列错位出问题。4. 完整实操流程与核心环节实现4.1 依赖引入与基础配置先引入 EasyExcel 依赖。以 Maven 为例用较新的稳定版本即可dependency groupIdcom.alibaba/groupId artifactIdeasyexcel/artifactId version3.3.2/version /dependency这里提醒一句EasyExcel 3.x 和 2.x 的 API 有差异网上很多老教程是 2.x 的写法直接抄会编译不过。3.x 里EasyExcel.read()的用法基本没变但一些监听器的接口方法签名调整过注意版本对齐。另外 EasyExcel 内部依赖了 POI如果项目里已经有 POI注意版本冲突必要时用exclusions排除掉传递依赖。4.2 导入实体类的定义假设我们要导入的是一批用户数据实体类这样定义Data public class UserImportVO { ExcelProperty(姓名) private String name; ExcelProperty(手机号) private String phone; ExcelProperty(部门编码) private String deptCode; ExcelProperty(状态) private String status; ExcelIgnore private Integer rowIndex; }ExcelIgnore标注的rowIndex不参与 Excel 映射是我们自己用来记录行号的。注意Data是 Lombok 的注解如果项目没用 Lombok手动写 getter/setter 即可。4.3 读取监听器的实现虽然我用doReadSync()拿全量数据但行号的记录还是得靠监听器。可以写一个简单的监听器在invoke里给每个对象塞上行号public class UserImportListener extends AnalysisEventListenerUserImportVO { private final ListUserImportVO dataList new ArrayList(); Override public void invoke(UserImportVO data, AnalysisContext context) { // 行号从 0 开始1 转成用户视角再 1 跳过表头 data.setRowIndex(context.readRowHolder().getRowIndex() 1); dataList.add(data); } Override public void doAfterAllAnalysed(AnalysisContext context) { // 读取完成后的回调这里可以留空 } public ListUserImportVO getDataList() { return dataList; } }然后读取的时候这样用UserImportListener listener new UserImportListener(); EasyExcel.read(inputStream, UserImportVO.class, listener) .headRowNumber(1) .sheet() .doRead(); ListUserImportVO list listener.getDataList();这里headRowNumber(1)表示表头一行。如果你的模板有标题行改成 2。4.4 校验逻辑的落地校验我封装成一个方法返回一个包含成功列表和失败列表的结果对象public ImportCheckResult check(ListUserImportVO list) { ListUserImportVO successList new ArrayList(); ListFailRow failList new ArrayList(); // 先收集已存在的手机号避免循环里反复查库 SetString existPhones userMapper.selectAllPhones(); for (UserImportVO vo : list) { String error validateRow(vo, existPhones); if (error null) { successList.add(vo); } else { failList.add(new FailRow(vo.getRowIndex(), error, vo)); } } return new ImportCheckResult(successList, failList); }validateRow里按前面说的三类规则顺序判断返回第一个错误原因就够不用把所有错误都堆给用户那样反而看不清。比如private String validateRow(UserImportVO vo, SetString existPhones) { if (StringUtils.isBlank(vo.getName())) { return 姓名不能为空; } if (!PhoneUtil.isValid(vo.getPhone())) { return 手机号格式不正确; } if (existPhones.contains(vo.getPhone())) { return 手机号已存在; } if (!启用.equals(vo.getStatus()) !禁用.equals(vo.getStatus())) { return 状态只能是启用或禁用; } return null; }注意existPhones这个优化如果每行都去select count(*) where phone ?1000 行就是 1000 次查询慢得离谱。一次性把已存在的手机号全查出来放内存里比对性能提升是数量级的。当然如果数据量特别大全量查出来内存也扛不住那就得分批查或者用布隆过滤器这是另一个话题了。4.5 批量入库与失败文件导出校验完成后成功列表批量入库失败列表导出文件// 批量入库每 500 条一批 if (!successList.isEmpty()) { Lists.partition(successList, 500).forEach(batch - userMapper.insertBatch(batch)); } // 导出失败文件 String failFilePath null; if (!failList.isEmpty()) { String dir /data/import/fail/; File dirFile new File(dir); if (!dirFile.exists()) { dirFile.mkdirs(); } String fileName 导入失败数据_ System.currentTimeMillis() .xlsx; failFilePath dir fileName; ListFailExcelVO excelList failList.stream() .map(f - new FailExcelVO(f.getRowIndex(), f.getErrorMsg(), f.getData())) .collect(Collectors.toList()); EasyExcel.write(failFilePath, FailExcelVO.class) .sheet(失败数据) .doWrite(excelList); }Lists.partition是 Guava 的工具把大列表切成小批次。为什么要分批因为 MySQL 的insert语句有长度限制一次插太多会报PacketTooLarge而且单条 SQL 太大也会拖慢事务。500 是个经验值具体看字段多少字段多就调小到 200。4.6 结果对象的组装与返回最后把结果组装好返回给前端ImportResult result new ImportResult(); result.setTotalCount(list.size()); result.setSuccessCount(successList.size()); result.setFailCount(failList.size()); result.setFailFilePath(failFilePath); result.setFailList(failList.stream() .map(f - new FailItem(f.getRowIndex(), f.getErrorMsg())) .collect(Collectors.toList())); return result;前端拿到这个对象就能展示共导入 1000 条成功 850 条失败 150 条并给出失败文件的下载链接。如果失败条数不多也可以直接把失败明细展示在页面上用户不用下载文件就能看到问题。5. 常见问题与排查技巧实录5.1 读取时数据错位或读不到最常见的原因是表头行数配置不对。如果 Excel 第一行是合并单元格的大标题第二行才是字段名headRowNumber必须设成 2。另一个原因是ExcelProperty的列名和实际表头文字对不上比如表头是手机号码你写的是手机号那就映射不上字段全是 null。排查方法很简单把读到的对象打印出来看哪个字段是 null再去核对表头文字。还有一种情况是用户传的 Excel 是.xls老格式EasyExcel 虽然支持但某些特殊格式会解析异常。稳妥做法是在上传时就限制只接受.xlsx并在前端给出明确提示。5.2 大数据量导入内存溢出虽然 EasyExcel 读取本身是低内存的但如果你用doReadSync()把全量数据读进 List再加上校验时的各种集合几万行数据还是可能 OOM。解决办法是分批处理读一批比如 2000 行就校验一批、入库一批、清空集合再读下一批。EasyExcel 的监听器天然支持这种流式处理在invoke里累积到阈值就触发一次处理逻辑即可。5.3 失败文件导出后中文乱码或打不开中文乱码通常是文件名编码问题尤其是通过 HTTP 响应头返回文件时要对文件名做 URL 编码。如果是落盘的文件本身乱码检查写入时的字符集。文件打不开多半是写入流没关闭EasyExcel 的doWrite内部会处理关闭但如果你自己包了OutputStream就要注意。另外并发导出同一个文件名会互相覆盖所以文件名一定要带时间戳或 UUID。5.4 校验查库导致的性能瓶颈前面提过逐行查库是性能杀手。除了批量预查还可以用缓存。比如部门编码这种变化不频繁的数据启动时加载到本地缓存校验时直接查缓存。如果校验规则涉及多个表考虑把关联数据一次性 join 出来而不是循环里多次单表查询。下面这张表是我整理的高频问题速查问题现象可能原因排查方向字段全为 null列名不匹配或表头行数错核对ExcelProperty与表头文字行号对不上未做行号换算检查getRowIndex的偏移处理导入中途报错单批 SQL 过大减小批量插入的批次大小失败文件覆盖文件名无唯一标识文件名加时间戳或 UUID内存溢出全量数据驻留内存改流式分批处理校验慢循环内查库批量预查或加缓存5.5 几个容易被忽略的细节第一空行处理。用户表格末尾经常有空白行EasyExcel 默认会跳过完全空的行但如果某行只有一两个单元格有空格可能被当成有效数据。建议在校验第一步就判断关键字段是否全空全空直接跳过不计入总数。第二数字精度问题。Excel 里的数字如果被读成double大整数会丢精度比如订单号202301011234567890读出来可能变成科学计数法。解决办法是把这类字段在实体里定义成String并在读取时用ExcelProperty配合converter指定按字符串读。第三事务边界。批量入库要不要包在一个事务里如果要求要么全成功要么全失败那就包事务但批量导入场景通常允许部分成功所以不建议包大事务否则一条失败全批回滚用户还得重传。我的做法是每批一个小事务失败的那批单独记录。第四并发导入。同一个用户短时间内重复点击导入按钮可能触发两次导入导致数据重复。前端要做按钮防抖后端可以用分布式锁按用户维度加锁或者用导入任务表做幂等控制。6. 我在这套方案上踩过的坑和沉淀下来的经验聊完流程说几个只有真正落地过才会知道的细节。第一个是关于失败原因的措辞。一开始我写的是手机号已存在结果用户来问哪个手机号存在了因为失败文件里只有行号和原因用户还得自己回去找。后来我改成手机号 138xxxx1234 已存在把具体值带上用户一眼就能定位。这个改动很小但客服咨询量明显下降。第二个是关于失败文件的清理。落到系统路径的文件不会自己消失时间一长磁盘就满了。我后来加了个定时任务每天凌晨清理 7 天前的失败文件同时在数据库里保留导入记录用户如果超过 7 天要文件就提示已过期需要重新导入。这个策略要和业务方对齐别自己拍脑袋定。第三个是关于校验规则的配置化。早期校验规则是硬编码在 Java 里的每次业务方要加个校验比如备注不能超过 50 字都得改代码发版。后来我把常用规则抽成了配置比如必填字段、长度限制、正则表达式都放到配置表里改规则不用发版。当然复杂的业务校验还是得写代码但至少把那些机械的格式校验解放出来了。第四个是关于大文件的进度反馈。如果导入要跑几十秒用户盯着转圈会以为卡死了。可以在导入任务表里记录进度前端轮询查询已处理 300/1000体验会好很多。这个不是必须的但做了之后用户满意度提升明显。这套方案我从最早用 POI 手写解析到后来换成 EasyExcel中间重构过好几次最后沉淀下来的就是上面这些。核心其实就一句话把读取、校验、落库、反馈这四件事拆开每件事做扎实用户要的成功失败数量和原因自然就清晰了。失败文件导出到系统路径这个设计看似是个小需求但它解决的是用户改完能立刻重传的闭环问题这才是批量导入功能真正好用的关键。 
长河君 · 2026/10/17 1:12:02 · 阅读 1.2k EasyExcel批量导入实战：校验、失败导出与系统路径落盘方案
1. 批量导入这件事为什么值得单独拿出来聊做过后台系统的人大概率都碰过这个需求运营或者业务方丢过来一个 Excel几百上千行数据要求批量导入到系统里。表面上看这就是个读文件、写数据库的活儿但真正落地的时候坑远比想象中多。用户传上来的表格里可能有空行、有格式错乱、有手机号少一位、有必填字段没填、有重复数据、有外键对不上的脏数据。你如果只是简单粗暴地全量插入要么整批失败回滚用户一脸懵不知道哪行错了要么部分成功部分失败数据状态混乱事后根本没法追溯。所以一个成熟的批量导入功能核心诉求从来不是能读 Excel而是能读、能校验、能反馈、能追溯。具体来说就是四件事第一把 Excel 里的数据准确读出来第二逐行做业务校验区分出哪些能入库、哪些不能第三给用户一个明确的反馈——成功多少条、失败多少条、每条失败的原因是什么第四把失败的那些行原样导出成一个新 Excel放到指定路径让用户下载下来改完再传。这个标题描述的正是这样一套完整的闭环方案技术选型用的是 EasyExcel。为什么是 EasyExcel 而不是 Apache POI因为 POI 的 DOM 解析模式会把整个文件加载进内存一个几万行的 Excel 就能把 JVM 撑爆而 EasyExcel 基于 SAX 的事件驱动模型逐行读取内存占用极低这是它在批量导入场景里几乎成为默认选择的原因。这套方案适合谁适合所有正在做后台管理系统、数据中台、运营工具的后端开发尤其是那些被导入失败用户天天来问哪行错了折磨过的同学。下面我把这套东西从设计思路到落地细节完整拆一遍包括我踩过的坑和最后沉淀下来的写法。2. 整体方案设计与核心思路拆解2.1 为什么要把读取和校验分开很多人写导入功能习惯在 EasyExcel 的AnalysisEventListener的invoke方法里直接做校验加插入读一行处理一行。这个写法在数据量小、逻辑简单的时候没问题但一旦校验规则变复杂代码就会变成一坨意大利面而且有个致命问题你没法做批量优化。比如你想用insertBatch一次性插 500 条读一行插一行就完全用不上批量插入的性能优势。我的做法是把流程拆成三段读取阶段只负责把 Excel 每一行映射成 Java 对象不做任何业务判断校验阶段遍历这批对象逐行跑校验规则把通过的和失败的分别收集到两个集合里落库与导出阶段把通过的整体批量入库失败的写回一个新 Excel。这样拆的好处是每一段职责单一校验规则可以随时增删批量插入也能用上。代价是内存里会同时持有全量数据所以如果单次导入量特别大比如超过 5 万行需要额外做分批处理这个后面会讲。2.2 成功/失败数量与原因的数据结构设计反馈给用户的结果不能只是一个导入完成的提示得是一个结构化的对象。我一般会定义一个ImportResult类里面包含总条数totalCount、成功条数successCount、失败条数failCount、失败明细列表failList、失败文件路径failFilePath。失败明细里每一条包含行号rowIndex和失败原因errorMsg。这里有个细节值得说行号一定要记录。用户拿到失败文件后最想知道的就是我原表格的第几行错了。EasyExcel 在读取时可以通过AnalysisContext拿到当前行号但要注意它默认是从 0 开始算的而用户眼里的行号是从 1 开始而且第一行通常是表头所以实际展示给用户的行号要做context.readRowHolder().getRowIndex() 1这样的换算否则用户按你给的行号去找永远差一行体验极差。2.3 失败文件为什么要落到系统路径而不是直接返回流标题里明确说了导出到系统路径中这是个很务实的选择。直接返回文件流给前端下载适合小文件即时下载但批量导入的失败文件往往需要用户稍后处理甚至需要留档追溯落到服务器指定目录比如/data/import/fail/或者项目下的upload/fail/更合适。系统路径下可以按时间戳或业务类型建子目录文件名带上时间戳避免覆盖同时把路径存到数据库的导入记录表里用户随时能回来下载。注意落盘路径一定要做权限控制和目录存在性检查。我见过因为目标目录不存在导致FileNotFoundException把整个导入流程搞挂的案例写文件前先mkdirs()是基本操作。3. 核心细节解析与实操要点3.1 EasyExcel 读取模型的几个关键配置EasyExcel 读取的核心是EasyExcel.read()配合一个继承自AnalysisEventListenerT的监听器。这里有几个参数必须搞清楚否则会踩坑。第一个是headRowNumber指定表头占几行。默认是 1如果你的 Excel 表头有两行比如合并单元格的大标题加字段名就要设成 2否则第一行数据会被当成表头吃掉。第二个是sheetNo或sheetName指定读哪个 sheet多 sheet 的 Excel 不指定会读错。第三个是doReadSync()和doRead()的区别doReadSync()会同步返回一个 List代码写起来简单适合中小数据量doRead()是异步回调配合监听器自己收集数据适合大数据量做流式处理。我一般用doReadSync()因为后面要做批量校验本来就需要拿到全量数据。实体类上用ExcelProperty注解映射列这里有个强烈建议用列名映射而不是列索引。用ExcelProperty(手机号)比ExcelProperty(index 3)稳得多因为用户调整列顺序是常事用索引一旦列顺序变了就全错位用列名则不受影响。当然前提是表头文字要固定如果表头也会变那就得用自定义的head匹配策略了。3.2 校验规则的分类与执行顺序校验规则我习惯分三类按顺序执行因为后面的规则可能依赖前面的结果格式校验字段是否为空、长度是否超限、手机号/邮箱/身份证格式是否正确、数字是否能解析。这类校验不依赖数据库纯内存判断最快。业务校验枚举值是否合法比如状态字段只能是启用/禁用、日期范围是否合理、金额是否为正数。这类也不依赖数据库。数据校验手机号是否已存在、关联的部门 ID 是否存在、编码是否重复。这类需要查库最慢所以放最后前面能拦掉的就不查库了。这个顺序的意义在于性能。假设 1000 行数据格式校验能拦掉 300 行业务校验再拦掉 100 行最后只有 600 行需要查库比一上来就 1000 行全查库省了 40% 的数据库压力。别小看这个优化导入高峰期这点差距很关键。3.3 失败 Excel 的导出实现失败文件的导出本质上是把失败的行重新写成一个 Excel。这里有两种做法一种是把原始行数据原样保留加上一列失败原因另一种是只导出关键字段加失败原因。我推荐第一种因为用户需要对照原始数据修改字段越全越好。实现上用 EasyExcel 的写功能定义一个导出用的实体类字段和导入实体一致额外加一个errorMsg字段。把失败列表写进去EasyExcel.write(filePath, FailExcelVO.class).sheet(失败数据).doWrite(failList)一行搞定。文件名建议用导入失败数据_业务类型_yyyyMMddHHmmss.xlsx这种格式既清晰又不会重名。实操心得导出实体类的字段顺序要和导入模板保持一致用户改完直接重新上传不用再调整列顺序。另外失败原因那一列建议放在最后一列不要插在中间否则用户改完再传容易因为列错位出问题。4. 完整实操流程与核心环节实现4.1 依赖引入与基础配置先引入 EasyExcel 依赖。以 Maven 为例用较新的稳定版本即可dependency groupIdcom.alibaba/groupId artifactIdeasyexcel/artifactId version3.3.2/version /dependency这里提醒一句EasyExcel 3.x 和 2.x 的 API 有差异网上很多老教程是 2.x 的写法直接抄会编译不过。3.x 里EasyExcel.read()的用法基本没变但一些监听器的接口方法签名调整过注意版本对齐。另外 EasyExcel 内部依赖了 POI如果项目里已经有 POI注意版本冲突必要时用exclusions排除掉传递依赖。4.2 导入实体类的定义假设我们要导入的是一批用户数据实体类这样定义Data public class UserImportVO { ExcelProperty(姓名) private String name; ExcelProperty(手机号) private String phone; ExcelProperty(部门编码) private String deptCode; ExcelProperty(状态) private String status; ExcelIgnore private Integer rowIndex; }ExcelIgnore标注的rowIndex不参与 Excel 映射是我们自己用来记录行号的。注意Data是 Lombok 的注解如果项目没用 Lombok手动写 getter/setter 即可。4.3 读取监听器的实现虽然我用doReadSync()拿全量数据但行号的记录还是得靠监听器。可以写一个简单的监听器在invoke里给每个对象塞上行号public class UserImportListener extends AnalysisEventListenerUserImportVO { private final ListUserImportVO dataList new ArrayList(); Override public void invoke(UserImportVO data, AnalysisContext context) { // 行号从 0 开始1 转成用户视角再 1 跳过表头 data.setRowIndex(context.readRowHolder().getRowIndex() 1); dataList.add(data); } Override public void doAfterAllAnalysed(AnalysisContext context) { // 读取完成后的回调这里可以留空 } public ListUserImportVO getDataList() { return dataList; } }然后读取的时候这样用UserImportListener listener new UserImportListener(); EasyExcel.read(inputStream, UserImportVO.class, listener) .headRowNumber(1) .sheet() .doRead(); ListUserImportVO list listener.getDataList();这里headRowNumber(1)表示表头一行。如果你的模板有标题行改成 2。4.4 校验逻辑的落地校验我封装成一个方法返回一个包含成功列表和失败列表的结果对象public ImportCheckResult check(ListUserImportVO list) { ListUserImportVO successList new ArrayList(); ListFailRow failList new ArrayList(); // 先收集已存在的手机号避免循环里反复查库 SetString existPhones userMapper.selectAllPhones(); for (UserImportVO vo : list) { String error validateRow(vo, existPhones); if (error null) { successList.add(vo); } else { failList.add(new FailRow(vo.getRowIndex(), error, vo)); } } return new ImportCheckResult(successList, failList); }validateRow里按前面说的三类规则顺序判断返回第一个错误原因就够不用把所有错误都堆给用户那样反而看不清。比如private String validateRow(UserImportVO vo, SetString existPhones) { if (StringUtils.isBlank(vo.getName())) { return 姓名不能为空; } if (!PhoneUtil.isValid(vo.getPhone())) { return 手机号格式不正确; } if (existPhones.contains(vo.getPhone())) { return 手机号已存在; } if (!启用.equals(vo.getStatus()) !禁用.equals(vo.getStatus())) { return 状态只能是启用或禁用; } return null; }注意existPhones这个优化如果每行都去select count(*) where phone ?1000 行就是 1000 次查询慢得离谱。一次性把已存在的手机号全查出来放内存里比对性能提升是数量级的。当然如果数据量特别大全量查出来内存也扛不住那就得分批查或者用布隆过滤器这是另一个话题了。4.5 批量入库与失败文件导出校验完成后成功列表批量入库失败列表导出文件// 批量入库每 500 条一批 if (!successList.isEmpty()) { Lists.partition(successList, 500).forEach(batch - userMapper.insertBatch(batch)); } // 导出失败文件 String failFilePath null; if (!failList.isEmpty()) { String dir /data/import/fail/; File dirFile new File(dir); if (!dirFile.exists()) { dirFile.mkdirs(); } String fileName 导入失败数据_ System.currentTimeMillis() .xlsx; failFilePath dir fileName; ListFailExcelVO excelList failList.stream() .map(f - new FailExcelVO(f.getRowIndex(), f.getErrorMsg(), f.getData())) .collect(Collectors.toList()); EasyExcel.write(failFilePath, FailExcelVO.class) .sheet(失败数据) .doWrite(excelList); }Lists.partition是 Guava 的工具把大列表切成小批次。为什么要分批因为 MySQL 的insert语句有长度限制一次插太多会报PacketTooLarge而且单条 SQL 太大也会拖慢事务。500 是个经验值具体看字段多少字段多就调小到 200。4.6 结果对象的组装与返回最后把结果组装好返回给前端ImportResult result new ImportResult(); result.setTotalCount(list.size()); result.setSuccessCount(successList.size()); result.setFailCount(failList.size()); result.setFailFilePath(failFilePath); result.setFailList(failList.stream() .map(f - new FailItem(f.getRowIndex(), f.getErrorMsg())) .collect(Collectors.toList())); return result;前端拿到这个对象就能展示共导入 1000 条成功 850 条失败 150 条并给出失败文件的下载链接。如果失败条数不多也可以直接把失败明细展示在页面上用户不用下载文件就能看到问题。5. 常见问题与排查技巧实录5.1 读取时数据错位或读不到最常见的原因是表头行数配置不对。如果 Excel 第一行是合并单元格的大标题第二行才是字段名headRowNumber必须设成 2。另一个原因是ExcelProperty的列名和实际表头文字对不上比如表头是手机号码你写的是手机号那就映射不上字段全是 null。排查方法很简单把读到的对象打印出来看哪个字段是 null再去核对表头文字。还有一种情况是用户传的 Excel 是.xls老格式EasyExcel 虽然支持但某些特殊格式会解析异常。稳妥做法是在上传时就限制只接受.xlsx并在前端给出明确提示。5.2 大数据量导入内存溢出虽然 EasyExcel 读取本身是低内存的但如果你用doReadSync()把全量数据读进 List再加上校验时的各种集合几万行数据还是可能 OOM。解决办法是分批处理读一批比如 2000 行就校验一批、入库一批、清空集合再读下一批。EasyExcel 的监听器天然支持这种流式处理在invoke里累积到阈值就触发一次处理逻辑即可。5.3 失败文件导出后中文乱码或打不开中文乱码通常是文件名编码问题尤其是通过 HTTP 响应头返回文件时要对文件名做 URL 编码。如果是落盘的文件本身乱码检查写入时的字符集。文件打不开多半是写入流没关闭EasyExcel 的doWrite内部会处理关闭但如果你自己包了OutputStream就要注意。另外并发导出同一个文件名会互相覆盖所以文件名一定要带时间戳或 UUID。5.4 校验查库导致的性能瓶颈前面提过逐行查库是性能杀手。除了批量预查还可以用缓存。比如部门编码这种变化不频繁的数据启动时加载到本地缓存校验时直接查缓存。如果校验规则涉及多个表考虑把关联数据一次性 join 出来而不是循环里多次单表查询。下面这张表是我整理的高频问题速查问题现象可能原因排查方向字段全为 null列名不匹配或表头行数错核对ExcelProperty与表头文字行号对不上未做行号换算检查getRowIndex的偏移处理导入中途报错单批 SQL 过大减小批量插入的批次大小失败文件覆盖文件名无唯一标识文件名加时间戳或 UUID内存溢出全量数据驻留内存改流式分批处理校验慢循环内查库批量预查或加缓存5.5 几个容易被忽略的细节第一空行处理。用户表格末尾经常有空白行EasyExcel 默认会跳过完全空的行但如果某行只有一两个单元格有空格可能被当成有效数据。建议在校验第一步就判断关键字段是否全空全空直接跳过不计入总数。第二数字精度问题。Excel 里的数字如果被读成double大整数会丢精度比如订单号202301011234567890读出来可能变成科学计数法。解决办法是把这类字段在实体里定义成String并在读取时用ExcelProperty配合converter指定按字符串读。第三事务边界。批量入库要不要包在一个事务里如果要求要么全成功要么全失败那就包事务但批量导入场景通常允许部分成功所以不建议包大事务否则一条失败全批回滚用户还得重传。我的做法是每批一个小事务失败的那批单独记录。第四并发导入。同一个用户短时间内重复点击导入按钮可能触发两次导入导致数据重复。前端要做按钮防抖后端可以用分布式锁按用户维度加锁或者用导入任务表做幂等控制。6. 我在这套方案上踩过的坑和沉淀下来的经验聊完流程说几个只有真正落地过才会知道的细节。第一个是关于失败原因的措辞。一开始我写的是手机号已存在结果用户来问哪个手机号存在了因为失败文件里只有行号和原因用户还得自己回去找。后来我改成手机号 138xxxx1234 已存在把具体值带上用户一眼就能定位。这个改动很小但客服咨询量明显下降。第二个是关于失败文件的清理。落到系统路径的文件不会自己消失时间一长磁盘就满了。我后来加了个定时任务每天凌晨清理 7 天前的失败文件同时在数据库里保留导入记录用户如果超过 7 天要文件就提示已过期需要重新导入。这个策略要和业务方对齐别自己拍脑袋定。第三个是关于校验规则的配置化。早期校验规则是硬编码在 Java 里的每次业务方要加个校验比如备注不能超过 50 字都得改代码发版。后来我把常用规则抽成了配置比如必填字段、长度限制、正则表达式都放到配置表里改规则不用发版。当然复杂的业务校验还是得写代码但至少把那些机械的格式校验解放出来了。第四个是关于大文件的进度反馈。如果导入要跑几十秒用户盯着转圈会以为卡死了。可以在导入任务表里记录进度前端轮询查询已处理 300/1000体验会好很多。这个不是必须的但做了之后用户满意度提升明显。这套方案我从最早用 POI 手写解析到后来换成 EasyExcel中间重构过好几次最后沉淀下来的就是上面这些。核心其实就一句话把读取、校验、落库、反馈这四件事拆开每件事做扎实用户要的成功失败数量和原因自然就清晰了。失败文件导出到系统路径这个设计看似是个小需求但它解决的是用户改完能立刻重传的闭环问题这才是批量导入功能真正好用的关键。