在項目開發中，我們經常會使用REST風格進行API的定義，這篇文章為大家提供10條在使用REST API時的最佳實踐。希望能夠為你帶來靈感和幫助。

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

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

圖片

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

2、正確使用HTTP方法

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

圖片

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

3、對API進行版本控制

使用版本控制確保向后兼容性，并允許在不破壞現有客戶端的情況下進行未來的增強。

圖片

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

4、正確使用HTTP狀態碼

返回適當的HTTP狀態碼以指示API請求的成功或失敗。

圖片

這一條也是非常基礎的HTTP知識，不同的錯誤碼代表著不同的含義，準確的返回錯誤碼，可以讓終端更加精準的識別錯誤。

5、選擇JSON字段命名約定

JSON標準沒有強制規定字段命名約定，但最佳實踐是選擇一個并堅持使用。

圖片

選擇適合團隊和編程語言的JSON命名規則，具體采用哪種不重要，重要的是整個團隊要確保統一。在個人的團隊中，更習慣使用駝峰（camelCase）的形式。

6、使用一致的錯誤信息

在大多數情況下，僅使用HTTP狀態碼無法解釋出現的錯誤。為了幫助API使用者，包含一個結構化的JSON錯誤消息。這里的JSON錯誤信息更偏向業務層面。而HTTP狀態碼更偏向于HTTP交互層面。

響應應包括以下信息：

• 錯誤代碼：機器可讀的錯誤代碼，用于識別特定的錯誤條件。
• 錯誤消息：人類可讀的消息，提供對錯誤的詳細解釋。
• 錯誤上下文：與錯誤相關的附加信息，例如請求ID、導致錯誤的請求參數或導致錯誤的請求中的字段。
• 錯誤鏈接：提供有關錯誤以及如何解決錯誤的附加信息或文檔的URL。
• 時間戳：錯誤發生的時間。

7、使用查詢參數進行過濾、排序和搜索

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

圖片

8、實施身份驗證和授權

通過實施適當的身份驗證和授權機制來保護API。

建議：

• 使用API密鑰、令牌或OAuth 2.0進行身份驗證
• 應用基于角色的訪問控制（RBAC）進行授權

9、不要維護狀態

REST API不應在服務器上維護狀態，這是客戶端的責任。這很重要，因為它可以使API具備可緩存性、可擴展性，并使其與客戶端解耦。

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

10、文檔化你的API

為你的API提供全面的文檔，包括端點細節、請求/響應示例和使用指南。

建議：

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