SpringBoot实现高效文件下载功能的方法与实践

在Spring Boot项目中实现文件下载功能是常见的需求，但开发者常遇到文件名乱码、文件损坏、跨域限制等问题。本文将针对这些高频问题提供解决方案，并结合性能优化和实际场景分析，帮助开发者构建稳定高效的文件下载功能。

一、文件名乱码问题及处理

当文件名包含中文或特殊字符时，浏览器可能无法正确解析，导致下载后的文件名显示为乱码。解决方案：

1. 编码转换：使用`URLEncoder.encode`对文件名进行UTF-8编码。

java

String fileName = URLEncoder.encode("模板.xlsx", "UTF-8");

response.setHeader("Content-Disposition", "attachment;filename=" + fileName);

2. 兼容Swagger测试：在Swagger中需额外处理，避免直接使用`new String`转换，需统一采用`URLEncoder`。

二、文件损坏或内容异常

下载后的文件无法打开或提示修复，通常由以下原因导致：

1. 流读写错误：

java

// 错误写法：导致多写入空字节

outputStream.write(buff, 0, buff.length);

// 正确写法：根据实际读取长度写入

outputStream.write(buff, 0, readLength);

2. 资源路径问题：当项目打包为JAR时，直接通过`File`读取资源会失败。应使用类加载器获取流：

java

InputStream inputStream = getClass.getClassLoader.getResourceAsStream("template/file.xlsx");

三、跨域（CORS）与响应头限制

若前端报错`Refused to get unsafe header "Content-Disposition"`，需配置：

1. 启用跨域注解：在Controller添加`@CrossOrigin`，允许跨域请求。

2. 暴露响应头：显式设置`Access-Control-Expose-Headers`，使前端能读取自定义Header：

java

response.setHeader("Access-Control-Expose-Headers", "Content-Disposition");

四、大文件下载优化方案

处理大文件时需避免内存溢出和连接超时，推荐以下方法：

1. 分片下载与断点续传：

java

String rangeHeader = request.getHeader("Range");

// 解析rangeHeader并返回对应字节流

response.setStatus(HttpStatus.PARTIAL_CONTENT.value);

response.setHeader("Content-Range", "bytes " + start + "-" + end + "/" + total);

2. Nginx反向代理：将文件托管至Nginx，通过`X-Accel-Redirect`实现高效静态文件传输，减少应用服务器压力。

3. 下载限速：通过控制流读取速度平衡带宽，如限制每秒100KB：

java

int bytesPerSecond = 1024 100;

while ((bytesRead = in.read(buffer)) != -1) {

out.write(buffer, 0, bytesRead);

// 计算已传输数据，通过Thread.sleep控制速率

五、其他常见问题排查

1. 前端调用方式错误：