SpringBoot与EasyExcel实现Excel导入：从Upload到批量入库的完整方案

简介：这份资料面向需要快速实现 Excel 导入功能的 Java 全栈开发者，内容围绕 SpringBoot 与 AntDesignVue 的联调展开，重点讲解 upload 组件的 accept、customRequest、change 事件使用，并给出前后端完整实现思路。压缩包共 1 个 PDF 文件，大小约 198KB，便于在电脑或手机上直接阅读。该资源已吸引 2437 人浏览学习，适合正在开发后台管理系统、需要处理批量数据导入场景的初中级开发者参考。PDF 中不仅包含前端组件配置、自定义上传方法与加载状态切换，还提供了后端 Controller 和 Service 层的接收处理示例，能够帮助读者快速理解从文件上传到数据解析入库的完整链路，节省排查接口对接问题的时间。整体以实际项目片段为切入点，代码脉络清晰，可直接迁移到同类管理后台中使用。

1. Excel导入看着简单，为什么总是翻车：SpringBoot与AntDesignVue这条链路的真实复杂度

SpringBoot 后端加 AntDesignVue 前端，是后台管理系统里最常见的组合。而 Excel 导入功能恰恰是这个组合里最容易被低估的需求：表面上就是“选个文件传上去，后端读一下 Excel 再写库”，实际做起来几乎每一层都有坑。前端传上去的文件格式和后端解析器对不上、Excel 里的日期单元格读出来是一串数字、全空行被当成合法数据、文件超过 1MB 直接 500，这些场景我都在真实项目里遇到过。这篇文章把我自己在这种需求上的完整落地方案拆开讲：从前端 Upload 组件的拦截，到 SpringBoot 接收文件、EasyExcel 解析映射、数据校验与批量入库，最后单独列一张高频坑清单。适合正在写管理系统、准备接导入功能，或者接手了一个导入模块正被各种奇怪数据折磨的开发者。

2. 技术选型与链路设计：把导入需求拆成三段，每一段的责任都划清楚

2.1 一条导入链路拆成三段看，责任边界就清楚了

Excel 导入看上去是一个功能，实际上是一条跨前端的链路。我一般把它拆成三段来设计，每一段只负责一件事，这样后面排查问题时不用从头到尾把所有代码翻一遍。

第一段是前端拦截，负责两件事：把用户选中的文件按后端约定送过去，同时在格式、大小明显不合理时提前拦住。第二段是后端接收与解析，负责限制上传大小、校验文件后缀、读取 Excel 并把每一行映射成 Java 对象。第三段是校验与落库，负责业务规则校验、批量写入和结果统计。注意，这里有一个很容易犯的错：把“解析”和“校验”混在同一段代码里。解析失败和校验失败的处理方式完全不同，解析失败是文件格式问题，校验失败是数据内容问题，混在一起会让接口返回的提示语变得很难写清楚。

链路拆好之后，选型就顺理成章了。前端用 AntDesignVue 的 Upload 组件，后端在解析层选 EasyExcel，落库用 SpringBoot 自带的 JdbcTemplate 或项目里的 ORM。下面先聊解析层的选型，这是整个功能里最影响代码结构和运行内存的一环。

2.2 EasyExcel 与 POI 的取舍：不是谁替代谁，是看导入场景的复杂度

很多开发者在导入需求上纠结过一个问题：直接用 POI 写，还是用 EasyExcel。我得先说明一个事实：EasyExcel 底层基于 POI，它不是替代关系，而是在 POI 的读取模型上做了一层封装。POI 的典型写法是按 Workbook、Sheet、Row、Cell 一层层手动遍历，逻辑上是清晰的，但代码量很大。一个带表头、日期转换、空行过滤的基础导入，POI 版少说要写一两百行，而且一不小心就会踩内存泄漏的坑。

我做过一次对比，把同一份 6 万行数据的导入分别用 POI 和 EasyExcel 实现，结论很有代表性：

纯导入场景，我的结论是直接选 EasyExcel。但有一个前提要提前和产品对齐：统一用 xlsx 格式。如果你要兼容 xls 老文件，EasyExcel 的解析支持并不完整，遇到带格式的 xls 文件容易解析出乱数据，这种场景不如回到 POI 用 HSSFWorkbook 写。大多数后台管理系统里的导入需求，是用户从某个系统导出的 xlsx，模板固定、列头固定，EasyExcel 的注解映射方式刚好够用。

2.3 把最小链路先跑通：SpringBoot 接收文件并同步解析出数据

选型定了，先用一个最小可跑的示例把链路打通。不要一上来就写监听器、事务、批量 insert，先用同步读取把“前端传文件、后端收文件、解析出数据”这段链路验证一遍。

后端先加依赖，我这里不写死版本号，直接用你项目里已有的依赖管理或 BOM 统一控制版本：

<dependency> <groupId>com.alibaba</groupId> <artifactId>easyexcel</artifactId> <version>${easyexcel.version}</version> </dependency>

依赖加好后，写一个最简单的接收接口：

@RestController @RequestMapping("/api/import") public class UserImportController { @PostMapping("/demo") public String demo(@RequestParam("file") MultipartFile file) throws IOException { List<UserImportDTO> rows = EasyExcel.read(file.getInputStream()) .head(UserImportDTO.class) .headRowNumber(1) .sheet() .doReadSync(); return "解析到 " + rows.size() + " 行"; } }

注意这里的两个参数。headRowNumber(1) 表示文件第一行是表头，解析时跳过；如果你的模板表头占两行，例如第一行是大标题、第二行才是字段名，就把这个值改成 2。sheet() 不传参数时默认读第一个 sheet，也可以传 sheet(0) 按下标读，或 sheet("用户导入") 按名称读。doReadSync() 表示同步读取并把所有行收集成 List，这个写法只适合小文件快速验证，生产环境不要用，原因下一章讲监听器时会展开。

跑通这一步时，可以先在浏览器里用 AntDesignVue 的 Upload 组件随便传一个 xlsx 文件，后端返回的行数能对上，就说明整条链路的传输和解析没问题了。接下来就是把这套最小代码替换成生产可用的完整实现。

3. 后端解析与入库的关键实现：注解映射、监听器与批量写入

3.1 用 @ExcelProperty 把 Excel 列映射成对象：index 与 value 两种模式

Excel 是一张二维表，Java 对象是一组字段，映射关系是导入功能的翻译层。EasyExcel 用 @ExcelProperty 注解来完成这个翻译。这个注解有两种用法，我各说一遍。

第一种是按表头名称映射，value 填 Excel 里的列头文字：

public class UserImportDTO { @ExcelProperty(value = "姓名") private String name; @ExcelProperty(value = "部门") private String department; @ExcelProperty(value = "入职日期") private Date hireDate; }

这种写法的好处是表头顺序变化时不用改代码，缺点是表头文字必须和 Excel 里完全一致，多一个空格、少一个空格都会导致那一列读出来是 null。第二种是按列下标映射，index 填列的序号，从 0 开始：

public class UserImportDTO { @ExcelProperty(value = "姓名", index = 0) private String name; @ExcelProperty(value = "部门", index = 1) private String department; @ExcelProperty(value = "入职日期", index = 2) private Date hireDate; }

我这里两个参数都写了。实际项目里，我的习惯是 index 为主，value 只作为可读性注释。原因很简单：一旦导入模板固定，字段顺序就不会变，index 模式最稳定；而当用户拿了一个乱序的 Excel 来传时，value 模式会因为表头对不上而静默返回 null，这个排查成本比改代码高得多。

字段类型这块要提前约定。日期列直接声明为 Date 时，Excel 里的单元格必须是真正的日期格式或文本格式的“yyyy-MM-dd”，这个我在避坑章节会专门讲。数字列声明为 BigDecimal，不要声明为 double，Excel 单元格里的浮点精度问题会让金额类字段出现一堆小数尾巴。

3.2 用 ReadListener 监听器替换 doReadSync：边读边处理，而不是全部载入内存

doReadSync 的用法在第 2 章演示过，它的实现方式是把整个 sheet 读完后一次性返回 List。对于几千行的数据没问题，但数据量到几万行时，内存占用和 GC 压力会明显上升。生产环境下我统一用 ReadListener 监听器模式。

public class UserImportListener implements ReadListener<UserImportDTO> { private final List<UserImportDTO> rows = new ArrayList<>(); @Override public void invoke(UserImportDTO row, AnalysisContext context) { if (isAllFieldNull(row)) { return; } rows.add(row); } @Override public void doAfterAllAnalysed(AnalysisContext context) { // 解析结束后的收尾逻辑，这里暂时留空 } private boolean isAllFieldNull(UserImportDTO row) { return row.getName() == null && row.getDepartment() == null && row.getHireDate() == null; } }

invoke 方法会在每一行数据解析出来时被回调，这是 EasyExcel 基于 SAX 事件模型的核心机制，读一行回调一行，不会把整个工作表都载入内存。这里的 isAllFieldNull 检查是必要的，Excel 里的隐藏空行或被格式残留的行，都可能被解析出一个全部字段为 null 的对象，不拦截的话后面校验逻辑会误报“姓名为空”。doAfterAllAnalysed 在解析完后调用，适合放汇总逻辑。

Controller 里的写法相应改掉：

@PostMapping("/import") public ImportResult importUsers(@RequestParam("file") MultipartFile file) throws IOException { UserImportListener listener = new UserImportListener(); EasyExcel.read(file.getInputStream(), UserImportDTO.class, listener) .headRowNumber(1) .ignoreEmptyRow(true) .sheet() .doRead(); return userImportService.doImport(listener.getRows()); }

ignoreEmptyRow(true) 是让 EasyExcel 在读取时跳过真正没有数据的空行，减少多余的 invoke 回调。但注意，这个参数管不了“单元格有残留格式、肉眼看不到数据”的行，所以监听器里的全字段 null 判断不能省。另外，Controller 里做了解析，业务校验放在 Service 里，这个分层是刻意的：Controller 只负责拿到 MultipartFile 并触发解析，拿到行数据后交给 Service 处理。事务边界在 Service 层，解析过程本身不参与事务。

3.3 行级校验与批量落库：事务边界、错误收集与批次大小

解析拿到的是格式正确的对象列表，但业务上还能更严格。例如姓名字段为空、日期格式合法但是未来日期、同一部门重复导入，这些都要在落库前校验。我建议把校验统一放在 Service 层，并且把错误信息收集成列表，一次性返回给前端，而不是遇到第一行错误就中断整个导入。用户拿到一份“第 3 行：姓名为空；第 7 行：入职日期格式不正确”的清单，比拿到“导入失败”四个字有用得多。

@Service public class UserImportService { private final JdbcTemplate jdbcTemplate; public ImportResult doImport(List<UserImportDTO> rows) { ImportResult result = new ImportResult(); List<String> errors = new ArrayList<>(); List<Object[]> validRows = new ArrayList<>(); for (int i = 0; i < rows.size(); i++) { UserImportDTO row = rows.get(i); List<String> rowErrors = validateRow(row); if (!rowErrors.isEmpty()) { for (String error : rowErrors) { errors.add("第" + (i + 2) + "行：" + error); } } else { validRows.add(new Object[]{row.getName(), row.getDepartment(), row.getHireDate()}); } } if (!errors.isEmpty()) { return result.fail(errors); } jdbcTemplate.batchUpdate( "INSERT INTO t_user(name, department, hire_date) VALUES (?, ?, ?)", validRows, 500 ); return result.success(validRows.size()); } private List<String> validateRow(UserImportDTO row) { List<String> errors = new ArrayList<>(); if (row.getName() == null || row.getName().trim().isEmpty()) { errors.add("姓名为空"); } if (row.getDepartment() == null || row.getDepartment().trim().isEmpty()) { errors.add("部门为空"); } return errors; } }

这里说三个关键点。第一，行号计算是 i + 2，因为 Excel 第一行是表头，数组中下标 0 对应的实际是 Excel 第 2 行，给用户报错时一定要按 Excel 里的真实行号来，否则用户去 Excel 里找错误行永远对不上。第二，batchUpdate 方法传了第三参数 500，表示每 500 条数据执行一次批量提交，这个值可以根据数据库连接池和表结构调整，太小批量效果不明显，太大单次 SQL 包过长。第三，我的习惯是解析阶段只做格式校验，业务校验像“部门是否在系统里存在”这类查库操作，也放在 Service 层的这个方法里统一做，避免在监听器的 invoke 回调里查库，否则每读一行就查一次数据库，几万行数据会把数据库连接池拖垮。

4. 前端 AntDesignVue Upload 组件的落地写法：文件校验、进度与模板下载

4.1 a-upload 的最小配置：action、name、headers 与 accept

AntDesignVue 的 Upload 组件封装了文件选择、上传、进度展示和结果回调，后台导入功能用它最省事。先看一个最小可用的写法：

<template> <a-upload name="file" action="/api/import/import" :headers="uploadHeaders" accept=".xlsx,.xls" :before-upload="beforeUpload" :disabled="uploading" :show-upload-list="true" @change="handleChange" > <a-button type="primary" :loading="uploading">选择 Excel 文件</a-button> </a-upload> </template> <script setup> import { ref, computed } from 'vue'; import { message } from 'ant-design-vue'; const uploading = ref(false); const token = localStorage.getItem('token'); const uploadHeaders = computed(() => ({ Authorization: `Bearer ${token}`, })); const beforeUpload = (file) => { const validType = file.name.endsWith('.xlsx') || file.name.endsWith('.xls'); if (!validType) { message.error('只能上传 xlsx 或 xls 格式的 Excel 文件'); return false; } return true; }; const handleChange = (info) => { const { status } = info.file; if (status === 'uploading') { uploading.value = true; } else if (status === 'done') { uploading.value = false; const resp = info.file.response; if (resp && resp.success) { message.success(`导入成功${resp.data}条`); } else { message.error(resp?.message || '导入失败'); } } else if (status === 'error') { uploading.value = false; message.error('上传请求失败，请检查网络或联系管理员'); } }; </script>

这个写法里有几个参数说明。action 是上传接口地址，name 是表单字段名，后端用 @RequestParam("file") 接收时必须对得上，前端默认就叫 file，后端参数名也保持 file 最省事。headers 用来带登录凭证，后台管理系统一般都有接口鉴权，Upload 组件的请求是浏览器原生发的，不会自动带 axios 里的拦截器，所以用 headers 手动注入。accept 只是文件选择对话框的过滤，用户依然可以把文件后缀改成 pdf 然后强选，所以真正的文件类型校验必须放在 beforeUpload 里。

4.2 beforeUpload 把不合法文件拦截在请求发出之前

beforeUpload 在文件上传前被调用，返回 false 会阻止上传动作。它比 accept 更可靠，因为 accept 只影响系统文件选择器展示哪些文件，不限制拖拽和“所有文件”选项。我一般在 beforeUpload 里做两层检查：后缀名和文件大小。

const MAX_SIZE = 10 * 1024 * 1024; // 10MB const beforeUpload = (file) => { const validType = file.name.endsWith('.xlsx') || file.name.endsWith('.xls'); if (!validType) { message.error('只能上传 xlsx 或 xls 格式的 Excel 文件'); return Upload.LIST_IGNORE; } if (file.size > MAX_SIZE) { message.warning('文件大小不能超过 10MB'); return Upload.LIST_IGNORE; } return true; };

Upload.LIST_IGNORE 是 Upload 组件提供的静态常量，返回它之后文件不会出现在上传列表里，也不会触发上传，这是比返回 false 更干净的处理方式。返回 false 虽然也能阻止上传，但文件会残留在一个异常状态，用户看到列表里有个没传上去的文件，体验很怪。

文件大小的上限，我在公式里用的是 10MB。这个值不是拍脑袋定的，而是从业务角度推出来的：模板导入表一般就是几十列，10MB 的 xlsx 大约对应大几万行数据，这个量级用同步导入还能接受；如果你的业务里模板列少、数据行极多，可以把上限调到 20MB，但这时候就必须考虑下一章的异步导入了。

4.3 模板下载与导入结果回显：从“能导入”到“好导入”

把导入功能做成被人愿意用的功能，模板下载和清晰的结果回显比解析代码更影响体验。模板下载我一般放在导入按钮旁边，一个普通按钮即可：

<a-button style="margin-left: 8px" @click="downloadTemplate">下载模板</a-button>

const downloadTemplate = () => { const url = '/api/import/template'; const authHeader = `Bearer ${localStorage.getItem('token')}`; fetch(url, { headers: { Authorization: authHeader } }) .then((res) => res.blob()) .then((blob) => { const link = document.createElement('a'); link.href = URL.createObjectURL(blob); link.download = '用户导入模板.xlsx'; link.click(); URL.revokeObjectURL(link.href); }); };

这里不要用 window.location.href 直接跳转，因为带不了 Authorization 头，还得在 URL 后面拼 token，会留下安全隐患。用 fetch 拿 Blob 再触发下载，凭证走 header，干净很多。后端模板接口很简单，用 EasyExcel 的 write 方法输出一个带表头、不带数据的空模板即可，核心是让用户看到列头、列顺序和示例格式，别让他自己猜。

结果回显方面，我的习惯是后端不管成功失败都返回 HTTP 200，业务状态用响应体里的 success 字段区分，前端拿到 response 后只按业务字段处理。如果后端直接返回 500，浏览器会把响应当上传错误处理，这时你再想拿到“第 5 行：姓名为空”这种错误清单就很难了，因为错误信息会被 Upload 组件包装成一段 HTML 或默认错误文本。

5. Excel导入避坑指南：日期格式、空行、大小限制和内存爆掉的排查记录

5.1 上传 xls 文件后解析出 0 行数据

现象：用户上传了一个 .xls 后缀的 Excel，后端接口返回“解析到 0 行”，也不报错。这个坑很隐蔽，因为接口状态是成功的，只是数据为空，用户会怀疑是模板问题，而不是代码问题。

原因：EasyExcel 对 xlsx 走的是 SAX 事件解析，对老版 xls 格式走的是 POI 的 HSSF 兼容层。xls 文件里如果带了特殊格式、宏或者旧版单元格样式，HSSF 兼容层可能读不出数据，而且不会主动报异常。用户那边看到的文件明明有内容，导入结果却是空的，排查起来非常折腾。

解决：前端和后端都只接受 xlsx，不接受 xls。后端在 Controller 里对文件名做个后缀校验，非 xlsx 直接返回“请上传 xlsx 格式文件”。如果业务上确实有大量 xls 历史文件要兼容，用 POI 按 HSSFWorkbook 手动解析，不要指望 EasyExcel 在这类文件上表现稳定。

5.2 日期列读出 43831 这种数字

现象：Excel 里日期显示为“2023-01-01”，但导入后数据库里存的是 43831，或者代码断点看到 Date 字段的值不对劲。43831 其实是 Excel 内部对 2023-01-01 的数值表示方式，Excel 日期本质上就是一个从 1900 年开始算的天数。

原因：Excel 单元格如果本来是数值类型，即使显示成日期格式，底层存的还是 double 数值。POI 在读取这种单元格时按数值类型处理，EasyExcel 的 Date 类型映射需要依赖单元格格式是文本或约定的日期字符串。用户在原表里复制粘贴数据时，很容易把日期列变成数值列。

解决：模板里约定日期列必须是文本格式，并在模板的示例行里写出“2023-01-01”这样的标准格式，同时在后端 DTO 里对日期字段写一个 Converter，做两层兜底。Converter 的写法是继承 EasyExcel 的 AbstractConverter，在 convertToJavaData 方法里判断传入值是不是数字，如果是数字就按天数转成 Date。这一步属于编码细节，但它是导入功能稳定性的一个分水岭。

5.3 隐藏空行被当成合法数据，校验报“第 88 行：姓名为空”

现象：导入一条数据后，返回的错误列表里有大量空白行的报错，用户却坚持说 Excel 里没有这些行，打开文件看也确实没有。

原因：用户从其他系统导出的 Excel 经常带着隐藏行，或者某些单元格只设置了格式但没有内容。这类行不是真正的空行，EasyExcel 的 ignoreEmptyRow 不会把它们过滤掉，监听器的 invoke 仍然会收到一个全字段为 null 的对象。

解决：监听器里必须像第 3 章写的那样做全字段 null 判断，null 数据直接 return。同时，这类行不仅影响导入，还会把错误列表刷得很难看，用户看到几十条空白行报错会直接放弃排查。我一般还会在 Service 层判断一下，如果错误行里全是 null 行，就统一忽略，不把它们计入错误清单。

5.4 文件 1MB 多一点就上传失败，接口直接 500

现象：前端选了一个 1.2MB 的 Excel，点上传后很快在浏览器开发者工具里看到请求返回 500，后端日志报 MaxUploadSizeExceededException。更奇怪的是，换一个 900KB 的文件就正常。

原因：SpringBoot 的 servlet 上传限制默认 max-file-size 是 1MB。这个默认值很多开发不知道，第一次遇到时完全摸不着头脑，因为报错信息不是前端能看懂的。日志里的 MaxUploadSizeExceededException 是关键词。

解决：在 application.yml 里配置上传大小，同时把异常兜底返回 JSON：

spring: servlet: multipart: max-file-size: 10MB max-request-size: 10MB

max-file-size 限制单个文件，max-request-size 限制整个请求体。如果你同时上传文件和其他表单字段，建议把 max-request-size 设置得比 max-file-size 略大。另外要在全局异常处理器里捕获 MaxUploadSizeExceededException，返回“文件大小不能超过 10MB”这样的中文提示。这个异常如果不捕获，SpringBoot 默认返回 500，前端拿到的是泛化的错误信息，用户根本不知道发生了什么。

5.5 导入 5 万行数据时接口内存爆掉

现象：测试环境导入几千行没问题，首次导入 5 万行真实数据时接口直接 OOM 或者耗时几十秒，服务端 CPU 飙高。

原因：两个叠加的问题。第一，代码里用的是 doReadSync，把所有行一次性收集到 List；第二，落库时如果是逐条 insert，5 万次要和数据库交互 5 万次，单次虽然快，累计时间非常可观。内存和耗时双双失控。

解决：把 doReadSync 换成 ReadListener 监听器模式，数据行边读边放入有界队列，攒够 500 条就 flush 一次批量写入。这里有一个关键点：flush 之后要把已处理的行从队列里清掉，不能既监听又全量收集。我在第 3 章的代码里用的是“全量收集”策略，那是为了事务和校验清晰考虑，但它只适合一万行以内。超过这个量级，就要把策略改成“边读边校验边分批写”，事务边界改为“每一批一个小事务”，这样内存占用和数据库压力都稳定。

6. 再往前走两个方向：模板驱动的通用导入与异步导入

6.1 模板驱动的通用导入：把映射配置抽出来，一个模块一个模块接入

当系统里有多个地方需要导入功能时，不要每个模块复制一份导入代码。我把导入设计成模板驱动的通用组件：后端只提供一个通用接口，入参是模板编号和上传文件，具体映射关系、校验器、落库逻辑通过一个配置文件或注册表来维护。每个模块只需要做两件事：定义自己的 DTO 类并配置列映射，提供一个校验器实现。解析和落库的公共逻辑由通用组件完成。

这样设计的好处是，后续新增一个导入模块只需要写一个类，不用动公共代码。开发新功能时，我一般先看看以前的导入模块能不能直接套用，套不了再改公共部分，这样导入功能的维护成本会低很多。

6.2 异步导入：文件上传后立即返回，后台轮询任务进度

超过 10 万行的导入，不建议用同步接口。用户等不起，前端请求也会超时。我的做法是拆成两个接口：上传接口接收到文件后，把导入任务提交给线程池，立即返回一个任务 ID；前端拿到任务 ID 后定时轮询“导入进度”接口，拿当前处理行数和失败明细。这个设计还顺带解决了大数据量场景下的用户体验问题——用户不用一直盯着转圈，可以去做别的事，完成后再回来看结果。

异步导入的复杂度主要在后端：监听器里的分批写库要改成“每批更新一次进度”，失败明细要落库而不是返回给前端，任务状态要用一张表维护。如果你的项目里有消息队列，也可以把解析任务丢到队列里，效果类似。

6.3 我的验证习惯与收尾

导入功能上线前，我会准备三张测试表：第一张是正常数据表，覆盖所有列的正常值，验证主流程；第二张是错误数据表，故意制造空行、错误日期、超长字符串、重复数据，验证错误清单的准确性和行号是否对齐；第三张是边界表，包含空文件、只有表头的文件、xls 老格式文件，验证接口的健壮性。这三张表我建议保存到测试资源目录里，每次改代码后跑一遍回归，比临时造数据可靠得多。导入功能最怕的不是代码逻辑复杂，而是改了一行解析逻辑后，某个隐藏的数据格式突然把整批数据搞乱，而你又没有测试表去验证。我现在接手任何项目的第一件事，就是先看它的导入功能有没有这样一组测试文件，没有就先补上。希望帮到你。

本文还有配套的精品资源，点击获取