Why @ResponseBody Fails When Writing Directly to the Output Stream in Spring

In Q2 2023 a merchant‑center batch tool could not download its template, returning the JSON error

{"code":-1,"msg":"失败"}

. Investigation revealed two versions of the download code; both worked in pre‑release but failed online because the permission system had not configured the required file, resulting in an empty request.

Exploring @ResponseBody and Direct Stream Writing

The @ResponseBody annotation converts returned objects to JSON. The core processor is

RequestResponseBodyMethodProcessor

, which delegates to

AbstractMessageConverterMethodProcessor#writeWithMessageConverters

.

When a method also writes directly to the response output stream, Spring treats this as an exceptional case and the @ResponseBody effect is bypassed.

Code Example 1 – Simple @ResponseBody

<code>@RequestMapping("/test1")
@ResponseBody
public Map<String, String> test1(HttpServletResponse response) {
    Map<String, String> map = new HashMap<>();
    map.put("1", "1");
    return map;
}
// Returns JSON response</code>

Code Example 2 – Writing a File Stream

<code>@RequestMapping("/test2")
@ResponseBody
public Map<String, String> test2(HttpServletResponse response) throws IOException {
    Map<String, String> map = new HashMap<>();
    map.put("1", "1");
    response.setContentType("application/vnd.ms-excel");
    response.setHeader("Content-Disposition", String.format("attachment; filename=%s_%s.xls", "Demo", System.currentTimeMillis()));
    OutputStream out = response.getOutputStream();
    out.flush();
    out.close();
    return map;
}
// Triggers file download; @ResponseBody has no effect</code>

Debug screenshots (shown below) confirm that Spring treats the stream‑write path as an exception, so the JSON conversion does not occur.

Conclusion and Insights

Trust code that has passed testing; the failure was due to missing environment configuration, not the implementation.

Ensure that permissions, Zookeeper nodes, and other parameters are consistently set in both pre‑release and production environments to avoid omissions.

Suggested Best‑Practice Implementation

<code>@RequestMapping("/test1")
@ResponseBody
public Map<String, String> test1(HttpServletResponse response) {
    Map<String, String> map = new HashMap<>();
    if (fileConfigMissing) {
        map.put("msg", "Missing file configuration");
        return map;
    }
    response.setContentType("application/vnd.ms-excel");
    response.setHeader("Content-Disposition", String.format("attachment; filename=%s_%s.xls", "Demo", System.currentTimeMillis()));
    OutputStream out = response.getOutputStream();
    out.flush();
    out.close();
    return map;
}
</code>

This approach provides clear error messages when configuration is absent while still supporting normal file‑download functionality.