目录
[二、Spring Boot 文件上传基础](#二、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 "上传文件为空，请选择文件后再次上传。";
}
// 检查文件大小是否超过 5MB
if (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 Content
return 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 文件上传与下载功能的实现步骤、关键要点以及注意事项。强调在实际开发过程中，安全性与稳定性是至关重要的因素，需要开发者充分考虑各种边界情况并进行合理的处理。同时，展望未来可能的扩展方向，如与云存储服务集成，实现更强大、灵活的文件管理功能，以满足日益增长的业务需求。