首页
/ 正文

springboot 下载文件（长文讲解）

更新时间: 2025-03-17 18:37:21

💡一则或许对你有用的小广告

欢迎加入小哈的星球 ，你将获得：专属的项目实战 / 1v1 提问 / Java 学习路线 / 学习打卡 / 每月赠书 / 社群讨论

新项目:《从零手撸：仿小红书（微服务架构）》 正在持续爆肝中，基于 Spring Cloud Alibaba + Spring Boot 3.x + JDK 17...，点击查看项目介绍 ;

《从零手撸：前后端分离博客项目（全栈开发）》 2 期已完结，演示链接： http://116.62.199.48/ ;

截止目前，星球内专栏累计输出 82w+ 字，讲解图 3441+ 张，还在持续爆肝中.. 后续还会上新更多项目，目标是将 Java 领域典型的项目都整一波，如秒杀系统, 在线商城, IM 即时通讯，权限管理，Spring Cloud Alibaba 微服务等等，已有 2900+ 小伙伴加入学习，欢迎点击围观

前言

在现代 Web 应用开发中，文件下载功能是用户交互的重要环节。无论是文档分发、附件获取，还是软件更新，Spring Boot 提供了简洁高效的解决方案。本文将从基础到进阶，系统讲解如何在 Spring Boot 中实现文件下载功能，涵盖核心原理、代码实践、性能优化及常见问题的解决策略。通过本文，开发者可以快速掌握 springboot 下载文件的完整技术路径，提升实际项目开发能力。

一、基础实现：从零开始构建文件下载接口

1.1 HTTP 文件下载的核心原理

文件下载本质上是通过 HTTP 协议将服务器上的文件流传输到客户端。其核心步骤包括：

客户端发起请求：通过 GET 方法向服务器发送下载请求。
服务器响应处理：
- 设置 Content-Type 头，定义文件的 MIME 类型（如 application/octet-stream 表示二进制流）。
- 设置 Content-Disposition 头，指定文件名及保存方式（如 attachment 表示强制下载）。
文件流传输：将文件内容通过响应体逐块传输给客户端。

比喻：这一过程类似于快递公司处理包裹——服务器是快递员，客户端是收件人，HTTP 头信息是快递单上的地址和备注，文件流则是包裹本身。

1.2 Spring Boot 实现步骤

步骤 1：创建 Spring Boot 项目

使用 Spring Initializr 快速生成基础项目，添加 Spring Web 依赖。

步骤 2：编写控制器代码

通过 ResponseEntity<byte[]> 返回文件流，并设置 HTTP 头信息：

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.PathVariable;
import org.springframework.web.bind.annotation.RestController;

@RestController
public class FileDownloadController {

    @GetMapping("/download/{fileName}")
    public ResponseEntity<FileSystemResource> downloadFile(@PathVariable String fileName) {
        // 1. 定义文件路径（假设文件位于项目根目录的 "uploads" 文件夹）
        String filePath = "uploads/" + fileName;
        
        // 2. 创建文件资源对象
        FileSystemResource fileResource = new FileSystemResource(filePath);
        
        // 3. 构建响应头
        HttpHeaders headers = new HttpHeaders();
        headers.add(HttpHeaders.CONTENT_DISPOSITION, "attachment; filename=" + fileName);
        
        return ResponseEntity.ok()
                .headers(headers)
                .contentType(MediaType.APPLICATION_OCTET_STREAM)
                .body(fileResource);
    }
}

步骤 3：测试接口

启动项目后，访问 http://localhost:8080/download/example.pdf，浏览器将触发文件下载对话框。

二、进阶功能：优化与扩展

2.1 大文件下载与内存优化

直接读取大文件可能导致内存溢出，可通过 分块传输编码（Chunked Transfer Encoding） 或 NIO（非阻塞IO） 优化：

方法 1：使用 `StreamingResponseBody`

逐块读取文件并写入响应流：

@GetMapping("/download-large/{fileName}")
public ResponseEntity<StreamingResponseBody> downloadLargeFile(@PathVariable String fileName) {
    // 定义文件路径
    String filePath = "uploads/" + fileName;
    
    // 创建响应体对象
    StreamingResponseBody responseBody = outputStream -> {
        try (FileInputStream fis = new FileInputStream(filePath);
             BufferedInputStream bis = new BufferedInputStream(fis)) {
            byte[] buffer = new byte[4096];
            int bytesRead;
            while ((bytesRead = bis.read(buffer)) != -1) {
                outputStream.write(buffer, 0, bytesRead);
            }
        }
    };
    
    // 设置响应头
    HttpHeaders headers = new HttpHeaders();
    headers.add(HttpHeaders.CONTENT_DISPOSITION, "attachment; filename=" + fileName);
    
    return ResponseEntity.ok()
            .headers(headers)
            .contentType(MediaType.APPLICATION_OCTET_STREAM)
            .body(responseBody);
}

关键点：通过 StreamingResponseBody，文件数据无需一次性加载到内存，适合处理 GB 级文件。

方法 2：使用 `Transfer-Encoding: chunked`

Spring Boot 默认支持此模式，只需在响应头中省略 Content-Length 即可。

2.2 断点续传与进度条支持

通过 Range 请求头实现分段下载，结合 Content-Range 响应头通知客户端下载进度：

@GetMapping("/download-resume/{fileName}")
public ResponseEntity<Resource> downloadWithResume(@PathVariable String fileName,
                                                   @RequestHeader("Range") Optional<String> rangeHeader) {
    // 1. 获取文件信息
    Path path = Paths.get("uploads/" + fileName);
    long fileSize = Files.size(path);
    
    // 2. 处理 Range 请求头
    if (rangeHeader.isPresent()) {
        String range = rangeHeader.get();
        long start = 0, end = fileSize - 1;
        if (range.startsWith("bytes=")) {
            String[] parts = range.substring(6).split("-");
            start = Long.parseLong(parts[0]);
            if (parts.length > 1) {
                end = Long.parseLong(parts[1]);
            }
        }
        
        // 3. 创建分段响应
        HttpHeaders headers = new HttpHeaders();
        headers.add(HttpHeaders.CONTENT_RANGE, "bytes " + start + "-" + end + "/" + fileSize);
        headers.add(HttpHeaders.CONTENT_LENGTH, String.valueOf(end - start + 1));
        headers.add(HttpHeaders.ACCEPT_RANGES, "bytes");
        
        return ResponseEntity.status(HttpStatus.PARTIAL_CONTENT)
                .headers(headers)
                .body(new RangeResource(path, start, end));
    }
    
    // 默认返回完整文件
    return ResponseEntity.ok()
            .contentType(MediaType.APPLICATION_OCTET_STREAM)
            .body(new FileSystemResource(path.toString()));
}

关键类：自定义 RangeResource 继承 Resource，覆盖 getInputStream() 方法实现分段读取。

2.3 自定义文件名与编码处理

若文件名含中文或特殊字符，需使用 URLEncoder 编码，避免浏览器解析错误：

String encodedFileName = URLEncoder.encode(fileName, StandardCharsets.UTF_8).replace("+", "%20");
headers.add(HttpHeaders.CONTENT_DISPOSITION, "attachment; filename=\"" + encodedFileName + "\"");

三、常见问题与解决方案

3.1 权限控制：防止文件被随意下载

通过 Spring Security 实现访问权限校验，例如：

@Configuration
@EnableWebSecurity
public class SecurityConfig extends WebSecurityConfigurerAdapter {
    @Override
    protected void configure(HttpSecurity http) throws Exception {
        http.authorizeRequests()
            .antMatchers("/download/**").authenticated()  // 仅允许认证用户访问
            .anyRequest().permitAll();
    }
}

3.2 异常处理：文件不存在或读取失败

在控制器中捕获 FileNotFoundException，返回友好提示：

@ExceptionHandler(FileNotFoundException.class)
public ResponseEntity<String> handleFileNotFound(FileNotFoundException e) {
    return ResponseEntity.status(HttpStatus.NOT_FOUND)
            .body("File not found: " + e.getMessage());
}

3.3 性能优化：缓存与压缩

设置 Cache-Control 头减少重复下载，并启用 GZIP 压缩：

// 在响应头中添加
headers.add(HttpHeaders.CACHE_CONTROL, "max-age=3600");
// 启用 Spring Boot 的 GZIP 配置（application.properties）
spring.http.encoding.force=true
spring.http.encoding.charset=UTF-8
spring.http.encoding.enabled=true

四、结论

本文系统讲解了 springboot 下载文件的实现方法，从基础接口到大文件优化、断点续传等进阶功能，再到权限与性能优化，覆盖了开发者可能遇到的典型场景。通过代码示例与原理分析，读者可以快速构建健壮的文件下载模块。建议在实际项目中结合具体需求（如文件存储位置、用户权限体系）进一步调整代码，以提升系统安全性与用户体验。

下一步行动：尝试将本文中的代码整合到自己的 Spring Boot 项目中，并测试断点续传功能，或添加日志记录以监控下载流量。通过实践，逐步掌握 springboot 下载文件的完整技术栈。

springboot 下载文件（长文讲解）

前言

一、基础实现：从零开始构建文件下载接口

1.1 HTTP 文件下载的核心原理

1.2 Spring Boot 实现步骤

步骤 1：创建 Spring Boot 项目

步骤 2：编写控制器代码

步骤 3：测试接口

二、进阶功能：优化与扩展

2.1 大文件下载与内存优化

方法 1：使用 `StreamingResponseBody`

方法 2：使用 `Transfer-Encoding: chunked`

2.2 断点续传与进度条支持

2.3 自定义文件名与编码处理

三、常见问题与解决方案

3.1 权限控制：防止文件被随意下载

3.2 异常处理：文件不存在或读取失败

3.3 性能优化：缓存与压缩

四、结论

最新发布

Vue3 app.mixin() 函数（超详细）

Vue3 app.provide() 函数（建议收藏）

Vue3 app.runWithContext() 函数（建议收藏）

Vue3 app.version 属性（一文讲透）

Vue3 app.config 属性（手把手讲解）

Vue3 app.config.errorHandler 属性（保姆级教程）

Vue3 app.config.warnHandler 属性（长文讲解）

Vue3 app.config.performance 属性（超详细）

Vue3 app.config.compilerOptions 属性（千字长文）

Vue3 app.config.globalProperties 属性（保姆级教程）

springboot 下载文件（长文讲解）

前言

一、基础实现：从零开始构建文件下载接口

1.1 HTTP 文件下载的核心原理

1.2 Spring Boot 实现步骤

步骤 1：创建 Spring Boot 项目

步骤 2：编写控制器代码

步骤 3：测试接口

二、进阶功能：优化与扩展

2.1 大文件下载与内存优化

方法 1：使用 StreamingResponseBody

方法 2：使用 Transfer-Encoding: chunked

2.2 断点续传与进度条支持

2.3 自定义文件名与编码处理

三、常见问题与解决方案

3.1 权限控制：防止文件被随意下载

3.2 异常处理：文件不存在或读取失败

3.3 性能优化：缓存与压缩

四、结论

最新发布

Vue3 app.mixin() 函数（超详细）

Vue3 app.provide() 函数（建议收藏）

Vue3 app.runWithContext() 函数（建议收藏）

Vue3 app.version 属性（一文讲透）

Vue3 app.config 属性（手把手讲解）

Vue3 app.config.errorHandler 属性（保姆级教程）

Vue3 app.config.warnHandler 属性（长文讲解）

Vue3 app.config.performance 属性（超详细）

Vue3 app.config.compilerOptions 属性（千字长文）

Vue3 app.config.globalProperties 属性（保姆级教程）

方法 1：使用 `StreamingResponseBody`

方法 2：使用 `Transfer-Encoding: chunked`