在項(xiàng)目開發(fā)中，我們經(jīng)常會(huì)使用REST風(fēng)格進(jìn)行API的定義，這篇文章為大家提供10條在使用REST API時(shí)的最佳實(shí)踐。希望能夠?yàn)槟銕盱`感和幫助。

1、使用具體且有意義的資源名稱

選擇能準(zhǔn)確表示所代表實(shí)體的資源名稱，而不要使用泛化或模糊的名稱。

圖片

這一條最佳實(shí)踐非常明確，也就是說我們在使用REST API時(shí)，代表資源分類的部分，比如上圖中的“users”和“customers”，使用users更泛化，不夠具體，可能是To C的用戶，也可能是To B或To G的用戶。此時(shí)，最近確保定義的資源更具體，能夠代表一定的清晰含義。

2、正確使用HTTP方法

根據(jù)不同的操作使用合適的HTTP方法（GET、POST、PUT、DELETE、PATCH等）。

圖片

這一條涉及到HTTP方法的基本定義。舉一個(gè)簡單的例子來說明就是：一般提交表單操作，用POST請求，查詢信息用GET請求。不要將兩者顛掉或混用。當(dāng)然，還有其他的HTTP方法，也是如此。

3、對API進(jìn)行版本控制

使用版本控制確保向后兼容性，并允許在不破壞現(xiàn)有客戶端的情況下進(jìn)行未來的增強(qiáng)。

圖片

為了保持版本的兼容性，依舊流量和功能的控制等，通常需要對API進(jìn)行版本控制，這個(gè)是僅限于REST API，而是比較通用的一條最佳實(shí)踐，特別是真的終端是APP的情況。

4、正確使用HTTP狀態(tài)碼

返回適當(dāng)?shù)腍TTP狀態(tài)碼以指示API請求的成功或失敗。

圖片

這一條也是非常基礎(chǔ)的HTTP知識(shí)，不同的錯(cuò)誤碼代表著不同的含義，準(zhǔn)確的返回錯(cuò)誤碼，可以讓終端更加精準(zhǔn)的識(shí)別錯(cuò)誤。

5、選擇JSON字段命名約定

JSON標(biāo)準(zhǔn)沒有強(qiáng)制規(guī)定字段命名約定，但最佳實(shí)踐是選擇一個(gè)并堅(jiān)持使用。

圖片

選擇適合團(tuán)隊(duì)和編程語言的JSON命名規(guī)則，具體采用哪種不重要，重要的是整個(gè)團(tuán)隊(duì)要確保統(tǒng)一。在個(gè)人的團(tuán)隊(duì)中，更習(xí)慣使用駝峰（camelCase）的形式。

6、使用一致的錯(cuò)誤信息

在大多數(shù)情況下，僅使用HTTP狀態(tài)碼無法解釋出現(xiàn)的錯(cuò)誤。為了幫助API使用者，包含一個(gè)結(jié)構(gòu)化的JSON錯(cuò)誤消息。這里的JSON錯(cuò)誤信息更偏向業(yè)務(wù)層面。而HTTP狀態(tài)碼更偏向于HTTP交互層面。

響應(yīng)應(yīng)包括以下信息：

• 錯(cuò)誤代碼：機(jī)器可讀的錯(cuò)誤代碼，用于識(shí)別特定的錯(cuò)誤條件。
• 錯(cuò)誤消息：人類可讀的消息，提供對錯(cuò)誤的詳細(xì)解釋。
• 錯(cuò)誤上下文：與錯(cuò)誤相關(guān)的附加信息，例如請求ID、導(dǎo)致錯(cuò)誤的請求參數(shù)或?qū)е洛e(cuò)誤的請求中的字段。
• 錯(cuò)誤鏈接：提供有關(guān)錯(cuò)誤以及如何解決錯(cuò)誤的附加信息或文檔的URL。
• 時(shí)間戳：錯(cuò)誤發(fā)生的時(shí)間。

7、使用查詢參數(shù)進(jìn)行過濾、排序和搜索

查詢參數(shù)允許你在HTTP請求的URL中提供額外的信息，以控制服務(wù)器返回的響應(yīng)。

圖片

8、實(shí)施身份驗(yàn)證和授權(quán)

通過實(shí)施適當(dāng)?shù)纳矸蒡?yàn)證和授權(quán)機(jī)制來保護(hù)API。

建議：

• 使用API密鑰、令牌或OAuth 2.0進(jìn)行身份驗(yàn)證
• 應(yīng)用基于角色的訪問控制（RBAC）進(jìn)行授權(quán)

9、不要維護(hù)狀態(tài)

REST API不應(yīng)在服務(wù)器上維護(hù)狀態(tài)，這是客戶端的責(zé)任。這很重要，因?yàn)樗梢允笰PI具備可緩存性、可擴(kuò)展性，并使其與客戶端解耦。

例如，電子商務(wù)API可能使用cookie來維護(hù)購物車的狀態(tài)。然而，這種方法違反了RESTful API的關(guān)鍵原則：它們需要是無狀態(tài)的。

10、文檔化你的API

為你的API提供全面的文檔，包括端點(diǎn)細(xì)節(jié)、請求/響應(yīng)示例和使用指南。

建議：

• Swagger/OpenAPI文檔
• 基于Markdown的文檔（例如，使用Swagger UI或Redoc等工具）