統一返回數據格式

一、統一返回數據格式

項目中我們會將響應封裝成json返回，一般我們會將所有接口的數據格式統一， 使前端(iOS Android, Web)對數據的操作更一致、輕松。

一般情況下，統一返回數據格式沒有固定的格式，只要能描述清楚返回的數據狀態以及要返回的具體數據就可以。但是一般會包含狀態碼、返回消息、數據這幾部分內容

例如，我們的系統要求返回的基本數據格式如下：

列表：

{
  "success": true,
  "code": 20000,
  "message": "成功",
  "data": {
    "items": [
      {
        "id": "1",
        "name": "劉德華",
        "intro": "畢業於師范大學數學系，熱愛教育事業，執教數學思維6年有余"
      }
    ]
  }
}

分頁：

{
  "success": true,
  "code": 20000,
  "message": "成功",
  "data": {
    "total": 17,
    "rows": [
      {
        "id": "1",
        "name": "劉德華",
        "intro": "畢業於師范大學數學系，熱愛教育事業，執教數學思維6年有余"
      }
    ]
  }
}

沒有返回數據：

{
  "success": true,
  "code": 20000,
  "message": "成功",
  "data": {}
}

失敗：

{
  "success": false,
  "code": 20001,
  "message": "失敗",
  "data": {}
}

因此，我們定義統一結果

{
  "success": 布爾, //響應是否成功
  "code": 數字, //響應碼
  "message": 字符串, //返回消息
  "data": HashMap //返回數據，放在鍵值對中
}

二、創建統一結果返回類

1、在common模塊下創建子模塊common-utils

2、創建接口定義返回碼

創建包com.royal.commonutils，創建接口 ResultCode.java

package com.royal.commonutils;

public interface ResultCode {

    public static Integer SUCCESS = 20000;

    public static Integer ERROR = 20001;
}

3、創建結果類

創建類 R.java

@Data
public class R {
    @ApiModelProperty(value = "是否成功")
    private Boolean success;

    @ApiModelProperty(value = "返回碼")
    private Integer code;

    @ApiModelProperty(value = "返回消息")
    private String message;

    @ApiModelProperty(value = "返回數據")
    private Map<String, Object> data = new HashMap<String, Object>();

    private R(){}

    public static R ok(){
        R r = new R();
        r.setSuccess(true);
        r.setCode(ResultCode.SUCCESS);
        r.setMessage("成功");
        return r;
    }

    public static R error(){
        R r = new R();
        r.setSuccess(false);
        r.setCode(ResultCode.ERROR);
        r.setMessage("失敗");
        return r;
    }

    public R success(Boolean success){
        this.setSuccess(success);
        return this;
    }

    public R message(String message){
        this.setMessage(message);
        return this;
    }

    public R code(Integer code){
        this.setCode(code);
        return this;
    }

    public R data(String key, Object value){
        this.data.put(key, value);
        return this;
    }

    public R data(Map<String, Object> map){
        this.setData(map);
        return this;
    }
}

三、統一返回結果使用

1、在service模塊中添加依賴

<dependency>
    <groupId>com.royal</groupId>
    <artifactId>common_utils</artifactId>
    <version>0.0.1-SNAPSHOT</version>
</dependency>

2、修改Controller中的返回結果

列表

@ApiOperation(value = "所有講師列表")
@GetMapping
public R list(){
    List<Teacher> list = teacherService.list(null);
    return R.ok().data("items", list);
}

刪除

@ApiOperation(value = "根據ID刪除講師")
@DeleteMapping("{id}")
public R removeById(
    @ApiParam(name = "id", value = "講師ID", required = true)
    @PathVariable String id){
    teacherService.removeById(id);
    return R.ok();
}

四、統一異常處理

我們想讓異常結果也顯示為統一的返回結果對象，並且統一處理系統的異常信息，那么需要統一異常處理

1、創建統一異常處理器

在service-base中創建統一異常處理類GlobalExceptionHandler.java：

/**
 * 統一異常處理類
 */
@ControllerAdvice
public class GlobalExceptionHandler {
    
    /**
     * 全局異常
     * @param e
     * @return
     */
	@ExceptionHandler(Exception.class)
	@ResponseBody
	public R error(Exception e){
		e.printStackTrace();
		return R.error();
	}
}

2、處理特定異常

GlobalExceptionHandler.java中添加

@ExceptionHandler(ArithmeticException.class)
@ResponseBody
public R error(ArithmeticException e){
    e.printStackTrace();
    return R.error().message("執行了自定義異常");
}

3、自定義異常

1、創建自定義異常類

@Data
@AllArgsConstructor
@NoArgsConstructor
public class GuliException extends RuntimeException {

    @ApiModelProperty(value = "狀態碼")
    private Integer code;

    private String msg;
    
}

2、業務中需要的位置拋出GuliException

try {
    int a = 10/0;
}catch(Exception e) {
    throw new GuliException(20001,"出現自定義異常");
}

3、添加異常處理方法

GlobalExceptionHandler.java中添加

@ExceptionHandler(GuliException.class)
@ResponseBody
public R error(GuliException e){
    e.printStackTrace();
    return R.error().message(e.getMsg()).code(e.getCode());
}

4、測試