SpringBoot 如何統(tǒng)一后端返回格式？老鳥們都是這樣玩的！
大家好，我是飄渺。
今天我們來聊一聊在基于SpringBoot前后端分離開發(fā)模式下，如何友好的返回統(tǒng)一的標(biāo)準(zhǔn)格式以及如何優(yōu)雅的處理全局異常。
首先我們來看看為什么要返回統(tǒng)一的標(biāo)準(zhǔn)格式?
為什么要對SpringBoot返回統(tǒng)一的標(biāo)準(zhǔn)格式
在默認(rèn)情況下，SpringBoot的返回格式常見的有三種：
第一種：返回 String
- @GetMapping("/hello")
- public String getStr(){
- return "hello,javadaily";
- }
此時(shí)調(diào)用接口獲取到的返回值是這樣：
- hello,javadaily
第二種：返回自定義對象
- @GetMapping("/aniaml")
- public Aniaml getAniaml(){
- Aniaml aniaml = new Aniaml(1,"pig");
- return aniaml;
- }
此時(shí)調(diào)用接口獲取到的返回值是這樣：
- {
- "id": 1,
- "name": "pig"
- }
第三種：接口異常
- @GetMapping("/error")
- public int error(){
- int i = 9/0;
- return i;
- }
此時(shí)調(diào)用接口獲取到的返回值是這樣：
- {
- "timestamp": "2021-07-08T08:05:15.423+00:00",
- "status": 500,
- "error": "Internal Server Error",
- "path": "/wrong"
- }
基于以上種種情況，如果你和前端開發(fā)人員聯(lián)調(diào)接口她們就會(huì)很懵逼，由于我們沒有給他一個(gè)統(tǒng)一的格式，前端人員不知道如何處理返回值。
還有甚者，有的同學(xué)比如小張喜歡對結(jié)果進(jìn)行封裝，他使用了Result對象，小王也喜歡對結(jié)果進(jìn)行包裝，但是他卻使用的是Response對象，當(dāng)出現(xiàn)這種情況時(shí)我相信前端人員一定會(huì)抓狂的。
所以我們項(xiàng)目中是需要定義一個(gè)統(tǒng)一的標(biāo)準(zhǔn)返回格式的。
定義返回標(biāo)準(zhǔn)格式
一個(gè)標(biāo)準(zhǔn)的返回格式至少包含3部分：
- status 狀態(tài)值：由后端統(tǒng)一定義各種返回結(jié)果的狀態(tài)碼
- message 描述：本次接口調(diào)用的結(jié)果描述
- data 數(shù)據(jù)：本次返回的數(shù)據(jù)。
- {
- "status":"100",
- "message":"操作成功",
- "data":"hello,javadaily"
- }
當(dāng)然也可以按需加入其他擴(kuò)展值，比如我們就在返回對象中添加了接口調(diào)用時(shí)間
4.timestamp: 接口調(diào)用時(shí)間
定義返回對象
- @Data
- public class ResultData<T> {
- /** 結(jié)果狀態(tài) ,具體狀態(tài)碼參見ResultData.java*/
- private int status;
- private String message;
- private T data;
- private long timestamp ;
- public ResultData (){
- this.timestamp = System.currentTimeMillis();
- }
- public static <T> ResultData<T> success(T data) {
- ResultData<T> resultData = new ResultData<>();
- resultData.setStatus(ReturnCode.RC100.getCode());
- resultData.setMessage(ReturnCode.RC100.getMessage());
- resultData.setData(data);
- return resultData;
- }
- public static <T> ResultData<T> fail(int code, String message) {
- ResultData<T> resultData = new ResultData<>();
- resultData.setStatus(code);
- resultData.setMessage(message);
- return resultData;
- }
- }
定義狀態(tài)碼
- public enum ReturnCode {
- /**操作成功**/
- RC100(100,"操作成功"),
- /**操作失敗**/
- RC999(999,"操作失敗"),
- /**服務(wù)限流**/
- RC200(200,"服務(wù)開啟限流保護(hù),請稍后再試!"),
- /**服務(wù)降級**/
- RC201(201,"服務(wù)開啟降級保護(hù),請稍后再試!"),
- /**熱點(diǎn)參數(shù)限流**/
- RC202(202,"熱點(diǎn)參數(shù)限流,請稍后再試!"),
- /**系統(tǒng)規(guī)則不滿足**/
- RC203(203,"系統(tǒng)規(guī)則不滿足要求,請稍后再試!"),
- /**授權(quán)規(guī)則不通過**/
- RC204(204,"授權(quán)規(guī)則不通過,請稍后再試!"),
- /**access_denied**/
- RC403(403,"無訪問權(quán)限,請聯(lián)系管理員授予權(quán)限"),
- /**access_denied**/
- RC401(401,"匿名用戶訪問無權(quán)限資源時(shí)的異常"),
- /**服務(wù)異常**/
- RC500(500,"系統(tǒng)異常，請稍后重試"),
- INVALID_TOKEN(2001,"訪問令牌不合法"),
- ACCESS_DENIED(2003,"沒有權(quán)限訪問該資源"),
- CLIENT_AUTHENTICATION_FAILED(1001,"客戶端認(rèn)證失敗"),
- USERNAME_OR_PASSWORD_ERROR(1002,"用戶名或密碼錯(cuò)誤"),
- UNSUPPORTED_GRANT_TYPE(1003, "不支持的認(rèn)證模式");
- /**自定義狀態(tài)碼**/
- private final int code;
- /**自定義描述**/
- private final String message;
- ReturnCode(int code, String message){
- this.code = code;
- this.message = message;
- }
- public int getCode() {
- return code;
- }
- public String getMessage() {
- return message;
- }
- }
統(tǒng)一返回格式
- @GetMapping("/hello")
- public ResultData<String> getStr(){
- return ResultData.success("hello,javadaily");
- }
此時(shí)調(diào)用接口獲取到的返回值是這樣：
- {
- "status": 100,
- "message": "hello,javadaily",
- "data": null,
- "timestamp": 1625736481648,
- "httpStatus": 0
- }
這樣確實(shí)已經(jīng)實(shí)現(xiàn)了我們想要的結(jié)果，我在很多項(xiàng)目中看到的都是這種寫法，在Controller層通過ResultData.success()對返回結(jié)果進(jìn)行包裝后返回給前端。
看到這里我們不妨停下來想想，這樣做有什么弊端呢?
最大的弊端就是我們后面每寫一個(gè)接口都需要調(diào)用ResultData.success()這行代碼對結(jié)果進(jìn)行包裝，重復(fù)勞動(dòng)，浪費(fèi)體力;
而且還很容易被其他老鳥給嘲笑。
所以呢我們需要對代碼進(jìn)行優(yōu)化，目標(biāo)就是不要每個(gè)接口都手工制定ResultData返回值。
高級實(shí)現(xiàn)方式
要優(yōu)化這段代碼很簡單，我們只需要借助SpringBoot提供的ResponseBodyAdvice即可。
ResponseBodyAdvice的作用：攔截Controller方法的返回值，統(tǒng)一處理返回值/響應(yīng)體，一般用來統(tǒng)一返回格式，加解密，簽名等等。
先來看下ResponseBodyAdvice的源碼：
- public interface ResponseBodyAdvice<T> {
- /**
- * 是否支持advice功能
- * true 支持，false 不支持
- */
- boolean supports(MethodParameter var1, Class<? extends HttpMessageConverter<?>> var2);
- /**
- * 對返回的數(shù)據(jù)進(jìn)行處理
- */
- @Nullable
- T beforeBodyWrite(@Nullable T var1, MethodParameter var2, MediaType var3, Class<? extends HttpMessageConverter<?>> var4, ServerHttpRequest var5, ServerHttpResponse var6);
- }
我們只需要編寫一個(gè)具體實(shí)現(xiàn)類即可
- /**
- * @author jam
- * @date 2021/7/8 10:10 上午
- */
- @RestControllerAdvice
- public class ResponseAdvice implements ResponseBodyAdvice<Object> {
- @Autowired
- private ObjectMapper objectMapper;
- @Override
- public boolean supports(MethodParameter methodParameter, Class<? extends HttpMessageConverter<?>> aClass) {
- return true;
- }
- @SneakyThrows
- @Override
- public Object beforeBodyWrite(Object o, MethodParameter methodParameter, MediaType mediaType, Class<? extends HttpMessageConverter<?>> aClass, ServerHttpRequest serverHttpRequest, ServerHttpResponse serverHttpResponse) {
- if(o instanceof String){
- return objectMapper.writeValueAsString(ResultData.success(o));
- }
- return ResultData.success(o);
- }
- }
需要注意兩個(gè)地方：
- @RestControllerAdvice注解
@RestControllerAdvice是@RestController注解的增強(qiáng)，可以實(shí)現(xiàn)三個(gè)方面的功能：
- 全局異常處理
- 全局?jǐn)?shù)據(jù)綁定
- 全局?jǐn)?shù)據(jù)預(yù)處理
- String類型判斷
- if(o instanceof String){
- return objectMapper.writeValueAsString(ResultData.success(o));
- }
這段代碼一定要加，如果Controller直接返回String的話，SpringBoot是直接返回，故我們需要手動(dòng)轉(zhuǎn)換成json。
經(jīng)過上面的處理我們就再也不需要通過ResultData.success()來進(jìn)行轉(zhuǎn)換了，直接返回原始數(shù)據(jù)格式，SpringBoot自動(dòng)幫我們實(shí)現(xiàn)包裝類的封裝。
- @GetMapping("/hello")
- public String getStr(){
- return "hello,javadaily";
- }
此時(shí)我們調(diào)用接口返回的數(shù)據(jù)結(jié)果為：
- @GetMapping("/hello")
- public String getStr(){
- return "hello,javadaily";
- }
是不是感覺很完美，別急，還有個(gè)問題在等著你呢。
接口異常問題
此時(shí)有個(gè)問題，由于我們沒對Controller的異常進(jìn)行處理，當(dāng)我們調(diào)用的方法一旦出現(xiàn)異常，就會(huì)出現(xiàn)問題，比如下面這個(gè)接口
- @GetMapping("/wrong")
- public int error(){
- int i = 9/0;
- return i;
- }
返回的結(jié)果為：
這顯然不是我們想要的結(jié)果，接口都報(bào)錯(cuò)了還返回操作成功的響應(yīng)碼，前端看了會(huì)打人的。
別急，接下來我們進(jìn)入第二個(gè)議題，如何優(yōu)雅的處理全局異常。
SpringBoot為什么需要全局異常處理器
不用手寫try...catch，由全局異常處理器統(tǒng)一捕獲
使用全局異常處理器最大的便利就是程序員在寫代碼時(shí)不再需要手寫try...catch了，前面我們講過，默認(rèn)情況下SpringBoot出現(xiàn)異常時(shí)返回的結(jié)果是這樣：
- {
- "timestamp": "2021-07-08T08:05:15.423+00:00",
- "status": 500,
- "error": "Internal Server Error",
- "path": "/wrong"
- }
這種數(shù)據(jù)格式返回給前端，前端是看不懂的，所以這時(shí)候我們一般通過try...catch來處理異常
- @GetMapping("/wrong")
- public int error(){
- int i;
- try{
- i = 9/0;
- }catch (Exception e){
- log.error("error:{}",e);
- i = 0;
- }
- return i;
- }
我們追求的目標(biāo)肯定是不需要再手動(dòng)寫try...catch了，而是希望由全局異常處理器處理。
對于自定義異常，只能通過全局異常處理器來處理
- @GetMapping("error1")
- public void empty(){
- throw new RuntimeException("自定義異常");
- }
當(dāng)我們引入Validator參數(shù)校驗(yàn)器的時(shí)候，參數(shù)校驗(yàn)不通過會(huì)拋出異常，此時(shí)是無法用try...catch捕獲的，只能使用全局異常處理器。
SpringBoot集成參數(shù)校驗(yàn)請參考這篇文章SpringBoot開發(fā)秘籍 - 集成參數(shù)校驗(yàn)及高階技巧
如何實(shí)現(xiàn)全局異常處理器
- @Slf4j
- @RestControllerAdvice
- public class RestExceptionHandler {
- /**
- * 默認(rèn)全局異常處理。
- * @param e the e
- * @return ResultData
- */
- @ExceptionHandler(Exception.class)
- @ResponseStatus(HttpStatus.INTERNAL_SERVER_ERROR)
- public ResultData<String> exception(Exception e) {
- log.error("全局異常信息 ex={}", e.getMessage(), e);
- return ResultData.fail(ReturnCode.RC500.getCode(),e.getMessage());
- }
- }
有三個(gè)細(xì)節(jié)需要說明一下：
- @RestControllerAdvice，RestController的增強(qiáng)類，可用于實(shí)現(xiàn)全局異常處理器
- @ExceptionHandler,統(tǒng)一處理某一類異常，從而減少代碼重復(fù)率和復(fù)雜度，比如要獲取自定義異?？梢訞ExceptionHandler(BusinessException.class)
- @ResponseStatus指定客戶端收到的http狀態(tài)碼
體驗(yàn)效果
這時(shí)候我們調(diào)用如下接口：
- @GetMapping("error1")
- public void empty(){
- throw new RuntimeException("自定義異常");
- }
返回的結(jié)果如下：
- {
- "status": 500,
- "message": "自定義異常",
- "data": null,
- "timestamp": 1625795902556
- }
基本滿足我們的需求了。
但是當(dāng)我們同時(shí)啟用統(tǒng)一標(biāo)準(zhǔn)格式封裝功能ResponseAdvice和RestExceptionHandler全局異常處理器時(shí)又出現(xiàn)了新的問題：
- {
- "status": 100,
- "message": "操作成功",
- "data": {
- "status": 500,
- "message": "自定義異常",
- "data": null,
- "timestamp": 1625796167986
- },
- "timestamp": 1625796168008
- }
此時(shí)返回的結(jié)果是這樣，統(tǒng)一格式增強(qiáng)功能會(huì)給返回的異常結(jié)果再次封裝，所以接下來我們需要解決這個(gè)問題。
全局異常接入返回的標(biāo)準(zhǔn)格式
要讓全局異常接入標(biāo)準(zhǔn)格式很簡單，因?yàn)槿之惓Ｌ幚砥饕呀?jīng)幫我們封裝好了標(biāo)準(zhǔn)格式，我們只需要直接返回給客戶端即可。
- @SneakyThrows
- @Override
- public Object beforeBodyWrite(Object o, MethodParameter methodParameter, MediaType mediaType, Class<? extends HttpMessageConverter<?>> aClass, ServerHttpRequest serverHttpRequest, ServerHttpResponse serverHttpResponse) {
- if(o instanceof String){
- return objectMapper.writeValueAsString(ResultData.success(o));
- }
- if(o instanceof ResultData){
- return o;
- }
- return ResultData.success(o);
- }
關(guān)鍵代碼：
- if(o instanceof ResultData){
- return o;
- }
如果返回的結(jié)果是ResultData對象，直接返回即可。
這時(shí)候我們再調(diào)用上面的錯(cuò)誤方法，返回的結(jié)果就符合我們的要求了。
- {
- "status": 500,
- "message": "自定義異常",
- "data": null,
- "timestamp": 1625796580778
- }
好了，今天的文章就到這里了，希望通過這篇文章你能掌握如何在你項(xiàng)目中友好實(shí)現(xiàn)統(tǒng)一標(biāo)準(zhǔn)格式到返回并且可以優(yōu)雅的處理全局異常。
github地址：https://github.com/jianzh5/cloud-blog/
