如何優雅的處理Restful

最近公司搭建的項目，前端反映後端返回格式不統一的問題，因此引發小編的思考，如何能夠優雅的處理返回值格式呢？在度娘中仔細研讀了一番，決定總結一下，於是乎此文便誕生了。

一、背景

首先，大家都會思考爲什麼要做統一格式處理呢？

現階段的開發模式多以前後端分離形式存在，前後端開發人員需要通過大量 API 來進行數據交互，如果在交互過程中前後端人員經常遭遇如下問題：

• 前端人員不能快速理解接口字段含義及接口字段變化

• 後端人員想複用某些接口，但是不能快速從接口 URL 的定義中明確該接口的含義，需要進一步讀代碼確認

• URL中的英文單詞使用五花八門，搜索某個接口不知道具體的關鍵字

• 請求方法動詞如 POST GET 隨意使用

• 完成當前業務接口對接，前端人員經常會詢問下一步業務流程的接口定義在哪裏，對接形式是什麼樣的

以上只是前後端人員通過接口交互的一小部分問題，這些問題就好比"牙痛"，不致命，但是在整個軟件開發的生命週期內，天天"牙痛”是很要命的, 需要解決上述的問題，需要前後端人員都能認識與瞭解接口設計規範的重要性。因此，如何讓前端小夥伴可以處理標準的 response JSON 數據結構都至關重要。

通過上面一個問題把大家帶入正題，下面我們統一定義一下格式。

二、格式定義

2.1結果格式定義

每一次 RESTful 請求都應該包含以下幾個信息：

名稱	描述
success	標識請求成功與否，false、true
code	狀態碼，標識錯誤類型
message	提示信息
data	返回數據

 

2.2結果枚舉類定義

/**
 * @Author:qxy
 * @Date:2020/4/7 13:07
 */
public enum ResultCodeEnum {
    /*** 通用部分 100 - 599***/
    // 成功請求
    SUCCESS(200, "successful"),
    // 重定向
    REDIRECT(301, "redirect"),
    // 資源未找到
    NOT_FOUND(404, "not found"),
    // 服務器錯誤
    SERVER_ERROR(500,"server error"),

    BUSINESS_EXCEPTION(4000, "business exception"),
    ;

    private Integer code;

    private String message;

    //省略get/set方法
}

爲了日常開發中規範狀態碼，這裏着重參考一下Http定義的規範：

常見的HTTP狀態碼如：
200 - 請求成功；
301 - 資源（網頁等）被永久轉移到其它URL；
404 - 請求的資源（網頁等）不存在；
500 - 內部服務器錯誤。
message：錯誤信息
在發生錯誤時，如何友好的進行提示？
1.根據code 給予對應的錯誤碼定位；
2.把錯誤描述記錄到message中，便於接口調用者更詳細的瞭解錯誤。

狀態碼類型	code區間	類型	含義
1	100-199	信息	服務器接收到請求，需要請求者繼續執行操作
2	200-299	成功	請求被成功接收並處理
3	300-399	重定向	需要進一步的操作以完成請求
4	400-499	客戶端錯誤	請求包含語法錯誤或無法完成請求
5	500-599	服務端錯誤	服務器在處理的時候發生錯誤

 

2.3統一結果類

/**
 * @Author:qxy
 * @Date:2020/4/7 13:11
 */
public class HttpResult<T> implements Serializable {

    private Boolean success;

    private Integer code;

    private String message;

    private T data;
    //省略get/set

    /**
     * 無參構造
     */
    public HttpResult() {
        this.success = true;
        this.code = ResultCodeEnum.SUCCESS.getCode();
        this.message = ResultCodeEnum.SUCCESS.getMessage();
    }

    /**
     * 有參構造：返回成功
     * @param object
     */
    public HttpResult(T object) {
        this.success = true;
        this.code = ResultCodeEnum.SUCCESS.getCode();
        this.message = ResultCodeEnum.SUCCESS.getMessage();
        this.data = object;
    }

    /**
     * 有參構造：返回失敗
     * @param resultCode
     */
    public HttpResult(ResultCodeEnum resultCode) {
        this.success = false;
        this.code = resultCode.getCode();
        this.message = resultCode.getMessage();
    }
    
}

2.4定義業務場景返回類

/**
 * @Author:qxy
 * @Date:2020/4/7 13:57
 */
public class ResultResponse {
    /**
     * 通用返回成功（沒有返回結果）
     * @param
     * @return
     */
    public static HttpResult success(){
        return new HttpResult();
    }

    /**
     * 返回成功（有返回結果）
     * @param data
     * @return
     */
    public static<T> HttpResult success(T data){
        return new HttpResult<T>(data);
    }

    /**
     * 通用返回失敗
     * @param resultCode
     * @param <T>
     * @return
     */
    public static<T> HttpResult<T> failure(ResultCodeEnum resultCode){
        return new HttpResult<T>(resultCode);
    }

    /**
     * 捕獲異常類型設置狀態和提示信息
     * @param code
     * @param message
     * @param <T>
     * @return
     */
    public static<T> HttpResult<T> failure(Integer code, String message) {
        ResultCodeEnum resultCodeEnum = ResultCodeEnum.BUSINESS_EXCEPTION;
        resultCodeEnum.setCode(code);
        resultCodeEnum.setMessage(message);
        return failure(resultCodeEnum);
    }
}

三、測試

/**
 * @Author:qxy
 * @Date:2020/4/7 9:45
 */
@RestController
public class StudentController {

    @Autowired
    private StudentService studentService;

    @GetMapping("/getStudentList")
    public HttpResult getStudentList(){
        return ResultResponse.success(studentService.getStudentList());
    }
}

詳細代碼請移步github下載：https://github.com/stream-source/stream-source/tree/master/informal-essay/src/main/java/com/qxy/response

參考資料：風塵博客