Spring MVC文件上传与下载全面详解：从原理到实战

深入掌握Spring MVC文件处理机制，解决实际开发中的各种问题

文章目录

[Spring MVC文件上传与下载全面详解：从原理到实战](#Spring MVC文件上传与下载全面详解：从原理到实战)
- 一、文件上传基础概念
- - [1.1 什么是multipart/form-data？](#1.1 什么是multipart/form-data？)
  - [1.2 MultipartResolver的作用](#1.2 MultipartResolver的作用)
- 二、文件上传配置实战
- - [2.1 添加依赖](#2.1 添加依赖)
  - [2.2 配置MultipartResolver](#2.2 配置MultipartResolver)
  - [2.3 配置参数详解](#2.3 配置参数详解)
- 三、文件上传控制器实现
- - [3.1 单文件上传](#3.1 单文件上传)
  - [3.2 多文件上传](#3.2 多文件上传)
  - [3.3 MultipartFile接口详解](#3.3 MultipartFile接口详解)
- 四、文件下载实现
- - [4.1 推荐的下载返回类型](#4.1 推荐的下载返回类型)
  - [4.2 Content-Type的作用](#4.2 Content-Type的作用)
- 五、异常处理与最佳实践
- - [5.1 常见异常处理](#5.1 常见异常处理)
  - [5.2 文件验证最佳实践](#5.2 文件验证最佳实践)
- 六、常见问题解答（FAQ）
- - [Q1: 为什么我的文件上传请求报404错误？](#Q1: 为什么我的文件上传请求报404错误？)
  - [Q2: 如何捕获文件大小超限异常？](#Q2: 如何捕获文件大小超限异常？)
  - [Q3: 大文件上传有什么注意事项？](#Q3: 大文件上传有什么注意事项？)
  - [Q4: 文件下载时中文文件名乱码怎么办？](#Q4: 文件下载时中文文件名乱码怎么办？)
- 七、总结

一、文件上传基础概念

1.1 什么是multipart/form-data？

当我们在HTML表单中上传文件时，必须设置 enctype="multipart/form-data"：

html 复制代码

<form method="POST" action="/upload" enctype="multipart/form-data">
    <input type="file" name="file" />
    <input type="submit" value="上传" />
</form>

这种编码方式会将表单数据分成多个部分（part），每个文件单独作为一个部分进行传输。

1.2 MultipartResolver的作用

MultipartResolver 是Spring MVC文件上传的核心组件，它就像公司的"总机接线员"：

java 复制代码

// 伪代码展示MultipartResolver的工作流程
public class MultipartResolver {
    public HttpServletRequest parseRequest(HttpServletRequest request) {
        // 1. 检查是否是文件上传请求
        if (!isMultipart(request)) return request;
        
        // 2. 解析multipart数据
        List<Part> parts = parseMultipartData(request);
        
        // 3. 封装结果
        HttpServletRequest wrappedRequest = new MultipartHttpServletRequest();
        for (Part part : parts) {
            if (part.isFile()) {
                wrappedRequest.addFile(part.getName(), createMultipartFile(part));
            } else {
                wrappedRequest.addParameter(part.getName(), part.getValue());
            }
        }
        return wrappedRequest;
    }
}

二、文件上传配置实战

2.1 添加依赖

xml 复制代码

<!-- Maven 依赖 -->
<dependency>
    <groupId>commons-fileupload</groupId>
    <artifactId>commons-fileupload</artifactId>
    <version>1.4</version>
</dependency>

2.2 配置MultipartResolver

XML配置方式：

xml 复制代码

<bean id="multipartResolver"
      class="org.springframework.web.multipart.commons.CommonsMultipartResolver">
    <!-- 最大上传大小 10MB -->
    <property name="maxUploadSize" value="10485760"/>
    <!-- 单个文件最大大小 5MB -->
    <property name="maxUploadSizePerFile" value="5242880"/>
    <!-- 内存中最大大小 1MB -->
    <property name="maxInMemorySize" value="1048576"/>
    <!-- 默认编码 -->
    <property name="defaultEncoding" value="UTF-8"/>
    <!-- 延迟解析，可在控制器中捕获异常 -->
    <property name="resolveLazily" value="true"/>
</bean>

Java配置方式（Spring Boot）：

java 复制代码

@Configuration
public class FileUploadConfig {
    
    @Bean
    public MultipartResolver multipartResolver() {
        CommonsMultipartResolver resolver = new CommonsMultipartResolver();
        resolver.setMaxUploadSize(10 * 1024 * 1024L);     // 10MB
        resolver.setMaxUploadSizePerFile(5 * 1024 * 1024L); // 5MB
        resolver.setMaxInMemorySize(1 * 1024 * 1024);     // 1MB
        resolver.setDefaultEncoding("UTF-8");
        resolver.setResolveLazily(true);
        return resolver;
    }
}

⚠️ 重要提醒：

bean的id必须为 multipartResolver
如果不配置，Spring MVC无法处理文件上传请求

2.3 配置参数详解

参数名	作用	推荐值	注意事项
`maxUploadSize`	整个请求最大大小	10MB	包含所有文件+表单数据
`maxUploadSizePerFile`	单个文件最大大小	5MB	限制每个上传文件
`maxInMemorySize`	内存缓存大小	1MB	不是越大越好，需平衡
`resolveLazily`	延迟解析	true	可在控制器捕获异常

三、文件上传控制器实现

3.1 单文件上传

java 复制代码

@Controller
public class FileUploadController {
    
    @PostMapping("/upload")
    public String handleFileUpload(@RequestParam("file") MultipartFile file,
                                 Model model) {
        if (file.isEmpty()) {
            model.addAttribute("message", "请选择文件");
            return "upload-result";
        }
        
        try {
            // 获取文件信息
            String originalFilename = file.getOriginalFilename();  // 原始文件名
            String contentType = file.getContentType();            // 文件类型
            long size = file.getSize();                            // 文件大小
            
            // 生成唯一文件名
            String fileName = UUID.randomUUID() + "_" + originalFilename;
            String filePath = "/uploads/" + fileName;
            
            // 保存文件
            file.transferTo(new File(filePath));
            
            model.addAttribute("message", "上传成功: " + originalFilename);
            model.addAttribute("filePath", filePath);
            
        } catch (IOException e) {
            model.addAttribute("message", "上传失败: " + e.getMessage());
        }
        
        return "upload-result";
    }
}

3.2 多文件上传

java 复制代码

@PostMapping("/multiUpload")
public String handleMultiFileUpload(@RequestParam("files") MultipartFile[] files,
                                  Model model) {
    List<String> successFiles = new ArrayList<>();
    List<String> failedFiles = new ArrayList<>();
    
    for (MultipartFile file : files) {
        if (!file.isEmpty()) {
            try {
                String fileName = file.getOriginalFilename();
                file.transferTo(new File("/uploads/" + fileName));
                successFiles.add(fileName);
            } catch (IOException e) {
                failedFiles.add(file.getOriginalFilename() + ": " + e.getMessage());
            }
        }
    }
    
    model.addAttribute("successFiles", successFiles);
    model.addAttribute("failedFiles", failedFiles);
    return "upload-result";
}

3.3 MultipartFile接口详解

方法	返回值	说明	使用场景
`getOriginalFilename()`	String	原始文件名(含后缀)	文件保存命名
`getBytes()`	byte[]	文件字节数组	小文件处理、数据库存储
`getContentType()`	String	MIME类型	文件类型验证
`transferTo(File)`	void	保存到文件	最常用的保存方式
`isEmpty()`	boolean	是否为空	空文件检查
`getSize()`	long	文件大小(字节)	大小限制验证
`getInputStream()`	InputStream	输入流	大文件流式处理

四、文件下载实现

4.1 推荐的下载返回类型

✅ 推荐方式1：ResponseEntity<byte[]>（小文件）

java 复制代码

@GetMapping("/download")
public ResponseEntity<byte[]> downloadFile() throws IOException {
    byte[] fileData = Files.readAllBytes(Paths.get("/path/to/file.pdf"));
    
    HttpHeaders headers = new HttpHeaders();
    headers.setContentType(MediaType.APPLICATION_PDF);
    headers.setContentDisposition(ContentDisposition.attachment()
                                .filename("document.pdf").build());
    
    return new ResponseEntity<>(fileData, headers, HttpStatus.OK);
}

✅ 推荐方式2：void + HttpServletResponse（直接输出）

java 复制代码

@GetMapping("/download")
public void downloadFile(HttpServletResponse response) throws IOException {
    File file = new File("/path/to/file.pdf");
    
    // 设置响应头
    response.setContentType("application/pdf");
    response.setHeader("Content-Disposition", 
                      "attachment; filename=\"document.pdf\"");
    
    // 文件拷贝到响应流
    Files.copy(file.toPath(), response.getOutputStream());
}

✅ 推荐方式3：ResponseEntity（Spring方式）

java 复制代码

@GetMapping("/download")
public ResponseEntity<Resource> downloadFile() {
    File file = new File("/path/to/file.pdf");
    Resource resource = new FileSystemResource(file);
    
    return ResponseEntity.ok()
            .contentType(MediaType.APPLICATION_PDF)
            .header(HttpHeaders.CONTENT_DISPOSITION, 
                   "attachment; filename=\"document.pdf\"")
            .body(resource);
}

❌ 不推荐：ModelAndView

java 复制代码

// 错误示例 - 不要这样做！
@GetMapping("/download")
public ModelAndView downloadFile() {
    // ModelAndView用于页面渲染，不适合文件下载
    return new ModelAndView("someView");
}

4.2 Content-Type的作用

Content-Type响应头的主要作用是告诉浏览器服务器返回的内容类型：

Content-Type	浏览器行为
`application/pdf`	内嵌显示或下载PDF
`image/jpeg`	直接显示图片
`text/plain`	显示文本内容
`application/octet-stream`	强制下载

五、异常处理与最佳实践

5.1 常见异常处理

java 复制代码

@ControllerAdvice
public class FileUploadExceptionHandler {
    
    // 文件大小超过限制异常
    @ExceptionHandler(MaxUploadSizeExceededException.class)
    public ResponseEntity<String> handleMaxSizeException() {
        return ResponseEntity.badRequest()
               .body("文件大小超过限制！请上传小于5MB的文件");
    }
    
    // 文件上传通用异常
    @ExceptionHandler(MultipartException.class)
    public ResponseEntity<String> handleMultipartException() {
        return ResponseEntity.badRequest()
               .body("文件上传失败，请检查文件格式和大小");
    }
}

5.2 文件验证最佳实践

java 复制代码

@Service
public class FileValidationService {
    
    // 文件类型白名单
    private static final Set<String> ALLOWED_TYPES = Set.of(
        "image/jpeg", "image/png", "application/pdf", "text/plain"
    );
    
    // 文件扩展名白名单
    private static final Set<String> ALLOWED_EXTENSIONS = Set.of(
        ".jpg", ".jpeg", ".png", ".pdf", ".txt"
    );
    
    public boolean validateFile(MultipartFile file) {
        // 1. 非空检查
        if (file.isEmpty()) {
            throw new IllegalArgumentException("文件不能为空");
        }
        
        // 2. 大小检查
        if (file.getSize() > 5 * 1024 * 1024) {
            throw new IllegalArgumentException("文件大小不能超过5MB");
        }
        
        // 3. 类型检查
        String contentType = file.getContentType();
        if (!ALLOWED_TYPES.contains(contentType)) {
            throw new IllegalArgumentException("不支持的文件类型: " + contentType);
        }
        
        // 4. 扩展名检查
        String originalFilename = file.getOriginalFilename();
        if (originalFilename != null) {
            String extension = originalFilename.substring(originalFilename.lastIndexOf("."));
            if (!ALLOWED_EXTENSIONS.contains(extension.toLowerCase())) {
                throw new IllegalArgumentException("不支持的文件扩展名: " + extension);
            }
        }
        
        return true;
    }
}

六、常见问题解答（FAQ）

Q1: 为什么我的文件上传请求报404错误？

A: 检查是否配置了MultipartResolver，且bean的id必须是multipartResolver。

Q2: 如何捕获文件大小超限异常？

A: 设置resolveLazily=true，并在控制器方法中捕获MaxUploadSizeExceededException。

Q3: 大文件上传有什么注意事项？

调整maxUploadSize和maxUploadSizePerFile
考虑使用分片上传
监控服务器内存使用

Q4: 文件下载时中文文件名乱码怎么办？

A: 对文件名进行URL编码：

java 复制代码

String encodedFileName = URLEncoder.encode(fileName, "UTF-8")
    .replaceAll("\\+", "%20");
response.setHeader("Content-Disposition", 
    "attachment; filename*=UTF-8''" + encodedFileName);

七、总结

Spring MVC文件上传下载的核心要点：

配置是基础：必须正确配置MultipartResolver
理解原理：MultipartResolver负责解析multipart请求
灵活选择：根据场景选择合适的文件处理方式
安全第一：始终验证文件类型和大小
异常处理：合理处理各种上传下载异常

通过本文的学习，相信你已经掌握了Spring MVC文件上传下载的完整知识体系，能够在实际项目中灵活应用这些技术解决文件处理需求。

技术成长之路，从掌握每一个细节开始！ 🚀