SpringBoot實戰(zhàn)之實現(xiàn)結果的優(yōu)雅響應案例詳解

更新時間：2021年09月03日 11:28:38 作者：沉潛飛動

這篇文章主要介紹了SpringBoot實戰(zhàn)之實現(xiàn)結果的優(yōu)雅響應案例詳解,本篇文章通過簡要的案例,講解了該項技術的了解與使用,以下就是詳細內(nèi)容,需要的朋友可以參考下

今天說一下 Spring Boot 如何實現(xiàn)優(yōu)雅的數(shù)據(jù)響應：統(tǒng)一的結果響應格式、簡單的數(shù)據(jù)封裝。

前提

無論系統(tǒng)規(guī)模大小，大部分 Spring Boot 項目是提供 Restful + json 接口，供前端或其他服務調(diào)用，格式統(tǒng)一規(guī)范，是程序猿彼此善待彼此的象征，也是減少聯(lián)調(diào)挨罵的基本保障。

通常響應結果中需要包含業(yè)務狀態(tài)碼、響應描述、響應時間戳、響應內(nèi)容，比如：

{
"code": 200,
"desc": "查詢成功",
"timestamp": "2020-08-12 14:37:11",
"data": {
"uid": "1597242780874",
"name": "測試 1"
}
}

對于業(yè)務狀態(tài)碼分為兩個派系：一個是推薦使用 HTTP 響應碼作為接口業(yè)務返回；另一種是 HTTP 響應碼全部返回 200，在響應體中通過單獨的字段表示響應狀態(tài)。兩種方式各有優(yōu)劣，個人推薦使用第二種，因為很多 Web 服務器對 HTTP 狀態(tài)碼有攔截處理功能，而且狀態(tài)碼數(shù)量有限，不夠靈活。比如返回 200 表示接口處理成功且正常響應，現(xiàn)在需要有一個狀態(tài)碼表示接口處理成功且正常響應，但是請求數(shù)據(jù)狀態(tài)不對，可以返回 2001 表示。

自定義響應體

定義一個數(shù)據(jù)響應體是返回統(tǒng)一響應格式的第一步，無論接口正常返回，還是發(fā)生異常，返回給調(diào)用方的結構格式都應該不變。給出一個示例：

@ApiModel
@Data
public class Response<T> {
    @ApiModelProperty(value = "返回碼", example = "200")
    private Integer code;
    @ApiModelProperty(value = "返回碼描述", example = "ok")
    private String desc;
    @ApiModelProperty(value = "響應時間戳", example = "2020-08-12 14:37:11")
    private Date timestamp = new Date();
    @ApiModelProperty(value = "返回結果")
    private T data;
}

這樣，只要在 Controller 的方法返回Response就可以了，接口響應就一致了，但是這樣會形成很多格式固定的代碼模板，比如下面這種寫法：

@RequestMapping("hello1")
public Response<String> hello1() {
    final Response<String> response = new Response<>();
    response.setCode(200);
    response.setDesc("返回成功");
    response.setData("Hello, World!");
    return response;
}

調(diào)用接口響應結果為：

{
"code": 200,
"desc": "返回成功",
"timestamp": "2020-08-12 14:37:11",

"data": "Hello, World!"

}

這種重復且沒有技術含量的代碼，怎么能配得上程序猿這種優(yōu)（lan）雅（duo）的生物呢？最好能在返回響應結果的前提下，減去那些重復的代碼，比如：

@RequestMapping("hello2")
public String hello2() {
    return "Hello, World!";
}

這就需要借助 Spring 提供的ResponseBodyAdvice來實現(xiàn)了。

全局處理響應數(shù)據(jù)

先上代碼：

/**
 * <br>created at 2020/8/12
 *
 * @author www.howardliu.cn
 * @since 1.0.0
 */
@RestControllerAdvice
public class ResultResponseAdvice implements ResponseBodyAdvice<Object> {
    @Override
    public boolean supports(final MethodParameter returnType, final Class<? extends HttpMessageConverter<?>> converterType) {
        return !returnType.getGenericParameterType().equals(Response.class);// 1
    }

    @Override
    public Object beforeBodyWrite(final Object body, final MethodParameter returnType, final MediaType selectedContentType,
                                  final Class<? extends HttpMessageConverter<?>> selectedConverterType,
                                  final ServerHttpRequest request, final ServerHttpResponse response) {
        if (body == null || body instanceof Response) {
            return body;
        }
        final Response<Object> result = new Response<>();
        result.setCode(200);
        result.setDesc("查詢成功");
        result.setData(body);
        if (returnType.getGenericParameterType().equals(String.class)) {// 2
            ObjectMapper objectMapper = new ObjectMapper();
            try {
                return objectMapper.writeValueAsString(result);
            } catch (JsonProcessingException e) {
                throw new RuntimeException("將 Response 對象序列化為 json 字符串時發(fā)生異常", e);
            }
        }
        return result;
    }
}

/**
 * <br>created at 2020/8/12
 *
 * @author www.howardliu.cn
 * @since 1.0.0
 */
@RestController
public class HelloWorldController {
    @RequestMapping("hello2")
    public String hello2() {
        return "Hello, World!";
    }

    @RequestMapping("user1")
    public User user1() {
        User u = new User();
        u.setUid(System.currentTimeMillis() + "");
        u.setName("測試1");
        return u;
    }
}

上面代碼是實現(xiàn)了 Spring ResponseBodyAdvice類的模板方式，按照 Spring 的要求實現(xiàn)就行。只有兩個需要特別注意的地方，也就是代碼中標注 1 和 2 的地方。

首先說 1 這一行，也就是supports方法，這個方法是校驗是否需要調(diào)用beforeBodyWrite方法的前置判斷，返回true則執(zhí)行beforeBodyWrite方法，這里根據(jù) Controller 方法返回類型來判斷是否需要執(zhí)行beforeBodyWrite，也可以一律返回true，在后面判斷是否需要進行類型轉(zhuǎn)換。

然后重點說下 2 這一行，這行是坑，是大坑，如果對 Spring 結構不熟悉的，絕對會在這徘徊許久，不得妙法。

代碼 2 這一行是判斷Controller的方法是否返回的是String類型的結果，如果是，將返回的對象序列化之后返回。

這是因為Spring對String類型的響應類型單獨處理了，使用StringHttpMessageConverter類進行數(shù)據(jù)轉(zhuǎn)換。在處理響應結果的時候，會在方法getContentLength中計算響應體大小，其父類方法定義是protected Long getContentLength(T t, @Nullable MediaType contentType)，而StringHttpMessageConverter將方法重寫為protected Long getContentLength(String str, @Nullable MediaType contentType)，第一個參數(shù)是響應對象，固定寫死是String類型，如果我們強制返回Response對象，就會報ClassCastException。

當然，直接返回String的場景不多，這個坑可能會在某天特殊接口中突然出現(xiàn)。

補充說明

上面只是展示了ResponseBodyAdvice類最簡單的應用，我們還可以實現(xiàn)更多的擴展使用。比如：

返回請求ID：這個需要與與RequestBodyAdvice聯(lián)動，獲取到請求ID后，在響應是放在響應體中；
結果數(shù)據(jù)加密：通過ResponseBodyAdvice實現(xiàn)響應數(shù)據(jù)加密，不會侵入業(yè)務代碼，而且可以通過注解方式靈活處理接口的加密等級；
有選擇的包裝響應體：比如定義注解IgnoreResponseWrap，在不需要包裝響應體的接口上定義，然后在supports方法上判斷方法的注解即可，比如：

@Override
public boolean supports(final MethodParameter returnType, final Class<? extends HttpMessageConverter<?>> converterType) {
    final IgnoreResponseWrap[] declaredAnnotationsByType = returnType.getExecutable().getDeclaredAnnotationsByType(IgnoreResponseWrap.class);
    return !(declaredAnnotationsByType.length > 0 || returnType.getGenericParameterType().equals(Response.class));
}

很多其他玩法就不一一列舉了。