1. 程式人生 > >每天用SpringBoot,還不懂RESTful API返回統一資料格式是怎麼實現的?

每天用SpringBoot,還不懂RESTful API返回統一資料格式是怎麼實現的?

關於 Spring 的全域性處理,我有兩方面要說:

  1. 統一資料返回格式
  2. 統一異常處理
    為了將兩個問題說明清楚,將分兩個章節分別說明,本章主要說第一點

有童鞋說,我們專案都做了這種處理,就是在每個 API 都單獨工具類將返回值進行封裝,但這種不夠優雅;我想寫最少的程式碼完成這件事,也許有童鞋說,加幾個註解就解決問題了,說的沒錯,但這篇文章主要是為了說明為什麼加了幾個註解就解決問題了,目的是希望大家知其所以然。

為了更好的說明問題,本文先說明如何實現,然後再詳細剖析實現原理(這很關鍵)

為什麼要做統一資料返回格式

前後端分離是當今服務形式的主流,如何設計一個好的 RESTful API ,以及如何讓前端小夥伴可以處理標準的 response JSON 資料結構都至關重要,為了讓前端有更好的邏輯展示與頁面互動處理,每一次 RESTful 請求都應該包含以下幾個資訊:

名稱 描述
status 狀態碼,標識請求成功與否,如 [1:成功;-1:失敗]
errorCode 錯誤碼,給出明確錯誤碼,更好的應對業務異常;請求成功該值可為空
errorMsg 錯誤訊息,與錯誤碼相對應,更具體的描述異常資訊
resultBody 返回結果,通常是 Bean 物件對應的 JSON 資料, 通常為了應對不同返回值型別,將其宣告為泛型型別

實現

通用返回值類定義

根據上面的描述,用 Java Bean 來體現這個結構就是這樣:

@Data
public final class CommonResult<T> {

    private int status = 1;

    private String errorCode = "";

    private String errorMsg = "";

    private T resultBody;

    public CommonResult() {
    }

    public CommonResult(T resultBody) {
        this.resultBody = resultBody;
    }
}

配置

沒錯,我們需要藉助幾個關鍵註解來完成一下相關配置:

@EnableWebMvc
@Configuration
public class UnifiedReturnConfig {

    @RestControllerAdvice("com.example.unifiedreturn.api")
    static class CommonResultResponseAdvice implements ResponseBodyAdvice<Object>{
        @Override
        public boolean supports(MethodParameter methodParameter, Class<? extends HttpMessageConverter<?>> aClass) {
            return true;
        }

        @Override
        public Object beforeBodyWrite(Object body, MethodParameter methodParameter, MediaType mediaType, Class<? extends HttpMessageConverter<?>> aClass, ServerHttpRequest serverHttpRequest, ServerHttpResponse serverHttpResponse) {
            if (body instanceof CommonResult){
                return body;
            }

            return new CommonResult<Object>(body);
        }
    }
}

到這裡就結束了,我們就可以縱情的寫任何 RESTful API 了,所有的返回值都會有統一的 JSON 結構

測試

新建 UserController,新增相應的 RESTful API,測試用例寫的比較簡單,只為了說明返回值的處理

@RestController
@RequestMapping("/users")
public class UserController {


    @GetMapping("")
    public List<UserVo> getUserList(){
        List<UserVo> userVoList = Lists.newArrayListWithCapacity(2);
        userVoList.add(UserVo.builder().id(1L).name("日拱一兵").age(18).build());
        userVoList.add(UserVo.builder().id(2L).name("tan").age(19).build());
        return userVoList;
    }
}

開啟瀏覽器輸入地址測試: http://localhost:8080/users/ ,我們可以看到返回了 List JSON 資料

繼續新增 RESTful API,根據使用者 ID 查詢使用者資訊

@GetMapping("/{id}")
public UserVo getUserByName(@PathVariable Long id){
    return UserVo.builder().id(1L).name("日拱一兵").age(18).build();
}

開啟瀏覽器輸入地址測試: http://localhost:8080/users/1 ,我們可以看到返回了單個 User JSON 資料

新增一個返回值型別為 ResponseEntity 的 API

@GetMapping("/testResponseEntity")
public ResponseEntity getUserByAge(){
    return new ResponseEntity(UserVo.builder().id(1L).name("日拱一兵").age(18).build(), HttpStatus.OK);
}

開啟瀏覽器輸入地址測試: http://localhost:8080/users/testResponseEntity ,我們可以看到同樣返回了單個 User JSON 資料

解剖實現過程

我會將關鍵部分一一說明清楚,斷案還需小夥伴自己去案發現場(開啟自己的 IDE 檢視)

故事要從 @EnableWebMvc 這個註解說起,開啟該註解看:

@Retention(RetentionPolicy.RUNTIME)
@Target(ElementType.TYPE)
@Documented
@Import(DelegatingWebMvcConfiguration.class)
public @interface EnableWebMvc {
}

通過 @Import 註解引入了 DelegatingWebMvcConfiguration.class,那來看這個類吧:

@Configuration
public class DelegatingWebMvcConfiguration extends WebMvcConfigurationSupport {
    ...
}

@Configuration 註解,你應該很熟悉了,該類的父類 WebMvcConfigurationSupport 中卻隱藏著一段關鍵程式碼:

@Bean
public RequestMappingHandlerAdapter requestMappingHandlerAdapter() {
    RequestMappingHandlerAdapter adapter = createRequestMappingHandlerAdapter();
    ...
    return adapter;
}

RequestMappingHandlerAdapter 是每一次請求處理的關鍵,來看該類的定義:

public class RequestMappingHandlerAdapter extends AbstractHandlerMethodAdapter
        implements BeanFactoryAware, InitializingBean {
    ...
}

該類實現了 InitializingBean 介面,我在 Spring Bean 生命週期之“我從哪裡來”? 這篇文章中明確說明了 Spring Bean 初始化的幾個關鍵,其中 InitializingBean 介面的
afterPropertiesSet 方法就是關鍵之一,在 RequestMappingHandlerAdapter 類中同樣重寫了該方法:

@Override
public void afterPropertiesSet() {
    // Do this first, it may add ResponseBody advice beans
    initControllerAdviceCache();

    if (this.argumentResolvers == null) {
        List<HandlerMethodArgumentResolver> resolvers = getDefaultArgumentResolvers();
        this.argumentResolvers = new HandlerMethodArgumentResolverComposite().addResolvers(resolvers);
    }
    if (this.initBinderArgumentResolvers == null) {
        List<HandlerMethodArgumentResolver> resolvers = getDefaultInitBinderArgumentResolvers();
        this.initBinderArgumentResolvers = new HandlerMethodArgumentResolverComposite().addResolvers(resolvers);
    }
    if (this.returnValueHandlers == null) {
        List<HandlerMethodReturnValueHandler> handlers = getDefaultReturnValueHandlers();
        this.returnValueHandlers = new HandlerMethodReturnValueHandlerComposite().addHandlers(handlers);
    }
}

該方法內容都非常關鍵,但我們先來看 initControllerAdviceCache 方法,其他內容後續再單獨說明:

private void initControllerAdviceCache() {
        ...
    if (logger.isInfoEnabled()) {
        logger.info("Looking for @ControllerAdvice: " + getApplicationContext());
    }

    List<ControllerAdviceBean> beans = ControllerAdviceBean.findAnnotatedBeans(getApplicationContext());
    AnnotationAwareOrderComparator.sort(beans);

    List<Object> requestResponseBodyAdviceBeans = new ArrayList<Object>();

    for (ControllerAdviceBean bean : beans) {
        ...
        if (ResponseBodyAdvice.class.isAssignableFrom(bean.getBeanType())) {
            requestResponseBodyAdviceBeans.add(bean);
        }
    }
}

通過 ControllerAdviceBean 靜態方法掃描 ControllerAdvice 註解,可是我們在實現上使用的是 @RestControllerAdvice 註解,開啟看該註解:

@Target(ElementType.TYPE)
@Retention(RetentionPolicy.RUNTIME)
@Documented
@ControllerAdvice
@ResponseBody
public @interface RestControllerAdvice {

該註解由 @ControllerAdvice@ResponseBody 標記,就好比你熟悉的 @RestController 註解由 @Controller@ResponseBody 標記是一樣的

到這裡你已經知道我們用 @RestControllerAdvice 標記的 Bean 是如何被載入到 Spring 上下文的,接下來就要知道是 Spring 是如何使用我們的 bean 以及對返回 body 做處理的

其實在 HttpMessageConverter是如何轉換資料的? 這篇文章中已經說明了一部分,希望小夥伴先看這篇文章,下面的部分就會秒懂了,我們在這裡做進一步的說明

在 AbstractMessageConverterMethodProcessor 的 writeWithMessageConverters 方法中,有一段核心程式碼:

if (messageConverter instanceof GenericHttpMessageConverter) {
    if (((GenericHttpMessageConverter) messageConverter).canWrite(
            declaredType, valueType, selectedMediaType)) {
        outputValue = (T) getAdvice().beforeBodyWrite(outputValue, returnType, selectedMediaType,
                (Class<? extends HttpMessageConverter<?>>) messageConverter.getClass(),
                inputMessage, outputMessage);
            ...
        return;
    }
}

可以看到通過 getAdvice() 呼叫了 beforeBodyWrite 方法,我們已經接近真相了

protected RequestResponseBodyAdviceChain getAdvice() {
    return this.advice;
}

RequestResponseBodyAdviceChain,看名字帶有 Chain,很明顯用到了「責任鏈設計模式」,這些內容在 不得不知的責任鏈設計模式 文章中明確說明過,只不過它傳遞責任鏈以迴圈的方式完成:

class RequestResponseBodyAdviceChain implements RequestBodyAdvice, ResponseBodyAdvice<Object> {

    @Override
    public Object beforeBodyWrite(Object body, MethodParameter returnType, MediaType contentType,
            Class<? extends HttpMessageConverter<?>> converterType,
            ServerHttpRequest request, ServerHttpResponse response) {

        return processBody(body, returnType, contentType, converterType, request, response);
    }

    @SuppressWarnings("unchecked")
    private <T> Object processBody(Object body, MethodParameter returnType, MediaType contentType,
            Class<? extends HttpMessageConverter<?>> converterType,
            ServerHttpRequest request, ServerHttpResponse response) {

        for (ResponseBodyAdvice<?> advice : getMatchingAdvice(returnType, ResponseBodyAdvice.class)) {
            if (advice.supports(returnType, converterType)) {
                body = ((ResponseBodyAdvice<T>) advice).beforeBodyWrite((T) body, returnType,
                        contentType, converterType, request, response);
            }
        }
        return body;
    }
}

我們重寫的 beforeBodyWrite 方法終究會被呼叫到,真相就是這樣了!!!

其實還沒完,你有沒有想過,如果我們的 API 方法返回值是 org.springframework.http.ResponseEntity<T> 型別,我們可以指定 HTTP 返回狀態碼,但是這個返回值會直接放到我們的 beforeBodyWrite 方法的 body 引數中嗎?如果這樣做很明顯是錯誤的,因為 ResponseEntity 包含很多我們非業務資料在裡面,那 Spring 是怎麼幫我們處理的呢?

在我們方法取得返回值並且在呼叫 beforeBodyWrite 方法之前,還要選擇 HandlerMethodReturnValueHandler 用於處理不同的 Handler 來處理返回值

在類 HandlerMethodReturnValueHandlerComposite 中的 handleReturnValue 方法中

@Override
public void handleReturnValue(Object returnValue, MethodParameter returnType,
        ModelAndViewContainer mavContainer, NativeWebRequest webRequest) throws Exception {

    HandlerMethodReturnValueHandler handler = selectHandler(returnValue, returnType);
    if (handler == null) {
        throw new IllegalArgumentException("Unknown return value type: " + returnType.getParameterType().getName());
    }
    handler.handleReturnValue(returnValue, returnType, mavContainer, webRequest);
}

通過呼叫 selectHandler 方法來選擇合適的 handler,Spring 內建了很多個 Handler,我們來看類圖:

HttpEntityMethodProcessor 就是其中之一,它重寫了 supportsParameter 方法,支援 HttpEntity 型別,即支援 ResponseEntity 型別:

@Override
public boolean supportsParameter(MethodParameter parameter) {
    return (HttpEntity.class == parameter.getParameterType() ||
            RequestEntity.class == parameter.getParameterType());
}

所以當我們返回的型別為 ResponseEntity 時,就要通過 HttpEntityMethodProcessor 的 handleReturnValue 方法來處理我們的結果:

@Override
public void handleReturnValue(Object returnValue, MethodParameter returnType,
        ModelAndViewContainer mavContainer, NativeWebRequest webRequest) throws Exception {

    ...
    if (responseEntity instanceof ResponseEntity) {
        int returnStatus = ((ResponseEntity<?>) responseEntity).getStatusCodeValue();
        outputMessage.getServletResponse().setStatus(returnStatus);
        if (returnStatus == 200) {
            if (SAFE_METHODS.contains(inputMessage.getMethod())
                    && isResourceNotModified(inputMessage, outputMessage)) {
                // Ensure headers are flushed, no body should be written.
                outputMessage.flush();
                // Skip call to converters, as they may update the body.
                return;
            }
        }
    }

    // Try even with null body. ResponseBodyAdvice could get involved.
    writeWithMessageConverters(responseEntity.getBody(), returnType, inputMessage, outputMessage);

    // Ensure headers are flushed even if no body was written.
    outputMessage.flush();
}

該方法提取出 responseEntity.getBody(),並傳遞個 MessageConverter,然後再繼續呼叫 beforeBodyWrite 方法,這才是真相!!!

這是 RESTful API 正常返回內容的情況,下一篇文章,讓我們來偵查一下統一異常情況的處理以及實現原理

靈魂追問

  1. 返回值是非 ResponseEntity 型別時,用的是什麼 handler?它支援的返回值型別是什麼?看過你也許就知道為什麼要用 @ResponseBody 註解了
  2. 你有追蹤過 DispatchServlet 的整個請求過程嗎?

提高效率工具


推薦閱讀

  • 只會用 git pull ?有時候你可以嘗試更優雅的處理方式
  • 雙親委派模型:大廠高頻面試題,輕鬆搞定
  • 面試還不知道BeanFactory和ApplicationContext的區別?
  • 如何設計好的RESTful API
  • 程式猿為什麼要看原始碼?

歡迎持續關注公眾號:「日拱一兵」

  • 前沿 Java 技術乾貨分享
  • 高效工具彙總 | 回覆「工具」
  • 面試問題分析與解答
  • 技術資料領取 | 回覆「資料」

以讀偵探小說思維輕鬆趣味學習 Java 技術棧相關知識,本著將複雜問題簡單化,抽象問題具體化和圖形化原則逐步分解技術問題,技術持續更新,請持續關注......

相關推薦

每天SpringBootRESTful API返回統一資料格式是怎麼實現的?

關於 Spring 的全域性處理,我有兩方面要說: 統一資料返回格式 統一異常處理 為了將兩個問題說明清楚,將分兩個章節分別說明,本章主要說第一點 有童鞋說,我們專案都做了這種處理,就是在每個 API 都單獨工具類將返回值進行封裝,但這種不夠優雅;我想寫最少的程式碼完成這件事,也許有童鞋說,加幾個註解就解

Restful介面返回統一資料格式

一、定義返回的資料格式: public class ResponseMessage<T> {     private int code;     private boolean state;     private T data;     private St

mybatis中config檔案載入mapper檔案的4中方式(自己勿怪)

<!-- 最簡單的引用方式,直接引入xml檔案 --> <mappers> <!-- 最簡單的引用方式,直接引入xml檔案 --> <mapper resource="config/TSysUserMapper.xml"/> <

看完這篇分析分散式事務請給我差評

0 題記 又或者在網上購物明明已經扣款,但是卻告訴我沒有發生交易。這一系列情況都是因為沒有事務導致的。這說明了事務在生活中的一些重要性。 有了事務,你去小賣鋪買東西,那就是一手交錢一手交貨。有了事務,你去網上購物,扣款即產生訂單交易。 1 事務的具體定義 事務

天天SpringBoot居然知道它的自動裝配的原理?

### 引言 最近有個讀者在面試,面試中被問到了這樣一個問題“看你專案中用到了`springboot`,你說下`springboot`的自動配置是怎麼實現的?”這應該是一個`springboot`裡面最最常見的一個面試題了。下面我們就來帶著這個問題一起解剖下`springBoot`的自動配置原理吧。 ###

Restful API返回統一響應體

參考文件: https://github.com/kuitos/kuitos.github.io/issues/9 對於客戶端開發或者網站開發而言,呼叫介面返回有統一的響應體,可以針對性的設計介面,程式碼結構更加清晰,層次也更加分明。 所以需要呼叫api時,要求

最實用的雲端數據保障措施60%的戶居然知道!

雲計 安全 雲計算 快速 賠償 備份 7月 用戶數 還需 7月的騰訊雲丟失用戶數據被要求賠償我的事假鬧得沸沸揚揚。在雲端,總會有意外發生,這個是不可控的,雲商既然是雲服務提供商便有義務最大限度上保障用戶在雲端的數據安全;但同時用戶也該對自己的數據進行雲端容災備份,然而很多用

如果看了此文你傅裏葉變換那就過來掐死我吧【完整版】

處理 為知 自然 pic 是不是 wikipedia sina 學習方法 依次 如果看了此文你還不懂傅裏葉變換,那就過來掐死我吧【完整版】 轉自 https://blog.csdn.net/u012361418/article/details/46277779 還記得上

Linux下百度雲盤怎麼操作簡單限速最後竟然能看閱後即瞎全集

說好的要下載資料集進行論文復現的,所以沒有百度雲盤怎麼能行。 我們今天的目的就是在Linux下弄好百度雲盤,然後下載我雲盤裡的閱後即瞎視訊。 首先開啟新增元件。 然後找網盤助手安裝。 之後網頁雲盤會變成這個樣。 匯出下載選文字。 回到終端安裝這個。 sudo apt install ar

[work] 如果看了此文你傅立葉變換那就過來掐死我吧【完整版】

我保證這篇文章和你以前看過的所有文章都不同,這是 2012 年還在果殼的時候寫的,但是當時沒有來得及寫完就出國了……於是拖了兩年,嗯,我是拖延症患者…… 這篇文章的核心思想就是: 要讓讀者在不看任何數學公式的情況下理解傅立葉分析。 傅立葉分析不僅僅是一個數學工具,更是一種可以徹底顛覆一個

Java經典題丨猴子吃桃問題:猴子第一天摘下若干個桃子當即吃了一半,還不又多吃了一個 第二天早上又將剩下的桃子吃掉一半又多吃了一個以後每天早上都吃了前一天剩下 的一半零一個。

習題:猴子吃桃問題:猴子第一天摘下若干個桃子,當即吃了一半,還不癮,又多吃了一個 第二天早上又將剩下的桃子吃掉一半,又多吃了一個,以後每天早上都吃了前一天剩下 的一半零一個。到第10天早上想再吃時,見只剩下一個桃子了。求第一天共摘了多少。 題意解析:從第一天到第十天的桃子的減少公式是n/

如果看了此文 Word2Vec那是我太笨

轉自http://www.sohu.com/a/128794834_211120   自從 Google 的 Tomas Mikolov 在《Efficient Estimation of Word Representation in Vector Space》提出 Word2Ve

股票跌得猝不及防是因為你這個技術!

今日是國慶長假後的第一個交易日,A股迎來當頭一棒,盤中超百點的下跌令市場猝不及防,在權重股大跌,題材股重挫之下,市場連續跌破多條均線支撐,吞噬節前一週的反彈。全天看,這裡的下跌屬於通殺,但市場反彈趨勢並未就此打破。 股民泣不成聲,那麼怎麼利用Python來分析資料,從而減少風險呢,大家一起來學習

如果看了此文你傅立葉變換那就過來掐死我吧【完整版】

原文出處: 韓昊    1 2 3 4 5 6 7 8 9 10 作 者:韓 昊 知 乎:Heinrich 微 博:@花生油工人 知乎專欄:

ACNO.15猴子吃桃問題。猴子第一天摘下若干個桃子當即吃了一半,還不過癮又多吃了一個。 第二天早上又將剩下的桃子吃掉一半又多吃一個。以後每天早上都吃了前一天剩下的一半零一個。 到第N天早上想再

題目描述 猴子吃桃問題。猴子第一天摘下若干個桃子,當即吃了一半,還不過癮,又多吃了一個。 第二天早上又將剩下的桃子吃掉一半,又多吃一個。 以後每天早上都吃了前一天剩下的一半零一個。 到第N天早上想再吃時,見只剩下一個桃子了。求第一天共摘多少桃子。 輸入 N 輸

如果看了此文你傅立葉變換那就過來掐死我吧【完整版教程】

傅立葉分析是訊號處理的核心內容,我一直沒有徹底理解,看到這篇教程覺得講得非常精彩,何況還是學長寫的,所以轉載此文。 作 者:韓 昊 知 乎:Heinrich 微 博:@花生油工人 知乎專欄:與時間無關的故事 謹以此文獻給大連海事大學的吳楠老師,柳曉鳴老師,王新年老師以及

如果看了這篇文章你傅立葉變換那就過來掐死我吧~~

本文轉載至https://zhuanlan.zhihu.com/p/19763358,原創作者韓昊,轉載宣告:謹以此文獻給大連海事大學的吳楠老師,柳曉鳴老師,王新年老師以及張晶泊老師。     我保證這篇文章和你以前看過的所有文章都不同,這是 2012 年還在果殼的時候

2012 天津 1002 Number (出自 ftiasch)

#include <cmath> #include <cstdio> #include <cstring> #include <iostream> #i

看完這篇別說你Hinton大神的膠囊網路capsule network

倒計時 2 天 來源 | 王的機器(公眾號ID:MeanMachine1031) 作者 | 王聖元 0 引言 斯蒂文認為機器學習有時候像嬰兒學習,特別是在物體識別上。比如嬰兒首先學會識別邊界和顏色,然後將這些資訊用於識別形狀和圖形等更復雜的實體。比如在人臉識別上