企业官网建设流程全解析

1. 项目概述：为什么一个“文件处理系列”值得单独成套讲透？

在某公司做后端开发的第三年，我接手了一个看似简单的内部运营系统——需要让业务人员每天从Excel里拉数据、填表单、上传附件、批量下载报表。当时想得很简单：Spring Boot不是有现成的POI和WebMvcConfigurer吗？抄几段网上的代码，两天搞定。结果上线第一周就崩了三次：一次是用户上传了200MB的Excel直接把JVM堆撑爆；一次是导出3万行数据时浏览器卡死，用户以为系统挂了；还有一次是并发下载压缩包时，服务器磁盘IO被打满，连SSH都连不上。后来翻日志才发现，问题根本不在“功能有没有”，而在于每一步操作背后隐藏的资源边界、线程安全、内存模型和HTTP协议细节。这个“文件处理系列”不是教你怎么写@RestController，而是带你重新理解：当一个文件从浏览器出发，穿过Nginx、Spring MVC、业务层、IO流、操作系统缓存，最后落盘或返回给用户时，中间每一个环节的“默认行为”都在悄悄埋雷。

核心关键词——导入Excel、导出Excel、上传文件、下载文件、批量压缩文件下载——这五个动作，表面看是五个独立接口，实则共享同一套底层逻辑：流式处理意识、内存与磁盘的权衡、HTTP响应生命周期管理、以及对Servlet容器工作模式的深度适配。比如“上传文件”和“下载文件”看似相反，但都必须直面Content-Length头的动态计算难题；“导入Excel”和“导出Excel”都绕不开Apache POI的SXSSF与XSSF内存模型切换；而“批量压缩文件下载”更是把前四者的能力全部串联起来，同时考验你对ZipOutputStream缓冲区大小、ResponseEntity的StreamingResponseBody用法、以及Nginx反向代理下X-Accel-Redirect头的兼容性认知。这不是API调用手册，而是一份基于真实压测数据（我们曾用JMeter模拟500并发上传10MB文件）总结出的避坑地图。适合所有已经能写出“Hello World”级Controller，但一碰文件就掉进OOM、超时、乱码、中文名丢失、大文件卡死等坑里的中初级开发者。如果你的项目里还写着MultipartFile.transferTo(new File(...))或者response.getOutputStream().write(bytes)，那这篇就是为你写的。

2. 核心设计思路拆解：为什么拒绝“一把梭”式编码？

2.1 导入Excel：不加载全量数据到内存，是底线，不是优化项

很多人以为POI的XSSFWorkbook只是“功能强”，却忽略了它本质是个内存Excel解析器。读取一个10MB的xlsx文件，实际占用JVM堆内存可能高达300MB——因为POI会把整个XML结构树、样式、公式缓存全部加载进内存。我们曾在线上环境见过一个导入接口，单次请求吃掉2GB堆空间，触发Full GC后STW长达8秒。解决方案不是升级服务器，而是切换到SXSSF（Streaming Usermodel）模式。它的核心思想是：只保留在内存中的“滑动窗口”，比如设置windowSize=100，就只缓存当前正在处理的100行，老数据自动刷到临时磁盘文件。但注意，SXSSF不是万能的：它不支持读取公式值（只返回缓存的计算结果）、不支持修改单元格样式、且临时文件路径必须可写。我们最终采用的策略是——双模自动降级：先用OPCPackage.open()快速读取文件元信息（如sheet数量、总行数），若总行数＜5000，走XSSF全量加载（快）；否则强制切SXSSF，并在Controller层加@RequestPart("file") MultipartFile file参数校验文件大小（前端传Content-Length不可信，必须服务端二次校验）。

提示：不要依赖file.getSize()做判断！MultipartFile的size在文件流未真正读取前可能为-1。正确做法是先调用file.getInputStream()，再用IOUtils.toByteArray()读取前1KB判断文件魔数（如xlsx是50 4B 03 04），同时记录已读字节数，避免重复读取。

2.2 导出Excel：流式生成+分页查询，才是应对大数据量的正解

导出3万行数据？别想着List<Record>查出来再塞进Workbook。数据库查3万行本身就要2秒，POI再渲染又要3秒，整个接口耗时5秒以上，用户早关页面了。真正的解法是游标分页+流式写入。我们用MyBatis的RowBounds或Cursor（推荐后者，内存友好）分批查库，每次取1000条，查完立刻写入SXSSFWorkbook的Sheet，然后调用workbook.write(outputStream)——注意，这里outputStream必须是HttpServletResponse.getOutputStream()，且要在写入前设置response.setContentType("application/vnd.openxmlformats-officedocument.spreadsheetml.sheet")和response.setHeader("Content-Disposition", "attachment; filename=\"data.xlsx\"")。关键点在于：不能调用workbook.close()！因为close会关闭底层流，导致后续无法写入HTTP响应体。我们封装了一个StreamingExcelExporter工具类，核心逻辑是：

public void export(HttpServletResponse response, Supplier<Cursor<Record>> cursorSupplier) throws IOException { SXSSFWorkbook workbook = new SXSSFWorkbook(100); Sheet sheet = workbook.createSheet("数据"); // 写入表头 Row headerRow = sheet.createRow(0); String[] headers = {"ID", "姓名", "邮箱"}; for (int i = 0; i < headers.length; i++) { headerRow.createCell(i).setCellValue(headers[i]); } int rowNum = 1; try (Cursor<Record> cursor = cursorSupplier.get()) { for (Record record : cursor) { Row row = sheet.createRow(rowNum++); row.createCell(0).setCellValue(record.getId()); row.createCell(1).setCellValue(record.getName()); row.createCell(2).setCellValue(record.getEmail()); // 每写入1000行，手动刷新一次内存，释放老数据 if (rowNum % 1000 == 0) { sheet.flushRows(1000); } } } // 关键：用response.getOutputStream()，且不close response.setContentType("application/vnd.openxmlformats-officedocument.spreadsheetml.sheet"); response.setHeader("Content-Disposition", "attachment; filename=\"export_" + System.currentTimeMillis() + ".xlsx\""); workbook.write(response.getOutputStream()); // 这里不调用workbook.close()，由容器在响应结束时自动清理 }

2.3 上传文件：别再用transferTo，用流式管道直通存储

MultipartFile.transferTo(File)的问题在于：它会先把文件完整写入临时目录（如/tmp/tomcat.12345.upload），再移动到目标位置。如果用户上传1GB文件，临时目录瞬间占满，且移动操作在Linux下是rename()系统调用，虽快但不可控。更危险的是，如果目标路径是相对路径（如"uploads/" + file.getOriginalFilename()），可能被构造恶意路径../../../etc/passwd。我们的方案是跳过临时文件，用InputStream直连OSS/S3或本地存储。以上传到本地为例：

public String upload(MultipartFile file, String basePath) throws IOException { // 1. 安全校验文件名：只保留字母、数字、下划线、短横线、点号 String originalName = file.getOriginalFilename(); String safeName = originalName.replaceAll("[^a-zA-Z0-9_\\-.]", "_"); String ext = FilenameUtils.getExtension(safeName); String finalName = UUID.randomUUID().toString() + "." + ext; // 2. 构建绝对路径，防止路径遍历 Path targetPath = Paths.get(basePath, finalName); if (!targetPath.getParent().toFile().exists()) { Files.createDirectories(targetPath.getParent()); } // 3. 流式写入，不经过临时文件 try (InputStream is = file.getInputStream(); OutputStream os = Files.newOutputStream(targetPath)) { IOUtils.copy(is, os); // Apache Commons IO } return "/files/" + finalName; // 返回可访问的URL路径 }

注意：basePath必须是绝对路径，且需在Spring Boot配置中通过spring.servlet.context-path或Nginx配置确保/files/路径能被静态资源处理器映射到该目录。

2.4 下载文件：Range请求支持和中文名兼容是用户体验分水岭

用户下载大文件时，网络中断怎么办？浏览器支持断点续传，但前提是服务端实现HTTPRange请求。Spring Boot默认不支持，需手动处理。另外，中文文件名在Chrome/Firefox/Safari表现不一：Chrome用filename*=UTF-8''xxx.xlsx，Firefox用filename="xxx.xlsx"，Safari两者都要。我们封装的FileDownloadService同时解决这两个问题：

public void download(HttpServletResponse response, Path filePath, String displayName) throws IOException { if (!Files.exists(filePath)) { response.sendError(HttpServletResponse.SC_NOT_FOUND); return; } long fileSize = Files.size(filePath); String contentType = Files.probeContentType(filePath); if (contentType == null) { contentType = "application/octet-stream"; } // 设置基础响应头 response.setContentType(contentType); response.setContentLengthLong(fileSize); // 中文文件名兼容处理 String encodedName = URLEncoder.encode(displayName, StandardCharsets.UTF_8); response.setHeader("Content-Disposition", "attachment; filename=\"" + displayName + "\"; filename*=UTF-8''" + encodedName); // Range请求支持 String rangeHeader = request.getHeader("Range"); if (rangeHeader != null && rangeHeader.startsWith("bytes=")) { // 解析Range: bytes=0-1023 String[] ranges = rangeHeader.substring(6).split("-"); long start = Long.parseLong(ranges[0]); long end = ranges.length > 1 && !ranges[1].isEmpty() ? Long.parseLong(ranges[1]) : fileSize - 1; if (end >= fileSize) end = fileSize - 1; long length = end - start + 1; response.setStatus(HttpServletResponse.SC_PARTIAL_CONTENT); response.setHeader("Content-Range", "bytes " + start + "-" + end + "/" + fileSize); response.setContentLengthLong(length); try (RandomAccessFile raf = new RandomAccessFile(filePath.toFile(), "r"); OutputStream os = response.getOutputStream()) { raf.seek(start); byte[] buffer = new byte[8192]; int bytesRead; while ((bytesRead = raf.read(buffer)) != -1 && length > 0) { int toWrite = (int) Math.min(bytesRead, length); os.write(buffer, 0, toWrite); length -= toWrite; } } } else { // 普通下载 try (InputStream is = Files.newInputStream(filePath); OutputStream os = response.getOutputStream()) { IOUtils.copy(is, os); } } }

2.5 批量压缩下载：ZipOutputStream的缓冲区大小决定吞吐量

批量下载100个文件，是生成100个独立链接，还是打包成一个zip？后者是标准答案，但ZipOutputStream用不好，性能会暴跌。常见错误是：为每个文件新建ZipEntry后，直接zos.putNextEntry(entry)，然后IOUtils.copy(fileInputStream, zos)——这会导致每次写入都触发一次系统调用。正确做法是设置足够大的缓冲区（如8KB），并复用byte数组。我们实测发现，缓冲区从1KB提升到8KB，100个1MB文件的压缩耗时从4.2秒降到1.7秒。此外，ZipEntry的setTime()必须显式设置，否则解压后文件时间戳是1970年；setMethod(ZipEntry.STORED)可跳过CRC校验（仅当确定文件内容不变时使用，节省CPU）。核心代码：

public void zipDownload(HttpServletResponse response, List<Path> files, String zipName) throws IOException { response.setContentType("application/zip"); response.setHeader("Content-Disposition", "attachment; filename=\"" + zipName + "\""); try (ZipOutputStream zos = new ZipOutputStream(response.getOutputStream(), StandardCharsets.UTF_8)) { // 设置缓冲区，提升性能 zos.setMethod(ZipOutputStream.DEFLATED); zos.setLevel(Deflater.BEST_SPEED); // 压缩速度优先 byte[] buffer = new byte[8192]; // 复用缓冲区 for (Path file : files) { if (!Files.exists(file)) continue; String entryName = file.getFileName().toString(); ZipEntry entry = new ZipEntry(entryName); entry.setTime(Files.getLastModifiedTime(file).toMillis()); zos.putNextEntry(entry); try (InputStream is = Files.newInputStream(file)) { int len; while ((len = is.read(buffer)) != -1) { zos.write(buffer, 0, len); } } zos.closeEntry(); } } }

3. 实操细节与关键参数配置：每一行代码背后的决策依据

3.1 Spring Boot文件上传配置：不只是改max-file-size

application.yml里只配spring.servlet.multipart.max-file-size=10MB远远不够。Tomcat作为默认容器，还有自己的限制：

# application.yml spring: servlet: multipart: max-file-size: 10MB max-request-size: 10MB # 关键：启用文件流式处理，避免内存溢出 enabled: true # Tomcat专用配置（需在Spring Boot启动类中注入） server: tomcat: # 最大连接数，影响并发上传能力 max-connections: 500 # 连接超时，大文件上传需延长 connection-timeout: 60000 # 禁用upload temp dir，强制流式处理 basedir: ""

但更重要的是Tomcat的maxSwallowSize参数。当客户端发送超大请求体（如100MB文件），而服务端在处理前就因超时或异常中断，Tomcat会尝试“吞掉”剩余字节以释放连接。默认maxSwallowSize=2MB，意味着它只会吞2MB，剩下的98MB还在socket缓冲区，导致连接假死。线上必须设为-1（不限制）或足够大值：

@Bean public WebServerFactoryCustomizer<TomcatServletWebServerFactory> customizer() { return factory -> factory.addAdditionalTomcatConnectors( new Connector("org.apache.coyote.http11.Http11NioProtocol") {{ setPort(8081); setMaxSwallowSize(-1); // 关键！禁用吞字节限制 }} ); }

3.2 POI内存模型参数：SXSSF的windowSize不是越大越好

SXSSFWorkbook的windowSize参数常被误解为“缓存行数越多越快”。实测数据打脸：在10万行Excel导入场景中，windowSize=100耗时12.3秒，windowSize=1000反而升到15.8秒。原因在于：更大的窗口意味着更多对象驻留内存，GC压力增大；且flushRows()操作本身有开销。我们最终选择windowSize=100，并配合异步解析+批量入库策略：解析完100行，立即用MyBatis Batch Insert提交，而不是攒够1000行再插。这样内存峰值稳定在80MB以内，插入耗时也更平滑。参数配置代码：

// 创建SXSSFWorkbook时指定 SXSSFWorkbook workbook = new SXSSFWorkbook(100); // windowSize=100 // 关键：关闭自动刷新，手动控制flush时机 workbook.setCompressTempFiles(true); // 压缩临时文件，节省磁盘 workbook.setUseSharedStringsTable(false); // 禁用共享字符串表，减少内存占用（若无重复字符串）

3.3 Nginx反向代理下的文件下载优化：X-Accel-Redirect头的正确用法

当Spring Boot部署在Nginx后，大文件下载不应由Java应用直接输出，而应交由Nginx处理。原理是：Java只校验权限，然后返回X-Accel-Redirect头，Nginx根据该头内部重定向到静态文件路径，完全绕过Java IO。配置步骤：

1. Nginx配置：

location /protected-files/ { internal; # 仅内部重定向可访问 alias /data/uploads/; # 实际文件存储路径 }

2. Java Controller中：

@GetMapping("/download/{id}") public ResponseEntity<Void> download(@PathVariable String id, HttpServletRequest request) { // 1. 校验用户权限、文件是否存在等业务逻辑 Path filePath = resolveFilePath(id); if (!Files.exists(filePath)) { return ResponseEntity.notFound().build(); } // 2. 返回X-Accel-Redirect头，Nginx会接管 HttpHeaders headers = new HttpHeaders(); headers.set("X-Accel-Redirect", "/protected-files/" + filePath.getFileName()); headers.set("Content-Disposition", "attachment; filename=\"" + filePath.getFileName() + "\""); return ResponseEntity.ok().headers(headers).build(); }

注意：X-Accel-Redirect的路径必须是Nginx配置的internallocation，且alias末尾的/必须与头中路径匹配，否则404。

3.4 并发上传的线程安全陷阱：MultipartFile不是线程安全的

一个常见误区：把MultipartFile存入ThreadLocal或静态Map，在异步线程中处理。这是危险的！MultipartFile的getInputStream()只能调用一次，且其底层CachedMultipartFile的缓存数据在transferTo()后会被清空。我们曾在线上遇到异步任务中is.read()返回-1的诡异问题，根源就是主线程已消费了流。正确做法是：在Controller方法内，第一时间将文件内容复制到ByteArrayInputStream或临时文件。例如：

@PostMapping("/upload") public ResponseEntity<?> handleUpload(@RequestPart("file") MultipartFile file) { // 立即复制到内存，避免流被多次消费 byte[] fileBytes; try { fileBytes = file.getBytes(); // 小文件（<10MB）用此法 } catch (IOException e) { // 大文件走流式复制 fileBytes = IOUtils.toByteArray(file.getInputStream()); } // 启动异步任务，传入fileBytes而非MultipartFile asyncTaskExecutor.submit(() -> processFileAsync(fileBytes, file.getOriginalFilename())); return ResponseEntity.ok().build(); }

3.5 中文文件名乱码的终极解决方案：三重编码保障

中文文件名在下载时乱码，本质是HTTP头编码不一致。我们采用三重保险：

1. URL编码：URLEncoder.encode(name, "UTF-8")
2. RFC 5987标准：filename*=UTF-8''encoded_name
3. Fallback兼容：同时提供filename="name"（部分旧浏览器需要）

但还不够！Spring Boot的ContentDisposition类在2.6+版本才原生支持RFC 5987，低版本需手动拼接。我们封装的工具方法：

public static String buildContentDisposition(String filename) { try { String encoded = URLEncoder.encode(filename, StandardCharsets.UTF_8); // RFC 5987格式：filename*=UTF-8''xxx String rfc5987 = "filename*=UTF-8''" + encoded; // 兼容旧版：filename="xxx" String fallback = "filename=\"" + filename + "\""; return fallback + "; " + rfc5987; } catch (UnsupportedEncodingException e) { return "filename=\"" + filename + "\""; } }

调用时：

response.setHeader("Content-Disposition", buildContentDisposition("订单汇总_202405.xlsx"));

4. 实战问题排查与避坑指南：那些文档里不会写的血泪教训

4.1 问题速查表：高频故障现象与根因定位

4.2 那些踩过的坑：只有亲手试过才知道的细节

坑1：MultipartFile.getOriginalFilename()的null安全陷阱
前端如果不传filename字段（如用fetchAPI手动构造FormData），getOriginalFilename()会返回null，直接substring()抛NPE。正确姿势：

String fileName = Optional.ofNullable(file.getOriginalFilename()) .filter(f -> !f.trim().isEmpty()) .orElse("unnamed_file");

坑2：response.getOutputStream()和response.getWriter()不能共存
一旦调用了getWriter()，再调用getOutputStream()会抛IllegalStateException。所以导出Excel时，必须确保没任何地方（包括Filter、Interceptor）提前获取了Writer。我们在全局Filter中加了防护：

@Component public class ResponseGuardFilter implements Filter { @Override public void doFilter(ServletRequest request, ServletResponse response, FilterChain chain) throws IOException, ServletException { HttpServletResponse httpResponse = (HttpServletResponse) response; // 检查是否已获取Writer，若是则记录告警（开发环境） if (httpResponse.isCommitted()) { log.warn("Response already committed before filter chain!"); } chain.doFilter(request, response); } }

坑3：ZipOutputStream的closeEntry()必须成对出现
漏掉closeEntry()会导致ZIP结构损坏。我们曾用try-with-resources包装ZipOutputStream，但忘了putNextEntry()后必须closeEntry()。正确模板：

zos.putNextEntry(new ZipEntry("file1.txt")); // ... write data zos.closeEntry(); // 必须！ zos.putNextEntry(new ZipEntry("file2.txt")); // ... write data zos.closeEntry(); // 必须！ // 最后不调用zos.close()，由容器处理

坑4：Content-Length头在流式响应中无法预知
导出大数据量Excel时，response.setContentLengthLong()需要知道总字节数，但流式生成无法预知。此时必须删除该头，让容器自动计算。Spring Boot 2.3+会自动处理，但低版本需手动：

// 错误：试图计算长度（不现实） // response.setContentLengthLong(calculateSize()); // 正确：不设Content-Length，由容器处理 response.setHeader("Content-Length", ""); // 清空

坑5：@RequestPart和@RequestParam混用时的顺序陷阱
当接口同时有@RequestPart("file")和@RequestParam("name")，必须保证@RequestPart在前，否则Spring会先解析@RequestParam，导致MultipartFile流已被消费。正确声明：

@PostMapping("/import") public ResponseEntity<?> importData( @RequestPart("file") MultipartFile file, // 必须在前 @RequestParam("type") String type) { ... }

4.3 性能压测实录：500并发下的真实瓶颈点

我们用JMeter对“上传10MB文件”接口做了压测，结果令人意外：

关键发现：磁盘IO是比CPU更早出现的瓶颈。即使服务器有32核CPU，当500个线程同时写入临时文件，机械硬盘的随机写性能直接崩溃。解决方案不是加CPU，而是：

• 禁用Tomcat临时目录，改用内存文件系统（如/dev/shm）
• 或直接流式上传到OSS，跳过本地磁盘

// 配置Tomcat使用内存临时目录 @Bean public WebServerFactoryCustomizer<TomcatServletWebServerFactory> customizer() { return factory -> factory.addAdditionalTomcatConnectors( new Connector("org.apache.coyote.http11.Http11NioProtocol") {{ setProperty("uploadTempDir", "/dev/shm/tomcat-upload"); }} ); }

4.4 安全加固 checklist：生产环境必须做的5件事

1. 文件类型白名单校验：仅允许.xlsx,.xls,.pdf,.jpg等业务必需扩展名，拒绝application/x-msdownload等危险MIME类型。
2. 文件内容魔数校验：读取文件头4字节，确认xlsx是50 4B 03 04，jpg是FF D8 FF，防止扩展名伪造。
3. 上传路径隔离：所有上传文件存入独立目录（如/data/uploads/），且该目录禁止执行权限（chmod -x /data/uploads）。
4. 下载路径限制：X-Accel-Redirect或Files.newInputStream()的路径必须经过Paths.get(basePath, filename).normalize()标准化，防止../路径遍历。
5. 大文件超时熔断：在Controller层加@TimeLimiter注解（Resilience4j），上传超过300秒自动中断，释放连接。

5. 工具链与生态整合：让文件处理融入现代工程实践

5.1 Apache POI版本选型：4.1.2 vs 5.2.4的取舍

POI 4.x和5.x的核心差异在Java版本支持和模块化。POI 4.1.2支持Java 8+，而5.2.4要求Java 11+。我们选择4.1.2，原因有三：

• 公司基础镜像仍是OpenJDK 8，升级成本高；
• 4.1.2的SXSSF稳定性经受了3年线上考验；
• 5.x的WorkbookFactory虽简化了创建逻辑，但SXSSFWorkbook的dispose()方法在4.1.2中已足够可靠。

Maven依赖：

<dependency> <groupId>org.apache.poi</groupId> <artifactId>poi</artifactId> <version>4.1.2</version> </dependency> <dependency> <groupId>org.apache.poi</groupId> <artifactId>poi-ooxml</artifactId> <version>4.1.2</version> </dependency> <!-- 注意：不要引入poi-scratchpad，除非真需要处理旧版Word文档 -->

5.2 文件存储选型：本地磁盘、OSS、MinIO的适用场景

我们封装了统一的FileStorageService接口，三个实现类分别对应三种存储，业务代码完全无感：

public interface FileStorageService { String upload(InputStream inputStream, String fileName, String contentType); InputStream download(String fileKey); void delete(String fileKey); } @Service @ConditionalOnProperty(name = "file.storage.type", havingValue = "oss") public class OssFileStorageService implements FileStorageService { ... } @Service @ConditionalOnProperty(name = "file.storage.type", havingValue = "minio") public class MinioFileStorageService implements FileStorageService { ... }

5.3 日志与监控：如何追踪一次文件操作的全链路

文件处理涉及IO、网络、数据库，必须有全链路日志。我们在关键节点埋点：

@Slf4j @Service public class FileProcessingService { @Transactional public void importExcel(MultipartFile file) { String traceId = MDC.get("traceId"); // 从WebMvcConfigurer注入 log.info("【FILE_IMPORT_START】traceId={}, fileName={}, size={}KB", traceId, file.getOriginalFilename(), file.getSize() / 1024); try { // 解析逻辑... log.info("【FILE_IMPORT_SUCCESS】traceId={}, parsedRows={}", traceId, rowCount); } catch (Exception e) { log.error("【FILE_IMPORT_FAIL】traceId={}, error={}", traceId, e.getMessage(), e); throw e; } } }

同时，用Micrometer暴露关键指标：

• file.upload.size.bytes：上传文件大小分布
• file.export.duration.ms：导出耗时直方图
• file.download.count：下载次数计数器

Prometheus配置：

# prometheus.yml scrape_configs: - job_name: 'spring-boot' metrics_path: '/actuator/prometheus' static_configs: - targets: ['localhost:8080']

Grafana看板中，我们重点关注“P95导出耗时”和“上传失败率”，当失败率突增时，自动触发告警，排查是否是磁盘满或OSS限流。

5.4 单元测试覆盖：如何为文件操作写可靠的测试

文件操作难测试，因为涉及IO。我们的策略是Mock IO，聚焦业务逻辑：

@SpringBootTest class FileServiceTest { @Autowired private FileProcessingService fileService; @MockBean private FileStorageService storageService; // Mock存储层 @Test void testImportExcel() throws Exception { // 准备测试Excel：用SXSSFWorkbook生成内存文件 SXSSFWorkbook workbook = new SXSSFWorkbook(100); Sheet sheet = workbook.createSheet("data"); Row row = sheet.createRow(0); row.createCell(0).setCellValue("test@example.com"); ByteArrayOutputStream baos = new ByteArrayOutputStream(); workbook.write(baos); workbook.close(); // 构造MultipartFile MockMultipartFile file = new MockMultipartFile( "file", "test.xlsx", "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet", baos.toByteArray() ); // 执行导入 fileService.importExcel(file); // 验证：检查是否调用了存储服务的upload方法 verify(storageService, times(1)).upload(any(), any(), any()); } }

关键点：用MockMultipartFile和SXSSFWorkbook在内存中生成测试文件，避免读写磁盘，测试速度快且稳定。

5.5 前端协同要点：不只是后端的事

后端再健壮，前端配合不到位也会出问题。我们给前端团队的协作清单：

• 上传组件：必须支持分片上传（axios的CancelToken取消上传）、进度条、文件类型/大小前端校验（减轻服务端压力）。
• 导出按钮：禁用<a href="/export">，改用fetch+Blob，避免GET请求长度限制：

  const response = await fetch('/api/export', { method: 'POST', body: JSON.stringify(params) }); const blob = await response.blob(); const url = window.URL.createObjectURL(blob); const a = document.createElement('a'); a.href = url; a.download = 'export.xlsx'; a.click();

• 下载大文件：前端需监听onprogress事件，显示实时进度，避免用户误以为卡死。
• 中文名兼容：`