在這個微服務的世界里，后端API的一致性設計是必不可少的，
今天，我們將討論一些可遵循的最佳實踐，我們將保持簡短和甜蜜——所以系好安全帶，出發咯！
首先介紹一些術語
任何API設計都遵循一種叫做“面向資源設計”的原則：
- 資源：資源是資料的一部分，例如：用戶
- 集合：一組資源稱為集合，例如：用戶串列
- URL：標識資源或集合的位置，例如：/user
1. 對URL使用kebab-case（短橫線小寫隔開形式）
例如，如果你想要獲得訂單串列，
不應該：
/systemOrders或/system_orders
應該：
/system-orders
2. 引數使用camelCase（駝峰形式）
例如，如果你想從一個特定的商店購買產品，
不應該：
/system-orders/{order_id}
或者：
/system-orders/{OrderId}
應該：
/system-orders/{orderId}
3. 指向集合的復數名稱
如果你想獲得系統的所有用戶，
不應該：
GET /user
或：
GET /User
應該：
GET /users
4. URL以集合開始，以識別符號結束
如果要保持概念的單一性和一致性，
不應該：
GET /shops/:shopId/category/:categoryId/price
這很糟糕，因為它指向的是一個屬性而不是資源，
應該：
GET /shops/:shopId/或GET /category/:categoryId
5. 讓動詞遠離你的資源URL
不要在URL中使用動詞來表達你的意圖，相反，使用適當的HTTP方法來描述操作，
不應該：
POST /updateuser/{userId}
或：
GET /getusers
應該：
PUT /user/{userId}
6. 對非資源URL使用動詞
如果你有一個端點，它只回傳一個操作，在這種情況下，你可以使用動詞，例如，如果你想要向用戶重新發送警報，
應該：
POST /alarm/245743/resend
請記住，這些不是我們的CRUD操作，相反，它們被認為是在我們的系統中執行特定作業的函式，
7. JSON屬性使用camelCase駝峰形式
如果你正在構建一個請求體或回應體為JSON的系統，那么屬性名應該使用駝峰大小寫，
不應該：
{
user_name: "Mohammad Faisal"
user_id: "1"
}
應該：
{
userName: "Mohammad Faisal"
userId: "1"
}
8. 監控
RESTful HTTP服務必須實作/health和/version和/metricsAPI端點，他們將提供以下資訊，
/health
用200 OK狀態碼回應對/health的請求，
/version
用版本號回應對/version的請求，
/metrics
這個端點將提供各種指標，如平均回應時間，
也強烈推薦使用/debug和/status端點，
9. 不要使用table_name作為資源名
不要只使用表名作為資源名，從長遠來看，這種懶惰是有害的，
不應該：
product_order
應該：
product-orders
這是因為公開底層體系結構不是你的目的，
10. 使用API設計工具
有許多好的API設計工具用于撰寫好的檔案，例如：
- API藍圖：https://apiblueprint.org/
- Swagger：https://swagger.io/
擁有良好而詳細的檔案可以為API使用者帶來良好的用戶體驗，
11. 使用簡單序數作為版本
始終對API使用版本控制，并將其向左移動，使其具有最大的作用域，版本號應該是v1，v2等等，
應該：http://api.domain.com/v1/shops/3/products
始終在API中使用版本控制，因為如果API被外部物體使用，更改端點可能會破壞它們的功能，
12. 在你的回應體中包括總資源數
如果API回傳一個物件串列，則回應中總是包含資源的總數，你可以為此使用total屬性，
不應該：
{
users: [
...
]
}
應該：
{
users: [
...
],
total: 34
}
13. 接受limit和offset引數
在GET操作中始終接受limit和offset引數，
應該：
GET /shops?offset=5&limit=5
這是因為它對于前端的分頁是必要的，
14. 獲取欄位查詢引數
回傳的資料量也應該考慮在內，添加一個fields引數，只公開API中必需的欄位，
例子：
只回傳商店的名稱，地址和聯系方式，
GET /shops?fields=id,name,address,contact
在某些情況下，它還有助于減少回應大小，
15. 不要在URL中通過認證令牌
這是一種非常糟糕的做法，因為url經常被記錄，而身份驗證令牌也會被不必要地記錄，
不應該：
GET /shops/123?token=some_kind_of_authenticaiton_token
相反，通過頭部傳遞它們：
Authorization: Bearer xxxxxx, Extra yyyyy
此外，授權令牌應該是短暫有效期的，
16. 驗證內容型別
服務器不應該假定內容型別，例如，如果你接受application/x-www-form-urlencoded，那么攻擊者可以創建一個表單并觸發一個簡單的POST請求，
因此，始終驗證內容型別，如果你想使用默認的內容型別，請使用：
content-type: application/json
17. 對CRUD函式使用HTTP方法
HTTP方法用于解釋CRUD功能，
GET：檢索資源的表示形式，
POST：創建新的資源和子資源，
PUT：更新現有資源，
PATCH：更新現有資源，它只更新提供的欄位，而不更新其他欄位，
DELETE：洗掉已存在的資源，
18. 在嵌套資源的URL中使用關系
以下是一些實際例子：
- GET /shops/2/products：從shop 2獲取所有產品的串列，
- GET /shops/2/products/31：獲取產品31的詳細資訊，產品31屬于shop 2，
- DELETE /shops/2/products/31：應該洗掉產品31，它屬于商店2，
- PUT /shops/2/products/31：應該更新產品31的資訊，只在resource-URL上使用PUT，而不是集合，
- POST /shops：應該創建一個新的商店，并回傳創建的新商店的詳細資訊，在集合url上使用POST，
19. CORS（跨源資源共享）
一定要為所有面向公共的API支持CORS（跨源資源共享）頭部，
考慮支持CORS允許的“*”來源，并通過有效的OAuth令牌強制授權，
避免將用戶憑證與原始驗證相結合，
20. 安全
在所有端點、資源和服務上實施HTTPS（tls加密），
強制并要求所有回呼url、推送通知端點和webhooks使用HTTPS，
21. 錯誤
當客戶端向服務發出無效或不正確的請求，或向服務傳遞無效或不正確的資料，而服務拒絕該請求時，就會出現錯誤，或者更具體地說，出現服務錯誤，
例子包括無效的身份驗證憑證、不正確的引數、未知的版本id等，
- 當由于一個或多個服務錯誤而拒絕客戶端請求時，一定要回傳4xx HTTP錯誤代碼，
- 考慮處理所有屬性，然后在單個回應中回傳多個驗證問題，
22. 黃金法則
如果您對API格式的決定有疑問，這些黃金規則可以幫助我們做出正確的決定，
- 扁平比嵌套好，
- 簡單勝于復雜，
- 字串比數字好，
- 一致性比定制更好，
就是這樣——如果你已經走到了這一步，恭喜你！希望你學到了一些東西，
來源：dockone.io/article/2434604
鏈接：betterprogramming.pub/22-best-practices-to-take-your-api-design-skills-to-the-next-level-65569b200b9
譯者：劉志超，軟體工程師、DevOpsDays、HDZ深圳核心組織者，目前供職于華為，從事云計算作業，專注于K8s、微服務領域，
近期熱文推薦：
1.1,000+ 道 Java面試題及答案整理(2022最新版)
2.勁爆！Java 協程要來了，，，
3.Spring Boot 2.x 教程，太全了！
4.別再寫滿屏的爆爆爆炸類了，試試裝飾器模式，這才是優雅的方式！！
5.《Java開發手冊（嵩山版）》最新發布，速速下載！
覺得不錯，別忘了隨手點贊+轉發哦！
轉載請註明出處，本文鏈接：https://www.uj5u.com/houduan/439127.html
標籤：Java
上一篇：go泛型教程