【Java學習】API介面數據規範

在日常開發中，一個優雅的API，必須提供簡單明瞭的響應值，然後根據狀態碼就可以大概知道問題的所在。這裡主要整理一下HTTP狀態碼和自定義狀態碼。

1、HTTP狀態碼

當瀏覽者訪問一個網頁時，瀏覽者的瀏覽器會向網頁所在伺服器發出請求。當瀏覽器接收並顯示網頁前，此網頁所在的伺服器會返回一個包含 HTTP 狀態碼的信息頭（server header）用以響應瀏覽器的請求。

常見的HTTP狀態碼有：

200-請求成功。

301-資源（網頁等）被永久轉移到其它URL。

403-伺服器拒絕訪問。驗證身份通過了，但是資源沒有許可權進行操作。

404-請求資源（網頁等）不存在。

500-內部伺服器錯誤。

504-網關超時。伺服器作為網關或代理，但是沒有及時從上游伺服器收到請求。

2、HTTP狀態碼分類

HTTP狀態碼可以分為5類：消息響應、成功響應、重定向、客戶端錯誤、伺服器錯誤。

3、自定義響應狀態碼規範

後端返回給前端一般使用json格式，定義如下：

{
    #返回狀態碼
    Code:integer,
    #返回信息描述
    message:string,
    #返回值
    data:object
}

3.1、返回介面

public interface IResultStatus {
    /**
     * 狀態碼
     * @return
     */
    Integer errorCode();
    /**
     * 異常信息
     * @return
     */
    String errorMsg();
}

3.2、狀態碼枚舉：

public enum ResultStatus implements IResultStatus {
    /**
     * 狀態碼及對應信息
     */
    //成功狀態碼
    SUCCESS(0, "執行成功"),
    //參數錯誤：1001~1999
    PARAM_IS_INVALID(1001, "參數無效"),
    PARAM_IS_BLANK(1002, "參數為空"),
    PARAM_TYPE_BIND_ERROR(1003, "參數類型錯誤"),
    //用戶錯誤：2001~2999
    USER_LOGIN_ERROR(2001, "賬號不存在或密碼錯誤"),
    USER_ACCOUNT_FORBIDDEN(2002, "賬戶已被禁用"),
    USER_NOT_EXIST(2003, "用戶不存在");
    private int errorCode;
    private String errorMsg;
    ResultStatus(int errorCode, String errorMsg) {
        this.errorCode = errorCode;
        this.errorMsg = errorMsg;
    }
    @Override
    public Integer errorCode() {
        return errorCode;
    }
    @Override
    public String errorMsg() {
        return errorMsg;
    }
}

狀態碼和信息就會一一對應，比較好維護。這樣前端同事在得到返回值後，根據狀態碼就可以知道，大概是什麼錯誤，再根據message相關的信息描述，可以快速定位。

3.3、返回數據體

json格式，根據不同的業務有不同的json體，可以設計一個返回體類Result

@Data
public class Result<T> {
    private Integer code;
    private String message;
    private Object data;
    public Result(ResultStatus restStatus, Object data) {
        this.code = restStatus.errorCode();
        this.message = restStatus.errorMsg();
        this.data = data;
    }
    /**
     * 業務成功返回業務代碼和描述信息
     */
    public static Result<Void> success() {
        return new Result<Void>(ResultStatus.SUCCESS, null);
    }
    /**
     * 業務成功返回業務代碼,描述和返回的參數
     */
    public static <T> Result<T> success(T data) {
        return new Result<T>(ResultStatus.SUCCESS, data);
    }
    /**
     * 業務成功返回業務代碼,描述和返回的參數
     */
    public static <T> Result<T> success(ResultStatus resultStatus, T data) {
        if (resultStatus == null) {
            return success(data);
        }
        return new Result<T>(resultStatus, data);
    }
    /**
     * 業務異常返回業務代碼和描述信息
     */
    public static <T> Result<T> failure() {
        return new Result<T>(ResultStatus.PARAM_TYPE_BIND_ERROR, null);
    }
    /**
     * 業務異常返回業務代碼,描述和返回的參數
     */
    public static <T> Result<T> failure(ResultStatus resultStatus) {
        return failure(resultStatus, null);
    }
    /**
     * 業務異常返回業務代碼,描述和返回的參數
     */
    public static <T> Result<T> failure(ResultStatus resultStatus, T data) {
        if (resultStatus == null) {
            return new Result<T>(ResultStatus.PARAM_IS_INVALID, null);
        }
        return new Result<T>(resultStatus, data);
    }
}

3.4、返回體測試

@RestController
@RequestMapping("/api/demo2")
public class Demo2Controller {
    private static final HashMap<String, Object> INFO;
    static {
        INFO = new HashMap<>();
        INFO.put("name", "張三");
        INFO.put("age", "25");
    }
    @GetMapping("/getInfo")
    public Map<String, Object> getInfo() {
        return INFO;
    }
    @GetMapping("/getInfoResult")
    public Result<Map<String, Object>> getInfoResult() {
        return Result.success(INFO);
    }
}

結果參考：