解决Spring中Excel下载接口报No converter for XXX with application/octet-stream错误

问题原因 #

接口设置了Content-Type: application/octet-stream用于返回文件流，但处理完流之后，代码又试图返回封装的ResultBean对象。Spring找不到能把ResultBean转换成二进制流格式的转换器，因此抛出HttpMessageNotWritableException。

解决步骤 #

• 排查接口返回逻辑：确保文件流输出完成后，不要返回任何其他对象，直接结束请求
• 核对响应头配置：保证Content-Type与实际返回内容匹配，文件流对应application/octet-stream
• 梳理接口设计：避免同一接口同时返回文件流和JSON格式的封装对象

是否需要配置特定转换器？ #

不需要。这个问题本质是响应类型不匹配，强行配置转换器把ResultBean转成二进制流不符合业务逻辑，反而会导致前端收到无效内容。

可行方案与示例代码 #

方案1：直接通过HttpServletResponse输出流（最直接） #

Controller方法返回值设为void，直接操作响应对象写入文件流，写完后刷新缓冲区结束请求，不返回任何对象。

@GetMapping("/download/excel")
public void downloadExcel(HttpServletResponse response) throws IOException {
    // 生成Excel工作簿
    XSSFWorkbook workbook = createExcelWorkbook();
    
    try {
        // 设置下载响应头
        response.setContentType("application/octet-stream");
        response.setHeader("Content-Disposition", "attachment; filename=\"data.xlsx\"");
        
        // 写入文件流到响应
        workbook.write(response.getOutputStream());
        // 强制刷新缓冲区，结束请求
        response.flushBuffer();
    } finally {
        // 关闭资源
        workbook.close();
    }
}

// 模拟生成Excel的工具方法
private XSSFWorkbook createExcelWorkbook() {
    XSSFWorkbook workbook = new XSSFWorkbook();
    XSSFSheet sheet = workbook.createSheet("业务数据");
    XSSFRow headerRow = sheet.createRow(0);
    headerRow.createCell(0).setCellValue("序号");
    headerRow.createCell(1).setCellValue("名称");
    return workbook;
}

方案2：使用ResponseEntity封装返回 #

利用Spring提供的ResponseEntity和Resource接口，自动处理响应头和流的关闭，代码更简洁规范。

@GetMapping("/download/excel")
public ResponseEntity<Resource> downloadExcel() throws IOException {
    XSSFWorkbook workbook = createExcelWorkbook();
    ByteArrayOutputStream baos = new ByteArrayOutputStream();
    workbook.write(baos);
    
    // 将字节流转为Spring的Resource对象
    ByteArrayResource resource = new ByteArrayResource(baos.toByteArray());
    
    // 构建响应头
    HttpHeaders headers = new HttpHeaders();
    headers.setContentType(MediaType.APPLICATION_OCTET_STREAM);
    headers.setContentDisposition(ContentDisposition.attachment()
            .filename("data.xlsx", StandardCharsets.UTF_8)
            .build());
    
    // 关闭资源
    workbook.close();
    baos.close();
    
    return new ResponseEntity<>(resource, headers, HttpStatus.OK);
}

方案3：异常场景单独返回ResultBean #

如果需要在下载失败时返回ResultBean格式的错误信息，可通过全局异常处理器统一处理异常，正常流程仍返回文件流。

// 全局异常处理器
@RestControllerAdvice
public class DownloadExceptionHandler {
    @ExceptionHandler(Exception.class)
    public ResponseEntity<ResultBean> handleDownloadError(Exception e) {
        ResultBean errorResult = new ResultBean(false, "下载失败：" + e.getMessage());
        return new ResponseEntity<>(errorResult, HttpStatus.INTERNAL_SERVER_ERROR);
    }
}

// 接口方法使用方案1的void返回逻辑，异常时会自动触发处理器返回ResultBean

内容的提问来源于stack exchange，提问作者Alf