【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 =https://www.cnblogs.com/pbinlog/p/ 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);
    }
}

結果參考：

標籤：Java

上一篇：Java 在Word指定段落/文本位置插入分頁符

下一篇：1.1.0.1 前言