構建強大REST API的十個最佳實踐
在項目開發(fā)中，我們經常會使用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狀態(tài)碼
返回適當的HTTP狀態(tài)碼以指示API請求的成功或失敗。
圖片
這一條也是非常基礎的HTTP知識，不同的錯誤碼代表著不同的含義，準確的返回錯誤碼，可以讓終端更加精準的識別錯誤。
5、選擇JSON字段命名約定
JSON標準沒有強制規(guī)定字段命名約定，但最佳實踐是選擇一個并堅持使用。
圖片
選擇適合團隊和編程語言的JSON命名規(guī)則，具體采用哪種不重要，重要的是整個團隊要確保統(tǒng)一。在個人的團隊中，更習慣使用駝峰（camelCase）的形式。
6、使用一致的錯誤信息
在大多數情況下，僅使用HTTP狀態(tài)碼無法解釋出現的錯誤。為了幫助API使用者，包含一個結構化的JSON錯誤消息。這里的JSON錯誤信息更偏向業(yè)務層面。而HTTP狀態(tài)碼更偏向于HTTP交互層面。
響應應包括以下信息：
- 錯誤代碼：機器可讀的錯誤代碼，用于識別特定的錯誤條件。
- 錯誤消息：人類可讀的消息，提供對錯誤的詳細解釋。
- 錯誤上下文：與錯誤相關的附加信息，例如請求ID、導致錯誤的請求參數或導致錯誤的請求中的字段。
- 錯誤鏈接：提供有關錯誤以及如何解決錯誤的附加信息或文檔的URL。
- 時間戳：錯誤發(fā)生的時間。
7、使用查詢參數進行過濾、排序和搜索
查詢參數允許你在HTTP請求的URL中提供額外的信息，以控制服務器返回的響應。
圖片
8、實施身份驗證和授權
通過實施適當的身份驗證和授權機制來保護API。
建議：
- 使用API密鑰、令牌或OAuth 2.0進行身份驗證
- 應用基于角色的訪問控制（RBAC）進行授權
9、不要維護狀態(tài)
REST API不應在服務器上維護狀態(tài)，這是客戶端的責任。這很重要，因為它可以使API具備可緩存性、可擴展性，并使其與客戶端解耦。
例如，電子商務API可能使用cookie來維護購物車的狀態(tài)。然而，這種方法違反了RESTful API的關鍵原則：它們需要是無狀態(tài)的。
10、文檔化你的API
為你的API提供全面的文檔，包括端點細節(jié)、請求/響應示例和使用指南。
建議：
- Swagger/OpenAPI文檔
- 基于Markdown的文檔（例如，使用Swagger UI或Redoc等工具）
