使用FeignClient调用含HttpServletResponse参数的端点时抛异常的咨询

定义如下Spring MVC端点：

@GetMapping("/{id}")
public HttpServletResponse downloadFile(@PathVariable String id, HttpServletResponse response) throws IOException {
    // some logic
}

直接调用该端点时表现正常，但通过FeignClient调用时会抛出以下异常：

异常1：

org.springframework.http.converter.HttpMessageNotWritableException: Could not write JSON: getOutputStream() has already been called for this response; nested exception is com.fasterxml.jackson.databind.JsonMappingException

异常2：

feign.codec.EncodeException: Error converting request body

即使端点内无业务逻辑仍会报错，经排查发现是HttpServletResponse请求参数导致该问题。请问是否有官方文档说明HttpServletResponse不应作为端点的参数？

官方文档的明确指引 #

Spring官方文档在Spring MVC控制器方法的参数与返回值设计部分，明确不推荐直接使用Servlet API对象（如HttpServletResponse、HttpServletRequest）作为控制器方法的参数或返回值，建议优先使用Spring提供的抽象化组件（如ResponseEntity、StreamingResponseBody、Resource等）来处理响应输出。

问题根源 #

1. 流冲突问题：当控制器方法接收HttpServletResponse参数时，相当于直接接管了响应输出流的控制权。而Feign客户端在调用时，会默认尝试将方法的返回值（此处为HttpServletResponse）序列化为JSON格式，这会导致重复操作响应流，触发getOutputStream() has already been called的异常。
2. 上下文不兼容：HttpServletResponse是绑定当前Servlet请求上下文的容器级对象，Feign作为跨服务的远程调用客户端，无法将该对象序列化或传递到远程服务，因此会抛出EncodeException。

修正方案 #

将控制器方法改为使用Spring推荐的响应处理方式，示例如下：

方式1：返回ResponseEntity<Resource> #

@GetMapping("/{id}")
public ResponseEntity<Resource> downloadFile(@PathVariable String id) throws IOException {
    // 根据id获取文件资源，示例为FileSystemResource
    Resource fileResource = new FileSystemResource("/path/to/target/file");
    
    return ResponseEntity.ok()
            .header(HttpHeaders.CONTENT_DISPOSITION, "attachment; filename=\"" + fileResource.getFilename() + "\"")
            .body(fileResource);
}

方式2：使用StreamingResponseBody处理大文件 #

@GetMapping("/{id}")
public ResponseEntity<StreamingResponseBody> downloadFile(@PathVariable String id) {
    StreamingResponseBody responseBody = outputStream -> {
        // 此处实现文件内容写入outputStream的逻辑
        // 例如：Files.copy(Paths.get("/path/to/file"), outputStream);
    };

    return ResponseEntity.ok()
            .header(HttpHeaders.CONTENT_DISPOSITION, "attachment; filename=\"downloaded-file.txt\"")
            .body(responseBody);
}

采用上述方式后，Spring会统一管理响应流的生命周期，Feign客户端也能正确处理响应内容，避免异常发生。

内容的提问来源于stack exchange，提问作者Mohamed Ennahdi El Idrissi