Vue3 + Spring Boot 文件下载异常错误友好提示处理

ErrorFileResponseUtils.java

确保错误响应包含正确的 Content-Type 和字符集。

public static ResponseEntity<Result<Object>> createJsonErrorResponse(String message, HttpStatus status) {
    Result<Object> result = Result.error(message);
    return ResponseEntity
            .status(status)
            .contentType(MediaType.APPLICATION_JSON)
            .body(result);
}

public static boolean isFileDownloadRequest(HttpServletRequest request) {
    String path = request.getRequestURI();
    if (path.contains("/export") || path.contains("/download")) {
        return true;
    }
    String acceptHeader = request.getHeader(HttpHeaders.ACCEPT);
    return acceptHeader != null && acceptHeader.contains(MediaType.APPLICATION_OCTET_STREAM_VALUE);
}

2. 前端优化：Axios 拦截器

修改 Axios 响应拦截器，在捕获 blob 错误时尝试解析内容。优先解析 JSON，若失败则提取文本内容。

src/utils/request.ts

import axios from "axios";
import { ElMessage } from "element-plus";

const instance = axios.create({ baseURL: "/api" });

instance.interceptors.response.use(
    async (response) => {
        // 正常逻辑...
        return response.data;
    },
    async (error) => {
        // 401 未授权
        if (error.response?.status === 401) {
            router.push("/login");
            return Promise.reject(error);
        }

        // 处理文件下载的错误响应
        if (
            error.config?.responseType === "blob" &&
            error.response?.data instanceof Blob &&
            error.response?.data.size < 1024
        ) {
            try {
                const errorText = await error.response.data.text();
                try {
                    const errorJson = JSON.parse(errorText);
                    const message = errorJson.message || errorJson.msg || "文件下载失败";
                    ElMessage.error(message);
                } catch {
                    // 非 JSON 格式，尝试提取核心错误信息
                    let message = errorText;
                    const match = errorText.match(/^\[.*?\]\s*(.*)/);
                    if (match && match[1]) {
                        message = match[1];
                    }
                    ElMessage.error(message || "文件下载失败");
                }
            } catch {
                ElMessage.error("文件下载失败");
            }
            return Promise.reject(error);
        }

        // 普通错误响应
        const errorData = error.response?.data || {};
        ElMessage.error(errorData.msg || errorData.message || "服务异常！");
        return Promise.reject(error);
    }
);

export default instance;

3. 控制器代码调整

移除 Controller 中的 try-catch，直接抛出异常由全局处理器处理。

CapitalInfoController.java

@PostMapping("/export-data-by-template")
public ResponseEntity<Resource> exportDataByTemplate(@RequestBody @Valid CapitalInfoQueryDTO queryDTO) throws IOException {
    String filePath = capitalInfoService.exportFileByTemplate(queryDTO);
    Path path = Paths.get(filePath);
    Resource resource = new UrlResource(path.toUri());

    if (!resource.exists()) {
        throw new ResourceNotFoundException("资源文件不存在");
    }

    return ResponseEntity.ok()
            .contentType(MediaType.APPLICATION_OCTET_STREAM)
            .header("Content-Disposition", "attachment;filename=" + URLEncoder.encode(FileUtils.getFileName(filePath), StandardCharsets.UTF_8))
            .body(resource);
}

总结

通过统一后端异常响应格式并增强前端对 Blob 错误内容的解析能力，实现了文件下载场景下业务异常的精准提示，同时解决了中文乱码问题。