前端文件下载实战：从原理到最佳实践

二、问题分析与优化方案

2.1 主要问题

1. 响应头访问问题：Cannot read properties of undefined (reading 'content-disposition')
2. 大文件内存问题：使用 ByteArrayResource 导致内存占用高
3. 文件名编码问题：中文文件名可能显示不正确
4. 错误处理不足：无法获取详细的错误信息

2.2 后端优化方案

2.2.1 流式响应改造

@PostMapping("/order-list/download")
public void downloadTaskOrderExcel(@RequestBody TaskDownLoadRequest taskDownLoadRequest, HttpServletResponse response) throws IOException {
    // 设置响应头
    String filename = "订单导出_" + LocalDateTime.now().format(DateTimeFormatter.ofPattern("yyyyMMdd_HHmmss")) + ".xlsx";
    response.setContentType("application/vnd.openxmlformats-officedocument.spreadsheetml.sheet");
    response.setHeader(HttpHeaders.CONTENT_DISPOSITION, "attachment; filename*=UTF-8''" + URLEncoder.encode(filename, "UTF-8").replace("+", "%20"));
    
    // 流式生成 Excel
    try (OutputStream out = response.getOutputStream()) {
        orderService.generateExcelToStream(queryOrders(taskDownLoadRequest.getTaskId()), out);
    }
}

2.2.2 Excel 生成优化

public void generateExcelToStream(List<CustomerOrder> orders, OutputStream out) throws IOException {
    try (Workbook workbook = new SXSSFWorkbook(100)) {
        // 使用流式 Workbook
        Sheet sheet = workbook.createSheet("订单数据");
        
        // 创建标题行
        String[] headers = {"订单 ID", "客户姓名", "运单号", /* 其他字段 */};
        Row headerRow = sheet.createRow(0);
        for (int i = 0; i < headers.length; i++) {
            headerRow.createCell(i).setCellValue(headers[i]);
        }
        
        // 填充数据
        int rowNum = 1;
        for (CustomerOrder order : orders) {
            Row row = sheet.createRow(rowNum++);
            row.createCell(0).setCellValue(order.getId());
            // 其他字段...
        }
        workbook.write(out);
    }
}

2.3 前端优化方案

2.3.1 增强的文件名解析

function getFilenameFromHeaders(headers) {
    let filename = "订单导出_" + new Date().toISOString().slice(0, 10) + ".xlsx";
    const disposition = headers['content-disposition'] || headers['Content-Disposition'];
    if (!disposition) return filename;
    
    // 支持 RFC 5987 编码
    const utf8Match = disposition.match(/filename\*=UTF-8''([^;]+)/i);
    if (utf8Match && utf8Match[1]) {
        return decodeURIComponent(utf8Match[1]);
    }
    
    // 支持普通文件名
    const filenameMatch = disposition.match(/filename="?([^"]+)"?/i);
    if (filenameMatch && filenameMatch[1]) {
        return filenameMatch[1].replace(/["']/g, '');
    }
    return filename;
}

2.3.2 完整的下载方法

const downloadFile = async (params, apiMethod, defaultFilename) => {
    try {
        const response = await apiMethod(params, {
            responseType: 'blob',
            headers: { 'Accept': 'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet' }
        });
        
        // 解析文件名
        const filename = getFilenameFromHeaders(response.headers) || defaultFilename;
        
        // 创建下载链接
        const blob = new Blob([response.data], {
            type: response.headers['content-type'] || 'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet'
        });
        
        if (window.navigator.msSaveOrOpenBlob) {
            // IE 专用方法
            window.navigator.msSaveOrOpenBlob(blob, filename);
        } else {
            const url = URL.createObjectURL(blob);
            const link = document.createElement('a');
            link.href = url;
            link.download = filename;
            link.style.display = 'none';
            document.body.appendChild(link);
            link.click();
            
            // 延迟清理
            setTimeout(() => {
                document.body.removeChild(link);
                URL.revokeObjectURL(url);
            }, 100);
        }
        return { success: true, filename };
    } catch (error) {
        // 尝试解析错误信息
        if (error.response?.data instanceof Blob) {
            try {
                const errorText = await error.response.data.text();
                const errorJson = JSON.parse(errorText);
                throw new Error(errorJson.message || '下载失败');
            } catch {
                throw new Error('文件下载失败');
            }
        }
        throw error;
    }
};

三、最佳实践总结

3.1 后端最佳实践

1. 使用流式响应：避免内存中保存完整文件

使用 SXSSFWorkbook 处理大数据：

try (Workbook workbook = new SXSSFWorkbook(100)) {
    // 只保留 100 行在内存中
}

正确设置响应头：

// 推荐使用 RFC 5987 标准
response.setHeader("Content-Disposition", "attachment; filename*=UTF-8''" + URLEncoder.encode(filename, "UTF-8"));

3.2 前端最佳实践

浏览器兼容方案：

// IE 浏览器兼容
if (window.navigator.msSaveOrOpenBlob) {
    window.navigator.msSaveOrOpenBlob(blob, filename);
} else {
    // 标准浏览器实现
}

完善的错误处理：

try {
    // 下载逻辑
} catch (error) {
    if (error.response?.status === 404) {
        showError("文件不存在");
    } else if (error.response?.status === 403) {
        showError("无下载权限");
    } else {
        showError("下载失败：" + (error.message || "未知错误"));
    }
}

正确处理 Blob 响应：

const blob = new Blob([response.data], {
    type: response.headers['content-type'] || 'application/octet-stream'
});

四、扩展思考

1. 断点续传：对于大文件可考虑 Range 请求支持
2. 进度显示：通过 axios 的 onUploadProgress 实现下载进度条
3. 安全控制：
   • 添加 CSRF Token 保护
   • 下载权限验证
4. 日志追踪：记录完整的下载日志用于审计

结语

文件下载功能看似简单，实则涉及前后端多个技术点的紧密配合。本文通过实际案例详细分析了常见问题及其解决方案，提供了经过生产验证的实现方案。希望这些经验能帮助开发者避免常见陷阱，构建更健壮的文件下载功能。