Spring Boot 实战：轻松实现文件上传与下载功能

一、引言

二、Spring Boot 文件上传基础

（一）依赖引入

（二）配置文件设置

（三）文件上传接口编写

（一）文件类型限制

（二）文件大小验证

（三）防止文件覆盖

四、Spring Boot 文件下载实现

（一）简单文件下载接口编写

（二）文件下载的异常处理

（三）支持断点续传

五、实战案例演示

六、总结与展望

一、引言

在当今的 Web 应用开发中，文件上传与下载功能是极为常见且重要的需求。无论是用户上传头像、分享文档，还是系统生成报告供用户下载，都离不开这一功能模块。Spring Boot 作为一款流行的 Java 开发框架，为我们提供了简洁高效的方式来实现文件上传与下载。本文将详细介绍如何基于 Spring Boot 框架轻松搭建并实现这一功能，让你快速掌握其核心要点与实践技巧。

二、Spring Boot 文件上传基础

（一）依赖引入

在 Spring Boot 项目中，首先需要引入相关依赖。对于文件上传功能，除了基础的spring-boot-starter-web依赖外，还需要添加处理文件上传的commons-fileupload依赖。在pom.xml文件中添加如下依赖：

<dependency><groupId>org.springframework.boot</groupId><artifactId>spring-boot-starter-web</artifactId>
</dependency>
<dependency><groupId>commons-fileupload</groupId><artifactId>commons-fileupload</artifactId><version>1.4</version>
</dependency>

spring-boot-starter-web提供了构建 Web 应用的基础功能，而commons-fileupload则专门用于处理文件上传操作。

（二）配置文件设置

在application.properties配置文件中设置与文件上传相关的参数。例如：

?
# 设置单个文件上传的最大大小为 10MB
spring.servlet.multipart.max-file-size=10MB
# 设置一次请求中上传文件的总大小为 20MB
spring.servlet.multipart.max-request-size=20MB
# 设置上传文件的临时目录
spring.servlet.multipart.location=/tmp/uploads?

这里分别设置了单个文件大小限制、总请求文件大小限制以及上传文件的临时存储目录。这些配置可以根据实际项目需求进行调整。

（三）文件上传接口编写

编写一个简单的文件上传接口，接收前端传来的文件数据。创建一个FileUploadController类：

import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.RequestParam;
import org.springframework.web.bind.annotation.RestController;
import org.springframework.web.multipart.MultipartFile;import java.io.File;
import java.io.IOException;@RestController
public class FileUploadController {@PostMapping("/upload")public String uploadFile(@RequestParam("file") MultipartFile file) {if (file.isEmpty()) {return "上传文件为空，请选择文件后再次上传。";}try {// 获取文件名String fileName = file.getOriginalFilename();// 获取文件存储路径，这里假设存储在项目根目录下的 uploads 文件夹中String filePath = System.getProperty("user.dir") + "/uploads/" + fileName;// 将文件保存到指定路径file.transferTo(new File(filePath));return "文件上传成功，文件路径：" + filePath;} catch (IOException e) {e.printStackTrace();return "文件上传失败：" + e.getMessage();}}
}

在上述代码中，@RestController表示这是一个处理 RESTful 风格请求的控制器类。@PostMapping("/upload")注解指定了该方法处理POST请求到/upload路径的逻辑。@RequestParam("file") MultipartFile file用于接收前端传来的名为file的文件数据。通过file.isEmpty()判断文件是否为空，如果不为空，则获取文件的原始名称getOriginalFilename()，构建文件存储路径，最后使用transferTo()方法将文件保存到指定路径。如果保存过程中出现IOException异常，则打印异常信息并返回错误提示。

（一）文件类型限制

可以通过白名单的方式对上传文件的类型进行限制。例如，只允许上传图片文件（如.jpg、.png、.gif）：

private static final String[] ALLOWED_FILE_TYPES = { "image/jpeg", "image/png", "image/gif" };@PostMapping("/upload")
public String uploadFile(@RequestParam("file") MultipartFile file) {if (file.isEmpty()) {return "上传文件为空，请选择文件后再次上传。";}// 检查文件类型是否在允许列表中if (!Arrays.asList(ALLOWED_FILE_TYPES).contains(file.getContentType())) {return "不允许上传该类型的文件，请上传图片文件（jpg、png、gif）。";}try {// 后续文件保存逻辑...} catch (IOException e) {e.printStackTrace();return "文件上传失败：" + e.getMessage();}
}

上述代码中，定义了一个允许的文件类型数组ALLOWED_FILE_TYPES，然后在上传文件前检查文件的ContentType是否在允许列表中，如果不在，则返回错误提示。

（二）文件大小验证

除了配置文件中的全局限制，在代码层面也可以再次验证单个文件大小：

@PostMapping("/upload")
public String uploadFile(@RequestParam("file") MultipartFile file) {if (file.isEmpty()) {return "上传文件为空，请选择文件后再次上传。";}// 检查文件大小是否超过 5MBif (file.getSize() > 5 * 1024 * 1024) {return "上传文件过大，单个文件大小不能超过 5MB。";}// 后续文件类型检查及保存逻辑...
}

这里通过file.getSize()获取文件大小，并与设定的限制（5MB）进行比较，如果超过则返回错误提示。

（三）防止文件覆盖

采用时间戳生成唯一文件名来防止文件覆盖：

@PostMapping("/upload")
public String uploadFile(@RequestParam("file") MultipartFile file) {if (file.isEmpty()) {return "上传文件为空，请选择文件后再次上传。";}try {// 获取文件名String originalFileName = file.getOriginalFilename();// 获取文件后缀名String fileExtension = originalFileName.substring(originalFileName.lastIndexOf("."));// 生成唯一文件名，使用当前时间戳String uniqueFileName = System.currentTimeMillis() + fileExtension;// 获取文件存储路径，这里假设存储在项目根目录下的 uploads 文件夹中String filePath = System.getProperty("user.dir") + "/uploads/" + uniqueFileName;// 将文件保存到指定路径file.transferTo(new File(filePath));return "文件上传成功，文件路径：" + filePath;} catch (IOException e) {e.printStackTrace();return "文件上传失败：" + e.getMessage();}
}

通过获取原始文件名的后缀名，结合当前时间戳生成一个唯一的文件名，确保每次上传的文件都有独立的标识，避免覆盖同名文件。

四、Spring Boot 文件下载实现

（一）简单文件下载接口编写

创建一个文件下载接口，如下：

import org.springframework.core.io.FileSystemResource;
import org.springframework.http.HttpHeaders;
import org.springframework.http.MediaType;
import org.springframework.http.ResponseEntity;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RequestParam;
import org.springframework.web.bind.annotation.RestController;import java.io.File;@RestController
public class FileDownloadController {@GetMapping("/download")public ResponseEntity<FileSystemResource> downloadFile(@RequestParam("fileName") String fileName) {// 获取文件路径，这里假设文件存储在项目根目录下的 uploads 文件夹中String filePath = System.getProperty("user.dir") + "/uploads/" + fileName;File file = new File(filePath);if (file.exists()) {// 设置响应头信息，包括文件名和文件类型HttpHeaders headers = new HttpHeaders();headers.add(HttpHeaders.CONTENT_DISPOSITION, "attachment;filename=" + fileName);headers.add(HttpHeaders.CONTENT_TYPE, MediaType.APPLICATION_OCTET_STREAM_VALUE);// 返回文件资源return ResponseEntity.ok().headers(headers).body(new FileSystemResource(file));} else {return ResponseEntity.notFound().build();}}
}

在这个代码中，@GetMapping("/download")表示处理GET请求到/download路径的逻辑。根据前端传入的文件名参数fileName，构建文件路径并检查文件是否存在。如果存在，则设置响应头信息，包括Content-Disposition用于指定文件名和下载方式（attachment表示下载），Content-Type设置为APPLICATION_OCTET_STREAM_VALUE表示通用的二进制流文件类型。最后通过ResponseEntity返回文件资源，若文件不存在则返回404 Not Found状态。

（二）文件下载的异常处理

在上述代码中，如果文件不存在则返回404状态。还可以进一步处理其他可能的异常，例如文件读取错误：

@GetMapping("/download")
public ResponseEntity<FileSystemResource> downloadFile(@RequestParam("fileName") String fileName) {String filePath = System.getProperty("user.dir") + "/uploads/" + fileName;File file;try {file = new File(filePath);if (file.exists()) {// 设置响应头信息...return ResponseEntity.ok().headers(headers).body(new FileSystemResource(file));} else {return ResponseEntity.notFound().build();}} catch (Exception e) {e.printStackTrace();return ResponseEntity.status(HttpStatus.INTERNAL_SERVER_ERROR).build();}
}

这里捕获了可能出现的异常，并在异常发生时返回500 Internal Server Error状态码，表示服务器内部错误。

（三）支持断点续传

对于大文件下载实现断点续传功能：

@GetMapping("/download")
public ResponseEntity<Resource> downloadFile(@RequestParam("fileName") String fileName,@RequestHeader(value = "Range", required = false) String rangeHeader) {String filePath = System.getProperty("user.dir") + "/uploads/" + fileName;File file = new File(filePath);if (file.exists()) {try {// 获取文件长度long fileLength = file.length();// 处理 Range 请求头HttpHeaders headers = new HttpHeaders();if (rangeHeader!= null && rangeHeader.startsWith("bytes=")) {long startRange = Long.parseLong(rangeHeader.substring("bytes=".length()).split("-")[0]);long endRange = fileLength - 1;if (rangeHeader.contains("-")) {endRange = Long.parseLong(rangeHeader.substring("bytes=".length()).split("-")[1]);}// 设置响应头的 Content-Range 字段headers.add(HttpHeaders.CONTENT_RANGE, "bytes " + startRange + "-" + endRange + "/" + fileLength);headers.add(HttpHeaders.CONTENT_LENGTH, String.valueOf(endRange - startRange + 1));headers.add(HttpHeaders.ACCEPT_RANGES, "bytes");// 设置响应状态码为 206 Partial Contentreturn ResponseEntity.status(HttpStatus.PARTIAL_CONTENT).headers(headers).body(new FileSystemResource(file).createRelative(startRange, endRange));} else {headers.add(HttpHeaders.CONTENT_LENGTH, String.valueOf(fileLength));headers.add(HttpHeaders.CONTENT_TYPE, MediaType.APPLICATION_OCTET_STREAM_VALUE);headers.add(HttpHeaders.CONTENT_DISPOSITION, "attachment;filename=" + fileName);return ResponseEntity.ok().headers(headers).body(new FileSystemResource(file));}} catch (Exception e) {e.printStackTrace();return ResponseEntity.status(HttpStatus.INTERNAL_SERVER_ERROR).build();}} else {return ResponseEntity.notFound().build();}
}

在上述代码中，首先获取文件的总长度fileLength。然后检查请求头中的Range信息，如果存在Range请求，则解析出起始和结束位置startRange和endRange，设置响应头的Content-Range、Content-Length和ACCEPT_RANGES字段，并返回206 Partial Content状态码，表示部分内容响应，同时通过createRelative()方法读取文件指定范围的数据返回给客户端。如果没有Range请求，则按照普通下载方式设置响应头并返回整个文件。

五、实战案例演示

通过一个完整的 Spring Boot 项目实例，演示文件上传与下载功能的实际应用。包括前端页面的设计与交互（使用 HTML、JavaScript 等前端技术实现简单的文件上传和下载按钮及相关提示信息），以及后端 Spring Boot 代码的具体实现细节。展示如何将文件上传与业务逻辑相结合，例如在用户注册时上传头像，并在用户个人资料页面实现头像的下载显示；或者在一个文档管理系统中，实现文件的上传、分类存储以及用户按需下载等功能场景。

六、总结与展望

总结本文所介绍的 Spring Boot 文件上传与下载功能的实现步骤、关键要点以及注意事项。强调在实际开发过程中，安全性与稳定性是至关重要的因素，需要开发者充分考虑各种边界情况并进行合理的处理。同时，展望未来可能的扩展方向，如与云存储服务集成，实现更强大、灵活的文件管理功能，以满足日益增长的业务需求。