Spring Boot阻塞Web Client如何返回含Body与状态码的ResponseEntity

ResponseEntity是Spring HTTP模块原生提供的封装类，本身就支持同时绑定HTTP状态码、响应头、泛型指定的自定义响应体，不需要自行实现封装逻辑，以下是可直接运行的实现步骤：

• 第一步：定义自定义响应体类
  按照你的业务字段定义普通Java类即可，框架会自动完成JSON/表单等格式的反序列化：

  public class CustomBizResponse {
      private String bizCode;
      private String bizMsg;
      private Object bizData;
  
      // 补全无参构造、全参构造、所有字段的getter/setter即可，Java 16+可直接用record类简化定义
  }
  

• 第二步：初始化阻塞式Web客户端，配置不拦截错误状态码
  初学者最容易踩的坑：Spring默认的阻塞式客户端（RestClient/RestTemplate）在遇到4xx、5xx状态码时会直接抛出HTTP异常，不会把响应封装到ResponseEntity里，需要先配置全局状态处理器放行所有状态码：

  import org.springframework.web.client.RestClient;
  
  // 客户端实例一般注册为Spring单例Bean使用即可
  RestClient restClient = RestClient.builder()
          // 放行所有HTTP状态码，不抛出异常，全部流转到后续响应处理逻辑
          .defaultStatusHandler(httpStatusCode -> true, (req, res) -> {})
          .build();
  

• 第三步：发起请求时直接指定泛型接收ResponseEntity
  调用接口时不要直接获取响应体，使用toEntity方法指定自定义响应体类型，框架会自动完成状态码绑定、响应体反序列化：

  import org.springframework.http.ResponseEntity;
  
  ResponseEntity<CustomBizResponse> responseEntity = restClient.get()
          .uri("你的业务接口地址")
          .retrieve()
          // 指定自定义类类型，框架会自动把响应体反序列化为CustomBizResponse实例
          .toEntity(CustomBizResponse.class);
  

• 第四步：业务层读取状态码和响应体，覆盖成功/失败全场景
  拿到ResponseEntity实例后，不管是2xx成功还是4xx/5xx失败场景，都可以直接读取对应内容：

  import org.springframework.http.HttpStatusCode;
  
  // 获取HTTP状态码
  HttpStatusCode httpStatus = responseEntity.getStatusCode();
  // 判断是否为2xx成功请求
  boolean requestSuccess = httpStatus.is2xxSuccessful();
  // 获取自定义类型响应体，失败场景下只要接口返回结构匹配CustomBizResponse定义，也能正常读取
  CustomBizResponse bizResponseBody = responseEntity.getBody();
  

• 手动构造ResponseEntity的方法
  如果你需要在业务逻辑里自行组装ResponseEntity返回给上层调用，直接用提供的静态方法构造即可：

  import org.springframework.http.HttpStatus;
  
  // 构造200成功响应
  ResponseEntity<CustomBizResponse> successResult = ResponseEntity
          .status(HttpStatus.OK)
          .body(new CustomBizResponse("0", "请求成功", yourBizData));
  
  // 构造400参数错误的失败响应
  ResponseEntity<CustomBizResponse> failResult = ResponseEntity
          .status(HttpStatus.BAD_REQUEST)
          .body(new CustomBizResponse("PARAM_001", "请求参数缺失", null));
  

补充说明：如果是老项目使用RestTemplate作为阻塞式客户端，逻辑完全一致，配置错误处理器时使用setErrorHandler方法放行所有状态码，调用时用exchange方法指定ParameterizedTypeReference或直接传自定义类class接收ResponseEntity即可。

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