手动写入响应后对 @ResponseBody 注解的影响-工具盒子

问题回溯 {#问题回溯}

2023 年 Q2 某日运营反馈一个问题，商品系统商家中心某批量工具模板无法下载，导致功能无法使用（因为模板是动态变化的）

商家中心报错如下（JSON串）：

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

负责的同事看到失败后立即与我展开讨论（因为不是关键业务，所以不需要回滚，修复即可），我们发现新功能模板下载的代码与之前的代码有所不同，恰好之前的功能又可以正常运行，所以同事对现有代码进行改造然后预发布测试完成后再次上线。

其他业务代码：

/**
 * 模板下载
 */
@RequestMapping("/doBatchWareSetAd")
public void doBatchWareSetAd(@RequestParam MultipartFile file, HttpServletResponse response) {
  wareBatchBusiness.doBatchWareSetAd(file, response, getLongOrgCode(), getCurrentUserPin(), getCurrentUserId());
}

上线的结果是：仍然无法使用。

其实也正常：因为两种代码在预发布都可以正常运行，在线上出错只可能是因为其他原因，只不过我们不了解底层原理，害怕它 "可能" 有问题罢了，最终查询得到的结论是权限系统管理员在线上环境没有给我们配置相应的文件，导致请求为空，导致请求失败。

探索 @ResponseBody 与主动写入响应流的关系 {#探索-responsebody-与主动写入响应流的关系}

我们都知道 @ResponseBody 注解可以帮助我们把返回对象转化为 JSON，方便展示和交互。

那它到底是如何工作的呢，请看下面的讲解：

代码案例 1 {#代码案例-1}


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

// 响应 JSON报文

Debug 代码，发现其核心处理类为：RequestResponseBodyMethodProcessor。

方法：org.springframework.web.servlet.mvc.method.annotation.RequestResponseBodyMethodProcessor#handleReturnValue 会处理其相关返回值。

真正的核心处理方法：org.springframework.web.servlet.mvc.method.annotation.AbstractMessageConverterMethodProcessor#writeWithMessageConverters。

关键 DEBUG 记录如下图所示：

Debug RequestResponseBodyMethodProcessor

后续内容可以想象，肯定还有地方去把流按照指定的 HEADER 写入，因为和本文无关所以不深究。

代码案例 2 {#代码案例-2}


@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;
}

// 响应提示下载文件

关键 DEBUG 源码截图：

ResponseBody DEBUG

可以发现 Spring 对这种方式操作文件流视作异常情况，然后抛出，在后续逻辑中完成整个请求，简单来说就是 @ResponseBody 注解没起到任何作用。

因此答案呼之欲出：当时功能不可用的罪魁祸首就是相关人员没有配置参数导致，与写法没有任何关系。

结论与启发 {#结论与启发}

结论 {#结论}

我们要相信自己的代码，至少是要相信已经经过测试的代码。
在委托他人或者自己配置环境参数，如权限、ZK等每次都保证预发布和线上同时配置，避免遗漏的情况。

启发 {#启发}

聊了这么多，那我们这种类似场景的代码应该怎么写？

既然主动写入流会解除 @ResponseBody 的作用，反之又能发挥它的作用，那我们最佳方案是不是如下所示？


@RequestMapping("/test1")
@ResponseBody
public Map<String, String> test1(HttpServletResponse response) {
    Map<String, String> map = new HashMap();
    if (获取不到文件配置 == true) {
        return map.put("msg", "获取不到文件配置");
    }
    
    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;
}

如此一来，当发生预期之外的情况，我们有非常明显的报错提示，当正常时又可以完美实现功能，妙哉（我觉得）~

Ref：https://mp.weixin.qq.com/s/gZtibHGEEHDQ1Pf0wGoNcA