当前位置：首页 > backend >正文

【SpringMVC文件上传终极指南：从基础配置到云存储集成】

backend 2025/7/3 8:52:47

在这里插入图片描述

🎥博主：程序员不想YY啊
💫CSDN优质创作者，CSDN实力新星，CSDN博客专家
🤗点赞🎈收藏⭐再看💫养成习惯
✨希望本文对您有所裨益，如有不足之处，欢迎在评论区提出指正，让我们共同学习、交流进步！

SpringMVC 文件上传基础概念

1、文件上传原理

文件上传本质上是客户端将本地文件数据通过 HTTP 协议发送到服务器端的过程，在 SpringMVC 中，当浏览器发起文件上传请求时，请求数据会按照特定格式进行封装，SpringMVC 通过相关组件解析请求，将文件数据保存到服务器指定位置。

2、必备依赖

在使用 SpringMVC 进行文件上传前，需要在项目的构建文件（如 Maven 的pom.xml）中添加相关依赖，主要依赖有 SpringMVC 核心依赖和文件上传组件依赖，以 Maven 项目为例：

<dependencies><!-- SpringMVC核心依赖 --><dependency><groupId>org.springframework</groupId><artifactId>spring-webmvc</artifactId><version>5.3.10</version></dependency><!-- 文件上传组件，常用的是commons-fileupload --><dependency><groupId>commons-fileupload</groupId><artifactId>commons-fileupload</artifactId><version>1.4</version></dependency>
</dependencies>

其中，commons-fileupload组件负责处理文件上传的具体操作，它依赖于commons-io组件，Maven 会自动解析并下载所需依赖。

SpringMVC文件上传核心原理

1、技术栈全景图

在这里插入图片描述

2、核心组件解析

MultipartResolver： 请求解析引擎（Apache Commons vs Servlet 3.0+）
MultipartFile： Spring封装的文件操作接口
临时存储： 服务器内存或系统临时目录（需及时清理）

全版本环境配置（含Spring Boot）

1、Maven依赖（传统Spring项目）

<!-- Apache Commons FileUpload -->
<dependency><groupId>commons-fileupload</groupId><artifactId>commons-fileupload</artifactId><version>1.5</version>
</dependency><!-- Servlet 3.0+ 容器（Tomcat 8+） -->
<dependency><groupId>javax.servlet</groupId><artifactId>javax.servlet-api</artifactId><version>4.0.1</version><scope>provided</scope>
</dependency>

2、Spring Boot自动化配置

# application.yml 关键配置
spring:servlet:multipart:max-file-size: 50MBmax-request-size: 100MBlocation: /tmp/uploads # 临时目录resolve-lazily: false # 是否延迟解析

SpringMVC文件上传的示例代码

1. 创建一个上传文件的HTML表单：
<form action="/upload" method="post" enctype="multipart/form-data"><input type="file" name="file" /><input type="submit" value="Upload" />
</form>

2. 创建一个UploadController来处理文件上传请求：
@Controller
public class UploadController {@PostMapping("/upload")public String uploadFile(@RequestParam("file") MultipartFile file) {// 检查文件是否为空if (file.isEmpty()) {return "redirect:/error";}try {// 获取文件名String fileName = file.getOriginalFilename();// 获取文件的字节数据byte[] bytes = file.getBytes();// 文件保存路径String filePath = "/path/to/save/" + fileName;// 将文件保存到指定路径Files.write(Paths.get(filePath), bytes);return "redirect:/success";} catch (IOException e) {e.printStackTrace();return "redirect:/error";}}
}

3. 创建一个DownloadController来处理文件下载请求：
@Controller
public class DownloadController {@GetMapping("/download")public ResponseEntity<Resource> downloadFile() {// 文件路径String filePath = "/path/to/file";// 创建文件对象File file = new File(filePath);// 创建文件资源对象Resource resource = new FileSystemResource(file);// 设置响应头HttpHeaders headers = new HttpHeaders();headers.add(HttpHeaders.CONTENT_DISPOSITION, "attachment; filename=" + file.getName());return ResponseEntity.ok().headers(headers).contentLength(file.length()).contentType(MediaType.APPLICATION_OCTET_STREAM).body(resource);}
}
请注意，上述代码中的文件保存路径和下载文件路径需要根据实际情况进行修改

1、表单准备（前端关键代码）

<form action="/upload" method="post" enctype="multipart/form-data"><input type="file" name="file" multiple> <!-- 多文件支持 --><input type="text" name="description"><button type="submit">上传</button>
</form>

2、控制器实现（单文件+多文件）

@PostMapping("/upload")
public String handleUpload(@RequestParam("file") MultipartFile file,@RequestParam("description") String desc,RedirectAttributes redirectAttributes) {if (file.isEmpty()) {redirectAttributes.addFlashAttribute("message", "请选择文件");return "redirect:/status";}try {// 安全存储路径（防止路径穿越攻击）Path safePath = Paths.get("/secure-upload").resolve(Paths.get(file.getOriginalFilename()).normalize());Files.copy(file.getInputStream(), safePath, StandardCopyOption.REPLACE_EXISTING);redirectAttributes.addFlashAttribute("message", "上传成功: " + file.getOriginalFilename());} catch (IOException e) {redirectAttributes.addFlashAttribute("message", "上传失败: " + e.getMessage());}return "redirect:/status";
}// 多文件上传
@PostMapping("/multi-upload")
public String multiUpload(@RequestParam("files") MultipartFile[] files) {Arrays.stream(files).forEach(this::saveFile);return "redirect:/status";
}

导入依赖的包

在pom.xml文件中导入依赖的包：

<dependency><groupId>commons-fileupload</groupId><artifactId>commons-fileupload</artifactId><version>1.3.3</version>
</dependency>

配置文件上传解析器

<bean id="multipartResolver" class="org.springframework.web.multipart.commons.CommonsMultipartResolver"><!-- 必须和用户JSP 的pageEncoding属性一致，以便正确解析表单的内容 --><property name="defaultEncoding" value="UTF-8"></property><!-- 文件最大大小(字节) 1024*1024*50=50M--><property name="maxUploadSize" value="52428800"></property><!--resolveLazily属性启用是为了推迟文件解析，以便捕获文件大小异常--><property name="resolveLazily" value="true"/></bean>

数据表

create table t_book_file
(file_id varchar(32) primary key comment '文件ID',real_name varchar(50) not null comment '文件名称',content_type varchar(50) not null comment '文件类型',url varchar(256) not null comment '文件路径'
);

在book表中加入一个字段来保存上传文件的ID，即：与file_id字段对应。

controller

在这里插入图片描述
编辑index.jsp
增加上传链接打开进入上传的页面

上传页面

该截图中的代码只是保存了图片，还需要将图片的信息保存到文件数据表中，请自行完善。

下载

核心代码：

@RequestMapping(value="/download")
public ResponseEntity<byte[]> download(@RequestParam String fileId){//先根据文件id查询对应图片信息，相关的后台代码省略，自行编写//下载关键代码File file=new File(bookFile.getUrl());HttpHeaders headers = new HttpHeaders();//http头信息String downloadFileName = new String(fileName.getBytes("UTF-8"),"iso-8859-1");//设置编码headers.setContentDispositionFormData("attachment", downloadFileName);headers.setContentType(MediaType.APPLICATION_OCTET_STREAM);//MediaType:互联网媒介类型  contentType：具体请求中的媒体类型信息return new ResponseEntity<byte[]>(FileUtils.readFileToByteArray(file),headers, HttpStatus.OK);}

下载功能链接，示例代码

<!-- 判断是否 存在图片，如果有图片则提供下载 -->
<c:if test="${not empty b.bookImages}">    <a href="${ctx}/bookFile/download?fileId=${b.bookImages}">下载图片</a>
</c:if>

高级功能扩展

1、文件校验拦截器

@Component
public class FileTypeInterceptor implements HandlerInterceptor {private static final Set<String> ALLOWED_TYPES = Set.of("image/jpeg", "image/png", "application/pdf");@Overridepublic boolean preHandle(HttpServletRequest request, HttpServletResponse response, Object handler) throws Exception {if (request instanceof MultipartHttpServletRequest) {MultipartHttpServletRequest multiRequest = (MultipartHttpServletRequest) request;multiRequest.getFileMap().forEach((name, file) -> {if (!ALLOWED_TYPES.contains(file.getContentType())) {throw new IllegalArgumentException("禁止的文件类型: " + file.getContentType());}});}return true;}
}

2、云存储集成（以阿里云OSS为例）

@Bean
public OSS ossClient() {return new OSSClientBuilder().build("oss-cn-beijing.aliyuncs.com","<your-access-key>","<your-secret-key>");
}@PostMapping("/oss-upload")
public String uploadToOSS(@RequestParam("file") MultipartFile file) {try {ossClient().putObject("your-bucket", "uploads/" + UUID.randomUUID() + getFileExtension(file),file.getInputStream());return "redirect:/success";} catch (IOException e) {throw new RuntimeException("OSS上传失败", e);}
}

生产级最佳实践

1、安全防护策略

风险类型	防御措施	实现示例
路径穿越	文件名规范化校验	`Paths.get(name).normalize()`
超大文件	限制最大文件尺寸	`@MaxFileSize(100MB)`
恶意类型	白名单校验Content-Type	拦截器检查MIME类型
重复攻击	客户端秒传（文件哈希校验）	MD5文件摘要比对

2、性能优化技巧

异步上传： 结合@Async与CompletableFuture
分片上传： 前端WebUploader + 后端断点续传接口
CDN加速： 上传后自动刷新CDN缓存
分布式文件存储： 在大型项目中，单机存储可能无法满足需求，此时可以考虑使用分布式文件存储系统，如 FastDFS、MinIO 等。将文件上传到分布式存储系统后，服务器只保存文件的访问地址，这样既提高了存储容量，又增强了系统的可扩展性和可靠性。

常见问题

1、上传失败提示“临时目录不可写”

检查spring.servlet.multipart.location权限
Linux执行：chmod 777 /tmp/uploads

2、中文文件名乱码

# 在spring配置中增加
spring.http.encoding.force=true
spring.http.encoding.charset=UTF-8
spring.http.encoding.enabled=true

3、如何获取上传进度？

前端：XMLHttpRequest的progress事件
后端：实现CommonsMultipartResolver的进度监听接口

4、Spring Boot下配置不生效？

确认依赖是否包含spring-boot-starter-web
检查是否有自定义MultipartConfigElement Bean覆盖默认配置

5、文件大小限制问题

在实际应用中，可能会遇到文件大小超出配置限制的情况。除了在CommonsMultipartResolver中设置maxUploadSize外，还需要注意 Tomcat 等服务器对请求大小的限制。以 Tomcat 为例，可以在server.xml文件中修改相关配置：

<Connector port="8080" protocol="HTTP/1.1"connectionTimeout="20000"redirectPort="8443"maxPostSize="10485760" />

通过设置maxPostSize参数（单位为字节），可以调整 Tomcat 允许接收的最大 POST 请求大小，避免因文件过大导致上传失败。

6、文件名重复问题

当多个用户上传相同文件名的文件时，可能会出现覆盖现象,为避免这种情况，可以在保存文件时对文件名进行处理，例如添加时间戳或随机字符串,修改后的保存文件代码如下：

import java.util.UUID;
//...
String uuid = UUID.randomUUID().toString().replaceAll("-", "");
String newFileName = uuid + "_" + fileName;
File targetFile = new File(filePath, newFileName);
file.transferTo(targetFile);

通过生成唯一的 UUID 并与原文件名拼接，确保每个上传文件都有唯一的文件名。

7、文件类型限制问题

为了保证系统安全和数据规范，有时需要限制上传文件的类型。可以通过判断文件扩展名的方式实现，示例代码如下：

String fileExtension = fileName.substring(fileName.lastIndexOf(".") + 1);
if (!"jpg".equals(fileExtension) &&!"png".equals(fileExtension) &&!"pdf".equals(fileExtension)) {modelAndView.addObject("message", "只允许上传jpg、png、pdf格式的文件");modelAndView.setViewName("result");return modelAndView;
}

上述代码判断文件扩展名是否在允许的范围内，如果不在则返回错误提示信息。

测试与调试技巧

1、Postman测试脚本

// 在Postman的Tests标签页添加
pm.test("Upload Success", function() {pm.response.to.have.status(200);pm.expect(pm.response.text()).to.include("success");
});

2、JUnit单元测试

@SpringBootTest
@AutoConfigureMockMvc
class FileUploadTest {@Autowiredprivate MockMvc mockMvc;@Testvoid testUpload() throws Exception {MockMultipartFile file = new MockMultipartFile("file", "test.txt", "text/plain", "Hello World".getBytes());mockMvc.perform(multipart("/upload").file(file).param("description", "test case")).andExpect(status().is3xxRedirection()).andExpect(redirectedUrl("/status"));}
}