Restful API 設(shè)計示例

一 ，HTTP狀態(tài)碼

??正例：

200: 返回成功

說明：200表示成功，4xx表示客戶端異常，5xx表示服務(wù)端異常，參見HTTP 的返回碼含義

?反例：

除了200就是500

說明：如果不細(xì)化狀態(tài)碼，前端很難充分的顯示錯誤信息，比如警告信息和錯誤信息顯示樣式不一樣

二 ， 返回數(shù)據(jù)格式

??正例：

{"data": {}, "message": "Success!", "status": 0, "requestId": 1609139633881
}

說明：data 主要負(fù)責(zé)存放數(shù)據(jù)，message 主要存放應(yīng)用的請求日志， status 負(fù)責(zé)存儲應(yīng)用狀態(tài)， requestId 負(fù)責(zé)存儲本次請求的唯一識別碼，方便排查錯誤

?反例：

{"data": {"userid": 123}}

說明：只有數(shù)據(jù)，出了異常前端很難識別

三， 請求方法

??正例：

GET： 獲取數(shù)據(jù)

POST： 創(chuàng)建數(shù)據(jù)

PUT： 更新數(shù)據(jù)

DELETE： 刪除數(shù)據(jù)

說明：很容易和資源的操作的增刪改查對應(yīng)起來，一個路由多次使用，減少路由的數(shù)量

?反例：

獲取數(shù)據(jù)，使用GET

所有的接口都是POST

說明：獲取數(shù)據(jù)必須是冪等（不改變結(jié)果）， 可以直接在瀏覽器調(diào)試，更方便

四， 請求URL格式

??正例：

/event/type/element

說明：很容易看出來是遞進(jìn)關(guān)系，需要操作的是事件類型要素，盡量不要使用復(fù)數(shù)

?反例：

/event_type_element

說明：沒有遞進(jìn)關(guān)系

?反例：

/data/import

說明：最好不要出現(xiàn)動詞，否則破壞超文本協(xié)議（HTTP）對資源的抽象的概念，這種情況可以寫成/importor/extract_data 表示導(dǎo)入抽取數(shù)據(jù)