企业官网建设流程全解析

简介：这份PDF面向使用SpringBoot与AntDesignVue开发管理系统的前后端开发者，聚焦Excel导入这一常见业务场景，提供从组件配置到接口落地的完整实现参考。内容围绕Ant Design Vue的upload组件展开，涵盖通过accept限定xlsx与xls文件类型、以customRequest接管默认上传、用change监听上传中、完成、失败状态，并结合loading图标与按钮禁用避免大数据量导入时的重复点击；同时说明FormData封装文件参数、沿用项目axios请求方法的做法，后端则给出Controller使用MultipartFile接收文件、Service解析并写入学生信息表的示例。资源包仅含1个PDF文件，约198KB，篇幅轻量、重点集中，适合快速查阅关键代码与前后端联调思路。目前已有2440人学习，可作为管理系统导入功能的实现模板，也便于开发者对照梳理参数命名、状态反馈与异常处理等细节。

1. 从「导入按钮被连点三次」说起：SpringBoot + AntDesignVue 的 Excel 导入，真正难的是那四道关口

一个两百来行的学生信息表，用户嫌页面没反应，连点了三次导入，数据库里多出六百条重复记录——这是 SpringBoot + AntDesignVue 做 Excel 导入时最典型的出错场景。前端 a-upload 组件不会拦第二次点击，后端 saveBatch 也不会帮你查重，依赖用户自觉就一定会出问题。这套方案的骨架并不复杂：前端用 Ant Design Vue 的 upload 组件配合 customRequest 接管上传，后端用 MultipartFile 接收，再用 POI 的 XSSFWorkbook 逐行解析，最后 MyBatis-Plus 批量写入数据库。决定它能不能上生产的，不是这几行代码写得漂不漂亮，而是文件类型校验、上传状态机、单元格类型判定、事务回滚这四道关口有没有堵死。这篇拆解适合已经搭好前后端架子、准备把导入做成通用能力的同学，前端部分看得懂 Vue，后端部分看得懂 Spring 注解就能跟上。

2. 前端上传链路：customRequest 接管之后，a-upload 还替你管什么

a-upload 有两种活法：给一个 action 让它自己发请求，或者用 customRequest 把发请求的活抢过来自己干。项目里百分之九十的麻烦都来自第一种——组件内部的 XMLHttpRequest 不经过你的 axios 拦截器，token 带不上、统一错误码解析不了、baseURL 和代理配置还可能冲突。抢过来之后，组件退化成「选文件 + 维护状态」的角色，剩下的全归你管，这才有可控性。

2.1 默认 action 方式在这里为什么走不通

用 action 的写法，组件在内部创建请求，字段名固定、请求头固定、返回体拿到的也是原始响应对象。项目里通常有一层统一封装：请求头塞 token、响应体按 code 判断成功失败、失败时统一弹提示。这套东西在 action 模式下全用不上，你得在 onSuccess 里再解析一遍响应体，等于把拦截器的活重写一份。

customRequest 接管的是一次完整的「发送」动作，参数对象里带着 file、onProgress、onSuccess、onError、action、data、filename、headers、withCredentials 这些字段。你只需要关心三件事：文件怎么塞进 FormData、请求发给谁、结果怎么回传给组件。回传这一步是很多人漏掉的，后面第 5 章会专门说。

还有一层隐性收益：接管之后可以对同一个文件做二次处理，比如上传前算 MD5 做幂等、压缩图片、拆分大文件分片。默认 action 模式下这些都得绕路。

2.2 accept 只是浏览器的过滤器，beforeUpload 才是硬校验

看这段模板代码，accept 里写了两个 MIME：

<a-upload accept="application/vnd.openxmlformats-officedocument.spreadsheetml.sheet, application/vnd.ms-excel" :customRequest="customRequest" :beforeUpload="beforeUpload" :disabled="uploadDisabled" :file-list="fileList" @change="customChange"> <a-button type="primary" :icon="uploadIcon" :disabled="uploadDisabled">导入</a-button> </a-upload>

accept 对应的是原生<input type="file">的 accept 属性，作用只有一个：在系统文件选择框里做一次过滤。用户在弹窗里把筛选切成「所有文件」，或者直接拖拽一个改了扩展名的文件进来，accept 完全拦不住。所以真正的校验必须写在 beforeUpload 里：

export default { data() { return { uploadIcon: 'to-top', uploadDisabled: false, fileList: [], // 受控文件列表，用于手动清空 allowExt: ['xlsx', 'xls'], maxSize: 5 * 1024 * 1024 }; }, methods: { /** * 上传前的最后一道前端校验 * @param {File} file 原生 File 对象 * @returns {boolean} false 表示中止，不会进入 customRequest */ beforeUpload(file) { const ext = (file.name.split('.').pop() || '').toLowerCase(); if (!this.allowExt.includes(ext)) { this.$message.error('只支持 .xlsx 或 .xls 文件'); return false; } if (file.size > this.maxSize) { this.$message.error('单个文件不要超过 5MB'); return false; } return true; } } };

allowExt决定放行哪些扩展名，判断用的是文件名后缀而不是 MIME，因为 MIME 在不同系统上不稳定：同样是 .xls，有的浏览器给application/vnd.ms-excel，有的给application/octet-stream，只靠 MIME 判断会误杀。maxSize卡的是体积，它和后端max-file-size是两道独立的闸，前端这道只为了少发一次无效请求，真正起作用的是后端那道。

fileList这个受控列表值得单独提一句。不绑定它的时候，a-upload 自己在内部维护列表，用户第二次选同一个文件，change 事件可能压根不触发，表现就是「点了没反应」。绑定成受控之后，在 done 或 error 分支里把它清空，下一次选同名文件就能正常走流程。

2.3 FormData 字段名和请求头，是后端接不到文件的两大原因

文件上传只有一条路：把 File 塞进 FormData，然后让浏览器自己生成 boundary。

customRequest(option) { const { file, onProgress, onSuccess, onError } = option; const formData = new FormData(); // 这个 key 必须和后端 @RequestParam("file") 里的名字一模一样 formData.append('file', file); // 手动把组件状态推到 uploading，否则按钮不会有任何变化 onProgress({ percent: 30 }); batchImportGetRecord(formData, { // 关键：不要手写 Content-Type，交给浏览器补 boundary headers: { 'Content-Type': undefined }, timeout: 120000, onUploadProgress: e => { if (e.total) { // 把 axios 的真实进度同步给组件 onProgress({ percent: Math.round((e.loaded / e.total) * 100) }); } } }).then(res => { if (res && res.code === 0) { onSuccess(res, file); } else { onError(new Error(res.msg || '导入失败')); } }).catch(err => { onError(err); }).finally(() => { this.switchIconAndStatus(false); }); }

三个参数点逐个说明。formData.append('file', file)的第一个参数是字段名，后端@RequestParam("file")括号里写的必须是同一个字符串，差一个字母就是 400 或者「Required request part 'file' is not present」。headers: { 'Content-Type': undefined }的作用是覆盖掉 axios 实例上可能统一设置的application/json——如果拦截器里把 Content-Type 写死了，FormData 会被序列化成一串 JSON 字符串发出去，后端收到的永远是空文件。最省事的做法是让浏览器自己加multipart/form-data; boundary=----xxx，手动写死反而不带 boundary。timeout单独设长一点，默认的 10 秒在几千行数据面前根本不够用，接口超时了前端报错、后端还在写库，用户重试又是一份重复数据。

3. 上传按钮的状态机：用 file.status 和 loading 图标阻止重复提交

按钮的视觉反馈不是装饰，它承担的是「并发控制」的职责。用户在等待期间看不到任何变化，第一反应就是再点一次，这个动作在几百毫秒内可能重复三到五次。把按钮从「可点」变成「转圈且禁用」，比后端加分布式锁便宜得多，也直观得多。

3.1 file.status 的四个取值和真实触发顺序

a-upload 抛给 change 事件的data.file.status有四种取值：

注意这里的主语：状态是「你调用了回调之后」才出现的，不是组件自己感知到的。组件不知道你的 axios 请求什么时候返回，它只认你手动调的那三个回调。这就是第 5 章第一条问题的根源——只调 onProgress 不调 onSuccess，status 会永远停在 uploading，按钮一直转圈，用户等到不耐烦刷新页面，后端可能已经写入数据了。

完整的 change 处理长这样：

customChange(data) { const status = data.file.status; if (status === 'uploading') { this.switchIconAndStatus(true); } else if (status === 'done' || status === 'error') { this.switchIconAndStatus(false); // 清空受控列表，保证同名文件能再次触发 change this.fileList = []; } else if (status === 'removed') { this.switchIconAndStatus(false); } }

3.2 switchIconAndStatus 的封装，以及 finally 放在哪

原文把图标和禁用状态抽成一个方法，这个思路是对的，两个状态必须同进同出，否则会出现「转圈但按钮还能点」或者「按钮灰了但图标还是静态」的割裂。

/** * 统一切换导入按钮的图标与禁用状态 * @param {boolean} flag true=正在导入，false=空闲 */ switchIconAndStatus(flag) { this.uploadIcon = flag ? 'loading' : 'to-top'; this.uploadDisabled = flag; }

调用点只有三处：change 的 uploading 分支、change 的 done/error 分支、customRequest 的 finally。第三处是兜底——如果请求链路上某一段抛了未捕获的异常，没有 finally 的话按钮会永久卡在转圈状态，用户只能刷新页面。

关于图标，loading在 Ant Design Vue 的图标体系里是自带旋转动画的，to-top是一个静态箭头，视觉上足够区分「空闲」和「处理中」。不要用两个静态图标换来换去，用户分辨不出来。

3.3 超时、进度和取消，大文件场景必须补的三件事

小文件测试没问题，一上千行就开始出问题，往往是这三项没做。

第一是超时。axios 默认超时通常在 10 秒量级，五千行 Excel 走完解析加批量插入，十几秒很正常。要么把 timeout 提到 120 秒，要么改成异步任务模式：接口立刻返回一个任务 ID，前端轮询进度，这样按钮状态和真实进度能对上。

第二是进度。customRequest 的onProgress是给组件用的，真实进度得从 axios 的onUploadProgress里取。注意区分上传进度和后台处理进度——文件传完只是第一步，后端还在解析和写库，此时进度条到 100% 但按钮不能恢复，所以进度只用来安抚用户，状态切换依然以 finally 为准。

第三是取消。用户选错文件想中止，可以用 AbortController 挂到 axios 请求上，在 removed 分支里调用 abort。不强求，但导入这种重操作留个退出通道，体验差别很明显。

4. 后端解析链路：MultipartFile 到 XSSFWorkbook 的坐标模型

前端把所有事情做完，交给后端的只是一个字节流。后端要做的是：接住流、识别格式、按行列坐标把值取出来、映射成实体、批量写库、出错能回滚。这五步里任何一步想当然，都会在线上演变成脏数据或者内存溢出。

4.1 Controller 层和 multipart 配置，第一道限制是文件大小

SpringBoot 的 multipart 默认限制是单文件 1MB、单请求 10MB。这个默认值在测试阶段很容易被忽略，因为几百行的小表根本到不了 1MB，一旦换成真实业务数据，直接抛MaxUploadSizeExceededException，前端只看到 500。

spring: servlet: multipart: max-file-size: 10MB # 单文件上限，默认 1MB max-request-size: 20MB # 整个请求上限，默认 10MB file-size-threshold: 2MB # 超过这个体积写临时文件，不再全放内存

file-size-threshold这个参数容易被跳过，它决定超出的部分是否落盘成临时文件。导入场景把它设小一点（比如 512KB），能显著降低高并发时的堆内存压力。

控制器只做三件事：判空、判后缀、转交服务层。

@RestController @RequestMapping("/api/student") public class StudentController { @Resource private StudentService studentService; /** * Excel 导入入口 * @param file 前端 FormData 中 key 为 file 的文件，名字必须一致 */ @PostMapping("/import") public Result<Integer> importExcel(@RequestParam("file") MultipartFile file) { if (file == null || file.isEmpty()) { return Result.fail("上传文件为空"); } String name = file.getOriginalFilename(); if (name == null) { return Result.fail("文件名解析失败"); } String lower = name.toLowerCase(); if (!lower.endsWith(".xlsx") && !lower.endsWith(".xls")) { return Result.fail("仅支持 .xlsx 与 .xls 格式"); } return Result.ok(studentService.importExcelData(file)); } }

@RequestParam("file")的字符串是硬约束，和前端formData.append('file', ...)必须完全一致。后缀判断是第二道防线，防止有人改了扩展名硬传一个 CSV 或 ZIP 上来，POI 解析时抛出的异常信息极难定位。

4.2 行与列的遍历，先搞清楚「下标」和「数量」的区别

POI 的坐标模型有两个容易混淆的 API：

原文用的是getPhysicalNumberOfRows()和getPhysicalNumberOfCells()，这两个方法在数据规整的表里没毛病，一旦用户在中间删了几行留白，或者某一列忘了填，后面的列就整体前移一位，姓名被塞进年龄字段，映射全乱。

4.3 单元格类型判定，getStringCellValue 直接调用会抛什么

这是后端解析里最常见的一处硬伤。cell.getStringCellValue()在单元格实际是数字类型时会抛：

java.lang.IllegalStateException: Cannot get a STRING value from a NUMERIC cell

用户的 Excel 里「年龄」一列是数字，程序按字符串去取，整批导入直接中断。同类问题还有getNumericCellValue()遇到文本单元格、公式单元格没有缓存值、日期单元格在不同区域设置下变成一串 5 位数字。

通用解法是 DataFormatter，它按单元格的「显示值」取字符串，数字、日期、百分比都能拿到你肉眼看到的样子：

@Override @Transactional(rollbackFor = Exception.class) public Integer importExcelData(MultipartFile file) { List<Student> list = new ArrayList<>(); try (InputStream in = file.getInputStream(); Workbook workbook = WorkbookFactory.create(in)) { // 自动识别 xls / xlsx Sheet sheet = workbook.getSheetAt(0); DataFormatter formatter = new DataFormatter(); // 按显示值取字符串 int lastRow = sheet.getLastRowNum(); for (int i = 1; i <= lastRow; i++) { // 从 1 开始，跳过表头 Row row = sheet.getRow(i); if (row == null) { continue; // 整行为空 } Student student = new Student(); short lastCell = row.getLastCellNum(); // 最后一列下标 + 1 for (int j = 0; j < lastCell; j++) { Cell cell = row.getCell(j, Row.MissingCellPolicy.RETURN_BLANK_AS_NULL); if (cell == null) { continue; // 跳过空单元格 } String text = formatter.formatCellValue(cell).trim(); switch (j) { case 0: student.setName(text); break; case 1: student.setAge(text.isEmpty() ? null : Integer.valueOf(text)); break; case 2: student.setHobby(text); break; case 3: student.setAddress(text); break; case 4: student.setBirthday(readDate(cell, text)); break; default: break; } } if (student.getName() == null || student.getName().isEmpty()) { continue; // 姓名为空视为无效行 } list.add(student); } } catch (Exception e) { // 包成运行时异常抛出，交给 rollbackFor 处理 throw new IllegalStateException("Excel 解析失败：" + e.getMessage(), e); } if (!list.isEmpty()) { studentService.saveBatch(list, 500); // 每 500 条一批 } return list.size(); } /** * 日期列读取：优先按真实日期单元格取，退化到字符串解析 */ private Date readDate(Cell cell, String text) throws ParseException { if (cell.getCellType() == CellType.NUMERIC && DateUtil.isCellDateFormatted(cell)) { return cell.getDateCellValue(); } String[] patterns = {"yyyy年M月d日HH:mm:ss", "yyyy年M月d日", "yyyy-MM-dd HH:mm:ss", "yyyy-MM-dd"}; for (String p : patterns) { try { return new SimpleDateFormat(p).parse(text); } catch (ParseException ignore) { // 换下一个格式继续试 } } throw new ParseException("无法识别的日期格式：" + text, 0); }

几个参数说清楚。WorkbookFactory.create(in)会根据文件头自动选择 HSSF 或 XSSF，这是兼容 .xls 的唯一正解，直接 new XSSFWorkbook 只会读 .xlsx。Row.MissingCellPolicy.RETURN_BLANK_AS_NULL保证空单元格返回 null 而不是抛异常。saveBatch(list, 500)的第二个参数是每批条数，默认 1000，取 500 是在 SQL 长度和往返次数之间折中，字段多、有长文本的时候调到 200 更稳。

4.4 事务和 saveBatch，为什么回滚要在 catch 里手动做

@Transactional默认只在遇到 RuntimeException 和 Error 时回滚，检查型异常不在其列。原文的 catch 块吞掉异常、返回 false，再调TransactionAspectSupport.currentTransactionStatus().setRollbackOnly()——这套写法能工作，但有三个前提：方法必须走代理调用（同类内部自调用不生效）、必须已经开启事务（否则抛 NoTransactionException）、必须用对 ThreadLocal 上的事务状态。

更干净的写法是@Transactional(rollbackFor = Exception.class)配合 catch 里重新抛出一个运行时异常，让事务切面自己处理。如果业务上确实需要「返回 false 而不是抛异常给前端」，那就保留 setRollbackOnly，但要清楚它是最后的保险措施，不能替代异常设计。

批量插入本身也有取舍：逐条 insert 意味着 N 次网络往返，几千行就是几千次；saveBatch 把多条拼成一条insert into ... values (...),(...)，往返次数降到个位数。代价是单条 SQL 变长，超过max_allowed_packet会直接失败，所以每批条数不能盲目调大。

5. 避坑与排查：五条从日志里翻出来的真实记录

这一章的五条，每一条都在不同项目的上线后暴露过。共同点是：测试环境用一张规规矩矩的表格能跑通，换成真实业务数据就出问题。它们的现象各不相同，排查路径却高度相似——先看前端 status，再看后端日志的第一个异常行，最后看数据库里的实际条数。

5.1 上传提示成功，按钮却一直转圈

现象：接口返回 200，Toast 也弹了「导入成功」，但按钮的 loading 图标不消失，用户只能刷新页面。

原因：customRequest 里只调了onProgress()，没调onSuccess()。组件的 status 停留在 uploading，change 事件的 done 分支永远不触发，switchIconAndStatus(false)只写在 finally 里能恢复图标，但如果 finally 在组件状态更新之前执行，加上没有受控 fileList，界面就会卡住。

解决：把onSuccess(res, file)和onError(err)补到对应分支，先把组件状态推到终态，finally 只做兜底复位。

5.2 .xls 文件报 OfficeXmlFileException

现象：前端 accept 放行了 .xls，用户选中后后端抛org.apache.poi.openxml4j.exceptions.OfficetmlFileException: The supplied data appears to be in the OLE2 Format。

原因：服务层直接new XSSFWorkbook(file.getInputStream())，XSSF 只认 OOXML 格式的 .xlsx，遇到 BIFF 格式的 .xls 就报这个错。前端放行两种格式，后端只支持一种，接口契约对不上。

解决：换成WorkbookFactory.create(in)，按文件头自动派发到 HSSF 或 XSSF。如果确定业务上只允许 .xlsx，那就把前端 accept 和后端后缀校验一起收紧，别让用户白传一次。

5.3 数字列全部报 Cannot get a STRING value

现象：前几行正常，到了某个用户的数据就抛出IllegalStateException，整批回滚。

原因：cell.getStringCellValue()只对文本单元格有效。用户的姓名列是文本，年龄列是数字，同一套代码按字符串取，遇到第一个数字单元格就炸。表现上看起来是「某些文件能导、某些不能」，其实是列的数据类型不一致。

解决：统一用DataFormatter.formatCellValue(cell)取显示值，需要数值时再对结果做Integer.valueOf。要保留日期语义的列，先用DateUtil.isCellDateFormatted(cell)判断是不是日期单元格，再用getDateCellValue()取原始值。

5.4 导入到一半失败，前 300 条已经写入数据库

现象：前端提示「导入失败」，但数据库里多出了几百条记录，用户重试后数据翻倍。

原因：catch 块里e.printStackTrace()之后直接return false，异常被吞掉，事务切面认为方法正常结束，于是正常提交。setRollbackOnly 那一行如果放在 return 之后，或者方法上有@Transactional(readOnly = true)之类的配置，都不会生效。

解决：@Transactional(rollbackFor = Exception.class)加到方法上，catch 里重新抛运行时异常，或者把 setRollbackOnly 提到 catch 的第一行。同时在业务上做幂等——导入前按「批次号 + 唯一键」查重，别指望事务能替你去重。

5.5 十万行 Excel 直接 OOM

现象：堆内存监控看着涨，几秒后java.lang.OutOfMemoryError: Java heap space，服务实例被拖垮。

原因：XSSFWorkbook 采用全量加载模型，整个文件解析成一棵 DOM 树放进内存，十万行乘二十列的对象树轻松吃掉几个 G。堆再大也只是推迟爆炸时间，不是解决问题。

解决：超过两三万行的场景换成流式解析，EasyExcel 或 POI 的 SAX 事件模型都可以，内存占用跟行数基本无关。如果短期不想换库，至少给导入接口加一个行数上限，超过阈值直接拒绝，把「导入失败」变成「请分批导入」——这比让整个服务挂掉体面得多。

5.6 一套可以照着走的自检清单

按这个顺序排查，八成问题能在五分钟内定位：前端先看 Network 里的请求体是不是 multipart 且带 boundary，再看响应体 code 是否为成功；后端先把日志过滤到第一个 Caused by，POI 的异常信息写得很直白，格式不对、类型不对、文件损坏都会明说；最后对一遍数据库条数与 Excel 有效行数，对不上就说明事务或者校验环节有漏。养成这个顺序，比对着代码一行行看快得多。

6. 进阶：把「能跑通」推到「敢给别人用」

功能跑通只是起点。真实场景里，运营会改列顺序、会插隐藏列、会在中间加一列备注，硬编码的 switch case 遇上这些就得改代码。有两种做法收益最高：把列下标映射改成表头名映射，以及把导入结果做成可下载的错误清单。

6.1 用表头名映射列下标，抵御列顺序变化

思路是把第一行读成一个「列名 → 下标」的字典，后续按名字取值，而不是按固定位置。

// 解析表头，建成 列名 -> 下标 的索引 Map<String, Integer> header = new HashMap<>(); Row headRow = sheet.getRow(0); for (int c = 0; c < headRow.getLastCellNum(); c++) { Cell cell = headRow.getCell(c, Row.MissingCellPolicy.RETURN_BLANK_AS_NULL); if (cell != null) { header.put(formatter.formatCellValue(cell).trim(), c); } } // 之后取值就变成按名字拿，列顺序随便换 Integer nameIdx = header.get("姓名"); Integer ageIdx = header.get("年龄"); if (nameIdx == null || ageIdx == null) { throw new IllegalStateException("表头缺少必填列：姓名 / 年龄"); } student.setName(formatter.formatCellValue(row.getCell(nameIdx)).trim());

代价是需要跟运营约定表头文案，换来的是「加一列备注不用改代码」。表头校验放在解析最前面，缺列直接整批拒绝，别让半张表的数据流进数据库。

6.2 导入结果回执，把「成功/失败」变成一张清单

只返回 true/false 的接口在上线第一周就会被投诉：用户不知道哪几行没过、为什么没过。把返回值改成一个结构体，记录成功条数、失败条数和每一条失败原因：

错误清单本身可以直接序列化成一张新的 Excel 让用户下载，行号对得上原表，用户改完再传一次。这一步做完，导入功能才算真正交出去了——用户能自己解决问题，你就不用每天在群里回复「第几行错了」。

我踩过最贵的一次坑，是给一个内部系统做学员信息导入，图省事只返回了布尔值。上线当天有三十多个人反馈「导入失败」，我一个人对着日志逐条比对行号，弄了一个下午。从那以后，凡是带批量导入的接口，我强制自己先写返回值结构体，把行号和原因带出来，再写解析逻辑。希望你不用重复这个下午。

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