API返回docx附件损坏无法打开问题求助

阿华AIGC实验室

2026-5-9

解决API返回docx文件下载后损坏的问题

我帮你排查了下代码，问题主要出在文件读取的逻辑上，还有一些细节需要优化，下面一步步拆解：

核心问题：`FileInputStream.read()` 未完整读取文件

你的readFileToByteArray方法里只调用了一次fis.read(bArray)，但这个方法的返回值是实际读取到的字节数——它不一定会一次性把整个文件的字节都读到数组里（尤其是文件较大时，操作系统会分批次返回数据）。这就导致你最终得到的字节数组是不完整的，下载后的docx自然损坏无法打开。

修复方案

1. 修复文件读取方法

推荐直接用Java标准库的Files.readAllBytes()（Java 7+），它简洁且能确保完整读取文件内容：

public static byte[] readFileToByteArray(File file) throws IOException {
    return Files.readAllBytes(file.toPath());
}

如果一定要自己实现流读取逻辑，必须用循环确保读完所有字节，同时用try-with-resources自动关闭流避免泄漏：

public static byte[] readFileToByteArray(File file) throws IOException {
    try (FileInputStream fis = new FileInputStream(file);
         ByteArrayOutputStream bos = new ByteArrayOutputStream()) {
        byte[] buffer = new byte[1024];
        int bytesRead;
        // 循环读取直到文件末尾
        while ((bytesRead = fis.read(buffer)) != -1) {
            bos.write(buffer, 0, bytesRead);
        }
        return bos.toByteArray();
    }
}

2. 优化响应头与输出流处理

给文件名添加编码，避免中文/特殊字符导致的文件名乱码（即使你现在用的是output.docx，也建议养成习惯）
明确设置Content-Length，让浏览器知晓文件大小，避免下载截断
用try-with-resources管理响应输出流，确保流正确关闭

修改后的控制器方法：

@ApiOperation("get file as bytes")
@PostMapping("/get-file")
public void getFileAsbytes(HttpServletRequest request, HttpServletResponse response) throws IOException {
    byte[] fileAsBytes= documentsService.getFileAsBytes();
    
    response.setContentType("application/vnd.openxmlformats-officedocument.wordprocessingml.document");
    // 处理文件名编码，兼容不同浏览器
    String encodedFileName = URLEncoder.encode("output.docx", StandardCharsets.UTF_8.name());
    response.setHeader("Content-Disposition", 
        "attachment; filename=\"" + encodedFileName + "\"; filename*=UTF-8''" + encodedFileName);
    // 设置文件长度
    response.setContentLength(fileAsBytes.length);
    
    // 安全写入响应流
    try (ServletOutputStream out = response.getOutputStream()) {
        out.write(fileAsBytes);
        out.flush();
    }
}