Spring Boot 文件上传和下载指南：从基础到进阶

IT_陈寒

发布于 2025-06-01 05:09:08

31800

代码可运行

文章被收录于专栏：开发经验开发经验

运行总次数：0

代码可运行

引言

在现代Web应用程序中，文件上传和下载是非常常见的功能。无论是用户上传头像、上传文档还是下载报告，都需要一个高效、安全的文件处理系统。Spring Boot 作为一个流行的Java框架，为开发者提供了简便的方式来实现这些功能。在这篇文章中，我们将探讨如何在Spring Boot应用中实现文件的上传和下载，并包含详细的代码解析和技术分析。

1. 环境配置

在开始编码之前，我们需要配置Spring Boot项目。假设你已经创建了一个Spring Boot项目，以下是需要添加的依赖项：

<dependencies>
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-web</artifactId>
    </dependency>
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-thymeleaf</artifactId>
    </dependency>
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-data-jpa</artifactId>
    </dependency>
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-validation</artifactId>
    </dependency>
</dependencies>

2. 文件上传

2.1 配置文件上传路径

首先，我们需要配置文件上传的存储路径。在application.properties中添加以下配置：

file.upload-dir=uploads

2.2 创建上传服务

创建一个服务类来处理文件的存储逻辑。我们将使用Spring的MultipartFile接口来处理上传的文件。

import org.springframework.beans.factory.annotation.Value;
import org.springframework.stereotype.Service;
import org.springframework.web.multipart.MultipartFile;

import java.io.IOException;
import java.nio.file.Files;
import java.nio.file.Path;
import java.nio.file.Paths;
import java.util.UUID;

@Service
public class FileStorageService {

    @Value("${file.upload-dir}")
    private String uploadDir;

    public String storeFile(MultipartFile file) throws IOException {
        // 生成唯一文件名
        String fileName = UUID.randomUUID().toString() + "_" + file.getOriginalFilename();
        Path targetLocation = Paths.get(uploadDir).resolve(fileName);

        // 创建目录
        Files.createDirectories(targetLocation.getParent());

        // 保存文件
        Files.copy(file.getInputStream(), targetLocation);

        return fileName;
    }
}

2.3 创建上传控制器

接下来，创建一个控制器来处理文件上传请求。

import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.http.HttpStatus;
import org.springframework.http.ResponseEntity;
import org.springframework.web.bind.annotation.*;
import org.springframework.web.multipart.MultipartFile;

@RestController
@RequestMapping("/api/files")
public class FileUploadController {

    @Autowired
    private FileStorageService fileStorageService;

    @PostMapping("/upload")
    public ResponseEntity<String> uploadFile(@RequestParam("file") MultipartFile file) {
        try {
            String fileName = fileStorageService.storeFile(file);
            return ResponseEntity.ok("文件上传成功: " + fileName);
        } catch (IOException e) {
            return ResponseEntity.status(HttpStatus.INTERNAL_SERVER_ERROR).body("文件上传失败: " + e.getMessage());
        }
    }
}

3. 文件下载

3.1 创建下载服务

同样地，我们需要创建一个服务类来处理文件的下载逻辑。

import org.springframework.beans.factory.annotation.Value;
import org.springframework.core.io.Resource;
import org.springframework.core.io.UrlResource;
import org.springframework.stereotype.Service;

import java.io.IOException;
import java.nio.file.Path;
import java.nio.file.Paths;

@Service
public class FileDownloadService {

    @Value("${file.upload-dir}")
    private String uploadDir;

    public Resource loadFileAsResource(String fileName) throws IOException {
        Path filePath = Paths.get(uploadDir).resolve(fileName).normalize();
        Resource resource = new UrlResource(filePath.toUri());

        if (resource.exists() || resource.isReadable()) {
            return resource;
        } else {
            throw new IOException("文件未找到或不可读: " + fileName);
        }
    }
}

3.2 创建下载控制器

然后，创建一个控制器来处理文件下载请求。

import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.core.io.Resource;
import org.springframework.http.HttpHeaders;
import org.springframework.http.ResponseEntity;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.PathVariable;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;

@RestController
@RequestMapping("/api/files")
public class FileDownloadController {

    @Autowired
    private FileDownloadService fileDownloadService;

    @GetMapping("/download/{fileName:.+}")
    public ResponseEntity<Resource> downloadFile(@PathVariable String fileName) {
        try {
            Resource resource = fileDownloadService.loadFileAsResource(fileName);

            return ResponseEntity.ok()
                    .header(HttpHeaders.CONTENT_DISPOSITION, "attachment; filename=\"" + resource.getFilename() + "\"")
                    .body(resource);
        } catch (IOException e) {
            return ResponseEntity.status(HttpStatus.INTERNAL_SERVER_ERROR).body(null);
        }
    }
}

4. 前端页面

为了更好地展示文件上传和下载功能，我们可以使用Thymeleaf来创建一个简单的前端页面。

4.1 文件上传页面

<!DOCTYPE html>
<html xmlns:th="http://www.thymeleaf.org">
<head>
    <title>文件上传</title>
</head>
<body>
    <h1>文件上传</h1>
    <form method="POST" enctype="multipart/form-data" action="/api/files/upload">
        <input type="file" name="file" />
        <button type="submit">上传</button>
    </form>
</body>
</html>

4.2 文件下载页面

<!DOCTYPE html>
<html xmlns:th="http://www.thymeleaf.org">
<head>
    <title>文件下载</title>
</head>
<body>
    <h1>文件下载</h1>
    <form method="GET" action="/api/files/download/{fileName}">
        <input type="text" name="fileName" placeholder="文件名" />
        <button type="submit">下载</button>
    </form>
</body>
</html>