Spring Boot 与文件上传与下载：完整指南与最佳实践！

🏆本文收录于「滚雪球学SpringBoot」专栏(全网一个名)，手把手带你零基础入门Spring Boot，从入门到就业，助你早日登顶实现财富自由🚀；同时，欢迎大家关注&&收藏&&订阅！持续更新中，up！up！up！！

环境说明：Windows 10 + IntelliJ IDEA 2021.3.2 + Jdk 1.8

前言

在现代 Web 开发中，文件上传与下载是非常常见的需求之一。不论是用户上传图片、PDF 文件，还是需要提供文档下载，Spring Boot 提供了非常简便和强大的支持。文件上传和下载的正确实现，可以极大地提升用户体验并保证系统的高效性。

本篇文章将从基本的文件上传流程讲起，逐步深入讲解如何在 Spring Boot 中配置文件上传与下载，并涵盖常见的文件大小和类型限制。通过实际案例，我们将演示如何高效地使用 MultipartFile 接收文件，如何通过流式处理进行文件下载，以及如何优化文件上传下载的性能和安全性。

🗺️ 目录

1. 📝 文件上传的基本流程
2. ⚙️ 配置文件上传参数
3. 📥 使用 MultipartFile 接收文件
4. 📤 文件下载与流式处理
5. 🚫 文件大小与类型限制
6. 🛠️ 性能优化与常见问题
7. 🧪 实战演示：文件上传与下载项目

1) 📝 文件上传的基本流程

文件上传通常需要以下几个步骤：

1. 客户端请求：用户通过表单选择文件并提交。
2. 服务器接收：服务器接收到文件数据，通常通过 Multipart 方式进行传输。
3. 保存文件：服务器将接收到的文件保存到指定位置（本地存储、数据库或云存储）。
4. 返回响应：服务器返回文件上传成功或失败的响应。

基本流程示意图

在 Spring Boot 中，我们通过 @RequestMapping 或 @PostMapping 来处理文件上传请求，利用 MultipartFile 接收文件并进行存储。Spring Boot 内置的文件上传处理器能够让我们轻松处理这类请求。

2) ⚙️ 配置文件上传参数

Spring Boot 提供了很简单的配置方式来控制文件上传的参数，例如文件大小、上传位置等。默认情况下，Spring Boot 使用了 Tomcat 作为内嵌容器，因此文件上传的配置项可以在 application.properties 或 application.yml 中进行调整。

配置文件大小限制

在 application.properties 文件中，可以通过以下属性来配置上传文件的大小限制：

# 限制单个文件的大小为 2MB
spring.servlet.multipart.max-file-size=2MB

# 限制上传文件总大小为 10MB
spring.servlet.multipart.max-request-size=10MB

配置文件存储路径

我们可以通过 Spring Boot 的配置项指定文件存储的路径：

# 文件上传保存的路径
file.upload-dir=/path/to/upload-directory

配置默认上传字符编码

如果需要指定上传文件的字符编码，可以使用如下配置：

# 设置文件上传字符编码
spring.servlet.multipart.charset=UTF-8

Spring Boot 会自动根据这些配置处理文件上传的基本需求。

3) 📥 使用 MultipartFile 接收文件

MultipartFile 是 Spring 用于处理文件上传的接口。它封装了上传的文件，可以方便地获取文件名、内容类型、大小等信息。

接收单个文件

我们使用 @RequestParam 注解来接收上传的文件。以下是一个处理单个文件上传的例子：

@RestController
public class FileUploadController {

    @PostMapping("/upload")
    public ResponseEntity<String> handleFileUpload(@RequestParam("file") MultipartFile file) {
        try {
            // 保存文件到指定目录
            String fileName = file.getOriginalFilename();
            Path path = Paths.get("/path/to/upload-directory", fileName);
            Files.write(path, file.getBytes());

            return ResponseEntity.ok("File uploaded successfully: " + fileName);
        } catch (IOException e) {
            return ResponseEntity.status(HttpStatus.INTERNAL_SERVER_ERROR).body("File upload failed");
        }
    }
}

在这个例子中：

• @RequestParam("file") 用于接收前端表单提交的文件。
• 通过 file.getOriginalFilename() 获取文件名。
• 使用 Files.write() 将文件保存到指定的目录。

接收多个文件

如果要支持多个文件上传，只需要通过 MultipartFile[] 数组接收：

@PostMapping("/uploadMultiple")
public ResponseEntity<String> handleMultipleFilesUpload(@RequestParam("files") MultipartFile[] files) {
    for (MultipartFile file : files) {
        try {
            String fileName = file.getOriginalFilename();
            Path path = Paths.get("/path/to/upload-directory", fileName);
            Files.write(path, file.getBytes());
        } catch (IOException e) {
            return ResponseEntity.status(HttpStatus.INTERNAL_SERVER_ERROR).body("File upload failed");
        }
    }
    return ResponseEntity.ok("Files uploaded successfully");
}

在这个例子中，我们通过 MultipartFile[] 来接收多个文件，并循环保存每个文件。

4) 📤 文件下载与流式处理

文件下载通常会涉及到大文件的传输，因此使用流式处理能够有效地减少内存消耗并提高传输效率。Spring 提供了非常简便的文件下载支持，下面我们将介绍如何通过流式处理下载文件。

基本文件下载实现

@RestController
public class FileDownloadController {

    @GetMapping("/download/{fileName}")
    public ResponseEntity<Resource> downloadFile(@PathVariable String fileName) {
        try {
            // 读取文件内容
            Path path = Paths.get("/path/to/upload-directory", fileName);
            Resource resource = new FileSystemResource(path);

            // 设置文件下载响应头
            String contentType = Files.probeContentType(path);
            return ResponseEntity.ok()
                    .contentType(MediaType.parseMediaType(contentType))
                    .header(HttpHeaders.CONTENT_DISPOSITION, "attachment; filename=\"" + resource.getFilename() + "\"")
                    .body(resource);
        } catch (IOException e) {
            return ResponseEntity.status(HttpStatus.INTERNAL_SERVER_ERROR).body(null);
        }
    }
}

解释：

1. 读取文件内容：通过 FileSystemResource 获取文件内容，支持从文件系统中读取文件。
2. 响应头设置：通过 HttpHeaders.CONTENT_DISPOSITION 设置响应头，指定文件以附件形式下载。
3. 流式下载：使用 Resource 来实现流式下载，避免将文件内容加载到内存中，适用于大文件下载。

使用 ResponseEntity 返回文件

ResponseEntity<Resource> downloadFile(String filePath) {
    File file = new File(filePath);
    InputStreamResource resource = new InputStreamResource(new FileInputStream(file));
    
    return ResponseEntity.ok()
            .contentType(MediaType.APPLICATION_OCTET_STREAM)
            .header(HttpHeaders.CONTENT_DISPOSITION, "attachment; filename=\"" + file.getName() + "\"")
            .body(resource);
}

这种方式可以有效减少内存消耗，适合处理大文件的下载。

5) 🚫 文件大小与类型限制

5.1 文件大小限制

为了避免恶意上传过大的文件，Spring Boot 默认会有文件大小限制。通过配置参数，我们可以对上传文件的大小进行限制：

# 单个文件最大2MB
spring.servlet.multipart.max-file-size=2MB

# 整个请求最大10MB
spring.servlet.multipart.max-request-size=10MB

5.2 文件类型限制

有时候，我们希望限制上传的文件类型，例如仅允许上传图片或文档。Spring 提供了 CommonsMultipartResolver 来进行文件类型的校验。通过 Content-Type 来进行文件类型的检查。

@PostMapping("/uploadImage")
public ResponseEntity<String> uploadImage(@RequestParam("file") MultipartFile file) {
    String contentType = file.getContentType();
    if (contentType == null || !contentType.startsWith("image/")) {
        return ResponseEntity.status(HttpStatus.BAD_REQUEST).body("Invalid file type. Only images are allowed.");
    }

    // 处理文件
    return ResponseEntity.ok("File uploaded successfully");
}

通过 file.getContentType() 来获取文件的 Content-Type，并检查文件是否是图片。

6) 🛠️ 性能优化与常见问题

6.1 性能优化

• 异步处理：使用 @Async 注解来异步处理文件上传或下载任务，避免主线程阻塞。
• 多线程上传：对于大文件，可以分块上传，使用多线程来处理不同的文件块，提高上传速度。
• 内存优化：使用流式处理下载大文件，避免将大文件全部加载到内存中。

6.2 常见问题与解决

• 文件上传失败：检查文件大小和类型配置是否符合要求。
• 文件下载慢：使用流式下载文件，并通过 CDN 等技术加速文件传输。
• 上传大文件超时：通过调整 server.tomcat.connection-timeout 和 spring.servlet.multipart 配置，增加超时时间。

7) 🧪 实战演示：文件上传与下载项目

在本项目中，我们创建了一个简单的文件上传与下载系统，使用 MultipartFile 处理上传文件，利用流式下载优化文件传输，配置文件大小与类型限制，确保系统高效且安全。

1. 配置 application.properties 设置文件上传参数。
2. 创建文件上传接口，支持接收单个或多个文件。
3. 创建文件下载接口，使用流式处理优化文件传输。
4. 配置文件类型和大小限制，确保只允许上传合规文件。

通过这个实战项目，我们能够快速实现文件上传与下载功能，同时保证系统的性能和安全。

总结

在本篇文章中，我们深入探讨了 Spring Boot 与文件上传与下载 的实现，包括了文件上传的基本流程、使用 MultipartFile 接收文件、文件下载与流式处理、文件大小与类型限制等内容。通过实际案例的讲解，我们不仅了解了如何高效处理文件上传下载，还学习了如何通过优化配置和代码来提升系统性能。

希望这篇文章能够帮助你更好地理解和实现文件上传与下载的功能，让你在 Spring Boot 开发中得心应手！🚀

🧧福利赠与你🧧

  无论你是计算机专业的学生，还是对编程有兴趣的小伙伴，都建议直接毫无顾忌的学习此专栏「滚雪球学SpringBoot」专栏(全网一个名)，bug菌郑重承诺，凡是学习此专栏的同学，均能获取到所需的知识和技能，全网最快速入门SpringBoot，就像滚雪球一样，越滚越大， 无边无际，指数级提升。

  最后，如果这篇文章对你有所帮助，帮忙给作者来个一键三连，关注、点赞、收藏，您的支持就是我坚持写作最大的动力。

  同时欢迎大家关注公众号:「猿圈奇妙屋」 ，以便学习更多同类型的技术文章，免费白嫖最新BAT互联网公司面试题、4000G pdf电子书籍、简历模板、技术文章Markdown文档等海量资料。

✨️ Who am I?

我是bug菌(全网一个名)，CSDN | 掘金 | InfoQ | 51CTO | 华为云 | 阿里云 | 腾讯云 等社区博客专家，C站博客之星Top30，华为云多年度十佳博主/价值贡献奖，掘金多年度人气作者Top40，掘金等各大社区平台签约作者，51CTO年度博主Top12，掘金/InfoQ/51CTO等社区优质创作者；全网粉丝合计 30w+；更多精彩福利点击这里；硬核微信公众号「猿圈奇妙屋」，欢迎你的加入！免费白嫖最新BAT互联网公司面试真题、4000G PDF电子书籍、简历模板等海量资料，你想要的我都有，关键是你不来拿。

-End-