为何部分REST API会在响应体中额外返回状态码？

这种设计是工业界非常普遍的工程实践，核心是弥补HTTP原生状态码的局限性，主要有以下几方面原因：

• 兼容特殊运行环境的限制
  部分老旧客户端、内网代理、防火墙或者低版本运行环境会过滤、篡改甚至直接拦截非2xx系列的HTTP响应，部分场景下开发者甚至没有权限读取HTTP响应的状态码，响应体内的状态码可以保证业务状态标识不受中间层干扰，客户端总能拿到准确的业务执行结果。
• 承载更细粒度的业务状态
  HTTP原生状态码总数不足百个，完全无法覆盖复杂的业务错误场景。比如同样返回400 Bad Request，背后可能是参数缺失、参数格式非法、签名校验失败、权限不足等数十种完全不同的业务原因。自定义的业务状态码可以和具体错误场景一一对应，开发者不需要额外解析错误文本就能快速定位问题，前端也可以直接基于业务状态码做差异化的交互处理，比如40101代表登录态过期跳登录页，40102代表权限不足跳无权限页，逻辑实现更可靠。
• 简化请求层的统一封装
  大部分团队都会封装统一的HTTP请求工具，约定所有接口返回固定结构：
  { "code": xxx, "msg": "xxx", "data": {} }
  工具层不需要额外读取HTTP响应头的状态码，只需要解析响应体的code字段就能完成统一的错误拦截、提示、日志上报等逻辑，大幅降低了封装的复杂度，也避免了不同HTTP客户端库读取状态码的API差异带来的兼容问题。
• 排查调试更便捷
  接口调试过程中，开发者不需要切换标签页查看响应头信息，只看响应体就能一次性拿到业务状态、错误描述、返回数据全部内容，在很多默认只展示响应体的调试工具里效率提升非常明显。
• 规避中间层的异常干扰
  部分CDN、缓存服务或者网关会对非2xx的响应做默认缓存，甚至直接返回自己的错误页面，这时候客户端拿到的HTTP状态码和服务端实际返回的可能不一致。响应体的状态码可以作为校验依据，一旦发现两者不匹配就能快速定位是中间链路出了问题。

当然这种设计也需要注意约定优先级，常规做法是HTTP状态码代表传输层状态，响应体code代表业务层状态，两者各司其职，避免出现状态冲突的歧义问题。

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