《框架封裝 · 統一異常處理和返回值包裝》

📢 大家好，我是【戰神劉玉棟】，有10多年的研發經驗，致力于前后端技術棧的知識沉淀和傳播。 💗
🌻 CSDN入駐不久，希望大家多多支持，后續會繼續提升文章質量，絕不濫竽充數，如需交流，歡迎留言評論。👍

文章目錄

- 寫在前面的話
- @RestControllerAdvice 實現異常處理
- - 基礎使用
  - 注解簡介
  - 實戰分析
- ResponseBodyAdvice 實現返回值包裝
- - 技術說明
  - 實戰分析
  - 其他方式
- 總結陳詞

寫在前面的話

此篇博文繼續介紹框架封裝過程中，關于統一異常處理和返回值包裝的具體方案，這本是一個相對常見的需求場景，此處結合實戰情況說明，各位看官可一睹為快。

技術棧：后端 SpringCloud + 前端 Vue/Nuxt

@RestControllerAdvice 實現異常處理

基礎使用

由于場景較簡單，也不構思了，可以直接實現，再來考慮內容。
由于是 SpringBoot 項目，直接使用注解@RestControllerAdvice的方式實現全局異常處理類。
先上一段示例代碼：

@RestControllerAdvice
@Slf4j
public class GlobalExceptionHandler {@ExceptionHandler(value = Throwable.class)public ResultModel jsonErrorHandler(HttpServletRequest req, Throwable e) throws Exception {log.error("請求發生異常，URL：{}，HTTP_METHOD：{}，IP：{}，錯誤信息：{}", req.getRequestURL().toString(),req.getMethod(), req.getRemoteAddr(), e.getMessage());ResultModel resultModel;//異常結果處理步驟return resultModel;}
}

注解簡介

@RestControllerAdvice是一個組合注解，由@ControllerAdvice、@ResponseBody組成，而@ControllerAdvice繼承了@Component，因此@RestControllerAdvice本質上是個Component，用于定義@ExceptionHandler，@InitBinder和@ModelAttribute方法，適用于所有使用@RequestMapping方法。
@RestControllerAdvice注解將作用在所有注解了@RequestMapping的控制器的方法上，該注解有一些屬性，可以設定具體的范圍。

Tips：上文提到的一些注解的基礎用法，網上資料很多，這邊不展開。

實戰分析

接下來談談博主所在企業是如何實現這一異常處理器的，它到底可以做，或者應該做哪些事情？
Step1、從上下文獲取鏈路ID，設置到響應頭，并設置響應狀態，代碼如下。

@ExceptionHandler(Exception.class)
public Object exceptionHandler(Exception ex) {IResult<?> result;try {String traceId = OnelinkContextHolder.getString(OnelinkConstant.TRACE_ID);// 響應頭增加鏈路IDthis.response.setHeader(OnelinkConstant.TRACE_ID, StrUtil.nullToEmpty(traceId));// 先默認設置HTTP狀態碼為500,然后根據具體異常處理再調整對應的狀態碼this.response.setStatus(HttpServletResponse.SC_INTERNAL_SERVER_ERROR);// 統一分發并處理異常result = this.handleException(ex);} catch (Exception e) {log.error("全局異常處理發生錯誤", e);result = ResultVO.failure(ex.getMessage(), ExceptionUtil.stacktraceToString(e));}// 是否開啟異常處理指南if (!this.onelinkExceptionGuideProviders.isEmpty()) {this.appendExGuide(ex, result);}return result;
}

Step2、針對框架自定義的異常攔截器接口進行遍歷，先執行前置接口，再執行后置接口，這個思想貫穿整個框架搭建過程，預留給各小組的業務開發人員，更多擴展空間（那什么，遵循開閉原則，對修改關閉，對擴展開放）。

// 異常攔截器
if (this.interceptors != null) {for (WebExceptionInterceptor interceptor : this.interceptors) {ex = interceptor.beforeHandle(ex);}
}public interface WebExceptionInterceptor {/*** 全局異常處理前邏輯*/default Exception beforeHandle(Exception ex) {return ex;}/*** 全局異常處理后邏輯*/default Exception afterHandle(Exception ex, ResultVO<Object> resultVO) {return ex;}}

3、最后就是本職工作了，針對異常的不同類型，進行不同的組裝，比如ORA-開頭的異常做出翻譯處理等，還有一些異常日志記錄、是否異常指引等功能，這里不展開了。

ResponseBodyAdvice 實現返回值包裝

技術說明

0、ResponseBodyAdvice 是 Spring Framework 的 Web 模塊中的一個接口，它允許你在將響應體寫入 HTTP 響應之前攔截和修改它。它提供了一種全局定制響應處理邏輯的方式，適用于 Spring MVC 或 Spring WebFlux 應用程序。
1、ResponseBodyAdvice 可以在注解 @ResponseBody 將返回值處理成相應格式之前操作返回值，實現這個接口即可完成相應操作，可用于對response 數據的一些統一封裝或者加密等操作。
2、ResponseBodyAdvice 接口和 RequestBodyAdvice 接口類似，RequestBodyAdvice 是請求到Controller 之前攔截，做相應的處理操作，而ResponseBodyAdvice 是對Controller返回的{@code @ResponseBody}or a {@code ResponseEntity} 后，{@code HttpMessageConverter} 類型轉換之前攔截，進行相應的處理操作后，再將結果返回給客戶端。
3、實現 ResponseBodyAdvice 接口，需要重寫其 supports 和 beforeBodyWrite 方法。
1）supports方法：判斷是否要執行beforeBodyWrite方法，true為執行，false不執行。通過該方法可以選擇哪些類或那些方法的response要進行處理，其他的不進行處理。
2）beforeBodyWrite方法：對response方法進行具體操作處理。

public interface ResponseBodyAdvice<T> {/*** 1、選擇是否執行 beforeBodyWrite 方法，返回 true 執行，false 不執行* 2、通過 supports 方法，可以選擇對哪些類或方法的 Response 進行處理* @param returnType：返回類型* @param converterType：轉換器* @return ：返回 true 則下面的 beforeBodyWrite  執行，否則不執行*/boolean supports(MethodParameter returnType, Class<? extends HttpMessageConverter<?>> converterType);/*** 對 Response 處理的具體執行方法* @param body：響應對象(response)中的響應體* @param returnType：控制器方法的返回類型* @param selectedContentType：通過內容協商選擇的內容類型* @param selectedConverterType：選擇寫入響應的轉換器類型* @param request：當前請求* @param response：當前響應* @return ：返回傳入的主體或修改過的(可能是新的)主體*/@NullableT beforeBodyWrite(@Nullable T body, MethodParameter returnType, MediaType selectedContentType, Class<? extends HttpMessageConverter<?>> selectedConverterType, ServerHttpRequest request, ServerHttpResponse response);
}

@ControllerAdvice
public class CustomResponseBodyAdvice implements ResponseBodyAdvice<Object> {@Overridepublic boolean supports(MethodParameter returnType, Class converterType) {// 根據返回類型和轉換器類型檢查是否應用此建議// 你可以在這里放置任何條件return true;}@Overridepublic Object beforeBodyWrite(Object body, MethodParameter returnType,MediaType selectedContentType,Class selectedConverterType, ServerHttpRequest request,ServerHttpResponse response) {// 在將響應體寫入輸出流之前修改它// 你可以在這里檢查或修改 'body' 對象return body;}
}

總結：ResponseBodyAdvice 接口允許在執行 @ResponseBody 或 ResponseEntity 控制器方法之后，但在使用 HttpMessageConverter 寫入響應體之前自定義響應，進行功能增強。通常用于加密，簽名，統一數據格式等。
注意：要使其生效參考框架代碼，關鍵點是@RestControllerAdvice。

實戰分析

可以用于針對返回數據進行處理，要特別注意如下點：

異常結果的處理
Feign調用結果的處理
普通數據的處理
其他數據的處理

核心思路就是設置一個返回值類，根據返回數據的類型是否為該類進行判斷處理。

public Object beforeBodyWrite(Object responseBody,@NonNull MethodParameter methodParameter,@NonNull MediaType mediaType,@NonNull Class<? extends HttpMessageConverter<?>> clazz,@NonNull ServerHttpRequest serverHttpRequest,@NonNull ServerHttpResponse serverHttpResponse) {HttpHeaders reqHeaders = serverHttpRequest.getHeaders();String disableWrapperFlag = reqHeaders.getFirst(ResultWrapper.DISABLE_WRAPPER_HEADER_KEY);String rpcClient = reqHeaders.getFirst(RpcConstant.RPC_CLIENT_HEADER_NAME);if (this.couldSkip(mediaType, disableWrapperFlag, rpcClient)) {return responseBody;}Type type = methodParameter.getExecutable().getAnnotatedReturnType().getType();String traceId = this.traceIdProvider == null ? null : this.traceIdProvider.getTraceId();Object result;// 遠程調用直接返回if (responseBody instanceof ApiResult<?>) {result = responseBody;// 為返回結果設置鏈路ID} else if (responseBody instanceof IResult) {ResultVO<?> resultVO = (ResultVO<?>) responseBody;result = StrUtil.isBlank(resultVO.getTraceId()) ? resultVO.setTraceId(traceId) : resultVO;this.setResultEnv(resultVO);// 如果返回結果是字符串,不能直接返回ResultVO,否則會與StringHttpMessageConverter沖突} else if (responseBody instanceof String || type == String.class) {ResultVO<?> resultVO = ResultVO.success(responseBody).setTraceId(traceId);result = JSON.toJSONString(resultVO, SerializerFeature.WriteMapNullValue);serverHttpResponse.getHeaders().add("content-type", ContentType.JSON.toString());// 沒有被IResult包裝,默認使用ResultVO進行包裝} else {ResultVO<Object> resultVO = ResultVO.success(responseBody).setTraceId(traceId);this.setResultEnv(resultVO);result = resultVO;}return result;
}

還可以用于鏈路追蹤返回數據Span的數據二次處理，比如返回值長度截取等，具體不展開了。

String responseTempStr = JSONObject.toJSONString(responseBody);
String truncatedResult = responseTempStr.length() > 2000 ? responseTempStr.substring(0, 2000) + "..." : responseTempStr;
span.tag(TraceSpanConstant.HTTP_RESPONSE, truncatedResult);