約定先後端對接數據格式

引言

輕舟採用先後端分離架構，先後端數據傳輸主要使用 json 格式。對 json 格式數據進行統一約定，將爲 HTTP 接口對接，調試帶來方便。

格式約定

清單1：返回信息格式約定源碼示例

package site.syksy.qingzhou.web.response;

import com.fasterxml.jackson.core.JsonProcessingException;
import com.fasterxml.jackson.databind.ObjectMapper;
import io.swagger.v3.oas.annotations.media.Schema;
import org.springframework.http.HttpStatus;
import org.springframework.http.ResponseEntity;

import java.io.Serializable;

/**
 * @author Raspberry
 */
@Schema(title = "返回信息")
public class ResponseMessage<T> implements Serializable {
    private static final long serialVersionUID = 1L;

    @Schema(title = "是否成功")
    private Boolean success;

    @Schema(title = "數據")
    private T data;

    @Schema(title = "錯誤碼")
    private String errorCode;

    @Schema(title = "錯誤信息")
    private String errorMessage;

    /**
     * error display type： 0 silent; 1 message.warn; 2 message.error; 4 notification; 9 page
     */
    @Schema(title = "錯誤信息顯示類型")
    private Integer showType;

    /**
     * Convenient for back-end Troubleshooting: unique request ID
     */
    @Schema(title = "惟一請求ID")
    private String traceId;

    /**
     * onvenient for backend Troubleshooting: host of current access server
     */
    @Schema(title = "當前訪問服務器的主機")
    private String host;
	
    ......省略部分代碼，詳細請到輕舟源碼中查找......
}

ResponseMessage 類中的屬性是依據 ant design pro 文檔中推薦。

統一包裝

約定好先後端交互數據格式後，咱們將在每一個 HTTP 接口方法中對返回結果進行包裝，但這樣顯得冗餘。這些重複冗餘的代碼可否集中處理呢？固然是能夠的！只需建立一個類，實現 **ResponseBodyAdvice **接口，再加上一個註解 **@RestControllerAdvice **就能實現統一對返回結果進行包裝處理，具體請看清單2中的源碼。

清單2：統一包裝返回信息源碼示例

package site.syksy.qingzhou.web.response;

import org.springframework.core.MethodParameter;
import org.springframework.http.MediaType;
import org.springframework.http.converter.HttpMessageConverter;
import org.springframework.http.server.ServerHttpRequest;
import org.springframework.http.server.ServerHttpResponse;
import org.springframework.web.bind.annotation.RestControllerAdvice;
import org.springframework.web.servlet.mvc.method.annotation.ResponseBodyAdvice;

/**
 * @author Raspberry
 */
@RestControllerAdvice
public class GeneralResponseBodyAdvice implements ResponseBodyAdvice<Object> {
    private final static String PACKAGE_PATH = "site.syksy.qingzhou";

    @Override
    public boolean supports(MethodParameter methodParameter, Class<? extends HttpMessageConverter<?>> aClass) {
        String className = methodParameter.getMethod().getDeclaringClass().getName();
        if (className.startsWith(PACKAGE_PATH)) {
            return true;
        } else {
            return false;
        }
    }

    @Override
    public Object beforeBodyWrite(Object o, MethodParameter methodParameter, MediaType mediaType, Class<? extends HttpMessageConverter<?>> aClass, ServerHttpRequest serverHttpRequest, ServerHttpResponse serverHttpResponse) {
        if (o instanceof ResponseMessage) {
            return o;
        }
        if (o instanceof String) {
            return ResponseMessage.success(o).toJSON();
        }
        return ResponseMessage.success(o);
    }
}

**GeneralResponseBodyAdvice **類中的兩個方法解釋以下：

1. supports：經過檢查 Controller 類包路徑是否匹配 site.syksy.qingzhou，返回 ture ,則會執行 beforeBodyWrite 方法。
2. beforeBodyWrite：先對 Controller 返回結果進行判斷，是否已包裝過（類型屬於 ResponseMessage ），是不是 String 類型（ String 類型，後續轉換器不會將其轉成 json）。若是以上判斷皆未經過，將對結果包裝成 ResponseMessage 格式。

清單2示例中經過包路徑來約束，也可經過其它方式來約束。不過注意，必定要約束範圍，不然如 springdoc-openapi 的接口也將包裝，則訪問 swagger ui 時將不能正確解析。

結束語

本文介紹了輕舟先後端格式的約定，以及如何實現結果統一包裝。這個方案並不是完美無瑕，其中一個問題是 springdoc-openapi 生成的 swagger 文檔中，返回結果未加上統一包裝格式。不知是否有讀者對解決這個問題感興趣，能夠給 springdoc-openapi 貢獻一個pr，爲開源世界添磚加瓦。

參考文獻

[1] Spring [EB/OL].https://spring.io/.2021-04-25 [2] Ant Design Pro [EB/OL].https://pro.ant.design/.2021-04-25

附錄

輕舟源碼地址：https://gitee.com/syksy/qingzhou

本文由博客一文多發平臺 OpenWrite 發佈！