Spring Boot 学习编写上传下载接口

一、项目基础配置

1. 核心配置文件（application.properties）

文件上传下载的核心配置集中在src/main/resources/application.properties，主要包含以下关键配置：

1
2
3
4
5
6
7
8
9
10
11
# 文件存储目录（相对路径，会在项目根目录下创建）
file.upload.dir=uploads

# 自定义上传 配置（自定义，需在代码中读取）
file.upload.max-size=10485760  # 单个文件最大限制（10MB，10*1024*1024）

# Spring 内置 multipart 配置（必须配置，控制文件上传行为）
spring.servlet.multipart.enabled=true  # 启用文件上传
spring.servlet.multipart.max-file-size=10MB  # 单个文件最大大小（与自定义配置保持一致）
spring.servlet.multipart.max-request-size=50MB  # 单次请求总文件大小限制
spring.servlet.multipart.file-size-threshold=2KB  # 超过此大小的文件会写入磁盘（否则暂存内存）

二、文件上传接口实现（POST /api/file/upload）

1. 接口功能

接收前端上传的单个或多个文件，保存到file.upload.dir配置的目录，并返回上传结果（如文件名、存储路径等）。

2. 核心技术点

  • 使用org.springframework.web.multipart.MultipartFile接收上传文件
  • 生成唯一文件名（避免文件名冲突）
  • 确保存储目录存在（若不存在则创建）
  • 校验文件大小、文件非空等

3. 代码实现思路

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
@RestController
@RequestMapping("/api/file")
public class FileController {

    // 从配置文件读取上传目录
    @Value("${file.upload.dir}")
    private String uploadDir;

    // 从配置文件读取单个文件最大限制
    @Value("${file.upload.max-size}")
    private long maxFileSize;

    @PostMapping("/upload")
    public ResponseEntity<Map<String, Object>> uploadFile(@RequestParam("files") MultipartFile[] files) {
        Map<String, Object> result = new HashMap<>();
        List<String> uploadedFiles = new ArrayList<>();

        // 1. 校验上传目录是否存在，不存在则创建
        File dir = new File(uploadDir);
        if (!dir.exists()) {
            dir.mkdirs(); // 递归创建目录
        }

        // 2. 处理每个上传的文件
        for (MultipartFile file : files) {
            // 校验文件非空
            if (file.isEmpty()) {
                result.put("success", false);
                result.put("message", "文件不能为空");
                return ResponseEntity.badRequest().body(result);
            }

            // 校验文件大小
            if (file.getSize() > maxFileSize) {
                result.put("success", false);
                result.put("message", "文件大小超过限制（最大10MB）");
                return ResponseEntity.badRequest().body(result);
            }

            try {
                // 3. 生成唯一文件名（UUID + 原文件后缀）
                String originalFilename = file.getOriginalFilename();
                String fileExt = originalFilename.substring(originalFilename.lastIndexOf("."));
                String uniqueFileName = UUID.randomUUID().toString() + fileExt;

                // 4. 保存文件到目录
                File dest = new File(dir, uniqueFileName);
                file.transferTo(dest); // 将上传文件写入目标路径

                uploadedFiles.add(uniqueFileName); // 记录成功上传的文件名
            } catch (IOException e) {
                result.put("success", false);
                result.put("message", "文件上传失败：" + e.getMessage());
                return ResponseEntity.status(500).body(result);
            }
        }

        // 5. 返回成功结果
        result.put("success", true);
        result.put("message", "文件上传成功");
        result.put("files", uploadedFiles);
        return ResponseEntity.ok(result);
    }
}

三、文件下载接口实现（GET /api/file/download/{fileName}）

1. 接口功能

根据文件名从存储目录读取文件，以附件形式返回给前端，触发浏览器下载。

2. 核心技术点

  • 通过文件名定位服务器上的文件
  • 设置响应头（Content-Type、Content-Disposition）控制下载行为
  • 以流的形式返回文件内容

3. 代码实现思路

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
@GetMapping("/download/{fileName}")
public ResponseEntity<Resource> downloadFile(@PathVariable String fileName) {
    // 1. 构建文件路径
    File file = new File(uploadDir + File.separator + fileName);
    if (!file.exists()) {
        return ResponseEntity.notFound().build(); // 文件不存在返回404
    }

    // 2. 创建文件资源对象
    Resource resource = new FileSystemResource(file);

    // 3. 推断文件MIME类型（用于Content-Type）
    String contentType = null;
    try {
        contentType = Files.probeContentType(file.toPath());
    } catch (IOException ex) {
        // 推断失败时使用默认类型
        contentType = "application/octet-stream";
    }

    // 4. 设置响应头，指定为附件（触发下载）
    return ResponseEntity.ok()
            .contentType(MediaType.parseMediaType(contentType))
            .header(HttpHeaders.CONTENT_DISPOSITION, 
                    "attachment; filename=\"" + resource.getFilename() + "\"")
            .body(resource);
}

四、文件预览接口（GET /api/file/preview/{fileName}）

1. 接口功能

针对图片等可预览文件，直接在浏览器中显示（而非下载）。

2. 核心区别

与下载接口的主要差异在于Content-Disposition头：预览时不设置attachment，浏览器会根据Content-Type自动渲染。

3. 代码实现思路

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
@GetMapping("/preview/{fileName}")
public ResponseEntity<Resource> previewFile(@PathVariable String fileName) {
    File file = new File(uploadDir + File.separator + fileName);
    if (!file.exists()) {
        return ResponseEntity.notFound().build();
    }

    Resource resource = new FileSystemResource(file);
    String contentType = null;
    try {
        contentType = Files.probeContentType(file.toPath());
    } catch (IOException ex) {
        contentType = "application/octet-stream";
    }

    // 关键：不设置attachment，浏览器会尝试预览
    return ResponseEntity.ok()
            .contentType(MediaType.parseMediaType(contentType))
            .header(HttpHeaders.CONTENT_DISPOSITION, 
                    "filename=\"" + resource.getFilename() + "\"")
            .body(resource);
}

五、关键注意事项

  1. 文件命名安全
    必须使用唯一文件名（如UUID），避免使用原始文件名（可能包含特殊字符或导致覆盖）。
  2. 目录权限
    确保file.upload.dir目录有读写权限，否则会出现Permission denied异常。
  3. 异常处理
    • 捕获MaxUploadSizeExceededException（文件大小超限）
    • 处理文件不存在、IO异常等场景，返回友好提示
  4. 前端配合
    上传时表单需设置enctype="multipart/form-data"，支持多文件上传时input标签添加multiple属性。

六、总结

通过上述配置和代码，可实现基础的文件上传、下载、预览功能。核心在于：

  • 正确配置Spring的multipart参数
  • 安全处理文件存储（唯一命名、目录创建）
  • 合理设置响应头控制文件传输行为（下载/预览）

项目地址： https://github.com/zero201913/springboot-file-upload-test