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

前端文件下载实战：从原理到最佳实践 | 极客日志

@ApiOperation(value = "下载订单列表", notes = "根据条件导出订单数据为 Excel 文件")
@PostMapping("/order-list/download")
public Result<?> downloadTaskOrderExcel(@RequestBody TaskDownLoadRequest taskDownLoadRequest, HttpServletRequest httpRequest) {
    try {
        // 获取用户 ID 并记录日志
        Integer userId = getUserId(taskDownLoadRequest.getTaskId());
        logDownloadStart(userId, taskDownLoadRequest.getTaskId());
        
        // 查询订单数据
        List<CustomerOrder> orders = queryOrders(taskDownLoadRequest.getTaskId());
        if (orders.isEmpty()) {
            return Result.error("没有找到符合条件的订单数据");
        }
        
        // 生成 Excel 文件
        ByteArrayResource resource = generateExcel(orders);
        
        // 构建响应数据
        Map<String, Object> data = buildResponseData(resource);
        return Result.ok(data);
    } catch (Exception e) {
        log.error("下载订单列表失败", e);
        return Result.error(500, "下载订单数据失败");
    }
}

const download = async (row) => {
    const loading = ElLoading.service({ text: "正在下载..." });
    try {
        const response = await commonApi.taskOrderListDownload(
            { taskId: row.id },
            { responseType: "blob" }
        );
        
        // 文件名解析逻辑
        let filename = "订单导出.xlsx";
        const disposition = response.headers['content-disposition'];
        if (disposition) {
            const match = disposition.match(/filename="?([^"]+)"?/);
            if (match) filename = decodeURIComponent(match[1]);
        }
        
        // 创建下载链接
        const blob = new Blob([response.data], {
            type: "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet"
        });
        const link = document.createElement("a");
        link.href = window.URL.createObjectURL(blob);
        link.download = filename;
        document.body.appendChild(link);
        link.click();
        document.body.removeChild(link);
        ElMessage.success("下载成功");
    } catch (e) {
        ElMessage.error("下载失败");
    } finally {
        loading.close();
    }
};

@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);
    }
}

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);
    }
}

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;
}

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;
    }
};

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

使用 SXSSFWorkbook 处理大数据：

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

正确设置响应头：

推荐使用 RFC 5987 标准

response.setHeader("Content-Disposition", "attachment; filename*=UTF-8''" + URLEncoder.encode(filename, "UTF-8"));

浏览器兼容方案：

// 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.1 业务需求

1.2 初始后端实现

1.3 初始前端实现

二、问题分析与优化方案

2.1 主要问题

2.2 后端优化方案

2.2.1 流式响应改造

2.2.2 Excel 生成优化

2.3 前端优化方案

2.3.1 增强的文件名解析

2.3.2 完整的下载方法

三、最佳实践总结

3.1 后端最佳实践

3.2 前端最佳实践

四、扩展思考

结语

更多推荐文章

相关免费在线工具

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

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

引言

一、需求背景与初始实现

1.1 业务需求

1.2 初始后端实现

1.3 初始前端实现

二、问题分析与优化方案

2.1 主要问题

2.2 后端优化方案

2.2.1 流式响应改造

2.2.2 Excel 生成优化

2.3 前端优化方案

2.3.1 增强的文件名解析

2.3.2 完整的下载方法

三、最佳实践总结

3.1 后端最佳实践

3.2 前端最佳实践

四、扩展思考

结语

微信扫一扫，关注极客日志

更多推荐文章

相关免费在线工具