原文鏈接：
https://mp.weixin.qq.com/s/z_VTBydcQKQ9R-gGH5C6Dw
在這個(gè)微服務(wù)的世界里，后端API的一致性設(shè)計(jì)是必不可少的。
今天，我們將討論一些可遵循的最佳實(shí)踐。我們將保持簡(jiǎn)短和甜蜜——所以系好安全帶，出發(fā)咯！
首先介紹一些術(shù)語(yǔ)
任何API設(shè)計(jì)都遵循一種叫做“面向資源設(shè)計(jì)”的原則：
- 資源：資源是數(shù)據(jù)的一部分，例如：用戶
- 集合：一組資源稱為集合，例如：用戶列表
- URL：標(biāo)識(shí)資源或集合的位置，例如：/user
1. 對(duì)URL使用kebab-case（短橫線小寫隔開形式）
例如，如果你想要獲得訂單列表。
不應(yīng)該：
/systemOrders或/system_orders
應(yīng)該：
/system-orders
2. 參數(shù)使用camelCase（駝峰形式）
例如，如果你想從一個(gè)特定的商店購(gòu)買產(chǎn)品。
不應(yīng)該：
/system-orders/{order_id}
或者：
/system-orders/{OrderId}
應(yīng)該：
/system-orders/{orderId}
3. 指向集合的復(fù)數(shù)名稱
如果你想獲得系統(tǒng)的所有用戶。
不應(yīng)該：
GET /user
或：
GET /User
應(yīng)該：
GET /users
4. URL以集合開始，以標(biāo)識(shí)符結(jié)束
如果要保持概念的單一性和一致性。
不應(yīng)該：
GET /shops/:shopId/category/:categoryId/price
這很糟糕，因?yàn)樗赶虻氖且粋€(gè)屬性而不是資源。
應(yīng)該：
GET /shops/:shopId/或GET /category/:categoryId
5. 讓動(dòng)詞遠(yuǎn)離你的資源URL
不要在URL中使用動(dòng)詞來表達(dá)你的意圖。相反，使用適當(dāng)?shù)腍TTP方法來描述操作。
不應(yīng)該：
POST /updateuser/{userId}
或：
GET /getusers
應(yīng)該：
PUT /user/{userId}
6. 對(duì)非資源URL使用動(dòng)詞
如果你有一個(gè)端點(diǎn)，它只返回一個(gè)操作。在這種情況下，你可以使用動(dòng)詞。例如，如果你想要向用戶重新發(fā)送警報(bào)。
應(yīng)該：
POST /alarm/245743/resend
請(qǐng)記住，這些不是我們的CRUD操作。相反，它們被認(rèn)為是在我們的系統(tǒng)中執(zhí)行特定工作的函數(shù)。
7. JSON屬性使用camelCase駝峰形式
如果你正在構(gòu)建一個(gè)請(qǐng)求體或響應(yīng)體為JSON的系統(tǒng)，那么屬性名應(yīng)該使用駝峰大小寫。
不應(yīng)該：
{
user_name: "Mohammad Faisal"
user_id: "1"
}
應(yīng)該：
{
userName: "Mohammad Faisal"
userId: "1"
}
8. 監(jiān)控
RESTful HTTP服務(wù)必須實(shí)現(xiàn)/health和/version和/metricsAPI端點(diǎn)。他們將提供以下信息。
/health
用200 OK狀態(tài)碼響應(yīng)對(duì)/health的請(qǐng)求。
/version
用版本號(hào)響應(yīng)對(duì)/version的請(qǐng)求。
/metrics
這個(gè)端點(diǎn)將提供各種指標(biāo)，如平均響應(yīng)時(shí)間。
也強(qiáng)烈推薦使用/debug和/status端點(diǎn)。
9. 不要使用table_name作為資源名
不要只使用表名作為資源名。從長(zhǎng)遠(yuǎn)來看，這種懶惰是有害的。
不應(yīng)該：
product_order
應(yīng)該：
product-orders
這是因?yàn)楣_底層體系結(jié)構(gòu)不是你的目的。
10. 使用API設(shè)計(jì)工具
有許多好的API設(shè)計(jì)工具用于編寫好的文檔，例如：
- API藍(lán)圖：https://apiblueprint.org/
- Swagger：https://swagger.io/
擁有良好而詳細(xì)的文檔可以為API使用者帶來良好的用戶體驗(yàn)。
11. 使用簡(jiǎn)單序數(shù)作為版本
始終對(duì)API使用版本控制，并將其向左移動(dòng)，使其具有最大的作用域。版本號(hào)應(yīng)該是v1，v2等等。
應(yīng)該：
http://api.domain.com/v1/shops/3/products
始終在API中使用版本控制，因?yàn)槿绻鸄PI被外部實(shí)體使用，更改端點(diǎn)可能會(huì)破壞它們的功能。
12. 在你的響應(yīng)體中包括總資源數(shù)
如果API返回一個(gè)對(duì)象列表，則響應(yīng)中總是包含資源的總數(shù)。你可以為此使用total屬性。
不應(yīng)該：
{
users: [
...
]
}
應(yīng)該：
{
users: [
...
],
total: 34
}
13. 接受limit和offset參數(shù)
在GET操作中始終接受limit和offset參數(shù)。
應(yīng)該：
GET /shops?offset=5&limit=5
這是因?yàn)樗鼘?duì)于前端的分頁(yè)是必要的。
14. 獲取字段查詢參數(shù)
返回的數(shù)據(jù)量也應(yīng)該考慮在內(nèi)。添加一個(gè)fields參數(shù)，只公開API中必需的字段。
例子：
只返回商店的名稱，地址和聯(lián)系方式。
GET /shops?fields=id,name,address,contact
在某些情況下，它還有助于減少響應(yīng)大小。
15. 不要在URL中通過認(rèn)證令牌
這是一種非常糟糕的做法，因?yàn)閡rl經(jīng)常被記錄，而身份驗(yàn)證令牌也會(huì)被不必要地記錄。
不應(yīng)該：
GET /shops/123?token=some_kind_of_authenticaiton_token
相反，通過頭部傳遞它們：
Authorization: Bearer xxxxxx, Extra yyyyy
此外，授權(quán)令牌應(yīng)該是短暫有效期的。
16. 驗(yàn)證內(nèi)容類型
服務(wù)器不應(yīng)該假定內(nèi)容類型。例如，如果你接受
Application/x-www-form-urlencoded，那么攻擊者可以創(chuàng)建一個(gè)表單并觸發(fā)一個(gè)簡(jiǎn)單的POST請(qǐng)求。
因此，始終驗(yàn)證內(nèi)容類型，如果你想使用默認(rèn)的內(nèi)容類型，請(qǐng)使用：
content-type: application/json
17. 對(duì)CRUD函數(shù)使用HTTP方法
HTTP方法用于解釋CRUD功能。
GET：檢索資源的表示形式。
POST：創(chuàng)建新的資源和子資源。
PUT：更新現(xiàn)有資源。
PATCH：更新現(xiàn)有資源，它只更新提供的字段，而不更新其他字段。
DELETE：刪除已存在的資源。
18. 在嵌套資源的URL中使用關(guān)系
以下是一些實(shí)際例子：
- GET /shops/2/products：從shop 2獲取所有產(chǎn)品的列表。
- GET /shops/2/products/31：獲取產(chǎn)品31的詳細(xì)信息，產(chǎn)品31屬于shop 2。
- DELETE /shops/2/products/31：應(yīng)該刪除產(chǎn)品31，它屬于商店2。
- PUT /shops/2/products/31：應(yīng)該更新產(chǎn)品31的信息，只在resource-URL上使用PUT，而不是集合。
- POST /shops：應(yīng)該創(chuàng)建一個(gè)新的商店，并返回創(chuàng)建的新商店的詳細(xì)信息。在集合url上使用POST。
19. CORS（跨源資源共享）
一定要為所有面向公共的API支持CORS（跨源資源共享）頭部。
考慮支持CORS允許的“*”來源，并通過有效的OAuth令牌強(qiáng)制授權(quán)。
避免將用戶憑證與原始驗(yàn)證相結(jié)合。
20. 安全
在所有端點(diǎn)、資源和服務(wù)上實(shí)施HTTPS（tls加密）。
強(qiáng)制并要求所有回調(diào)url、推送通知端點(diǎn)和webhooks使用HTTPS。
21. 錯(cuò)誤
當(dāng)客戶端向服務(wù)發(fā)出無效或不正確的請(qǐng)求，或向服務(wù)傳遞無效或不正確的數(shù)據(jù)，而服務(wù)拒絕該請(qǐng)求時(shí)，就會(huì)出現(xiàn)錯(cuò)誤，或者更具體地說，出現(xiàn)服務(wù)錯(cuò)誤。
例子包括無效的身份驗(yàn)證憑證、不正確的參數(shù)、未知的版本id等。
- 當(dāng)由于一個(gè)或多個(gè)服務(wù)錯(cuò)誤而拒絕客戶端請(qǐng)求時(shí)，一定要返回4xx HTTP錯(cuò)誤代碼。
- 考慮處理所有屬性，然后在單個(gè)響應(yīng)中返回多個(gè)驗(yàn)證問題。
22. 黃金法則
如果您對(duì)API格式的決定有疑問，這些黃金規(guī)則可以幫助我們做出正確的決定。
- 扁平比嵌套好。
- 簡(jiǎn)單勝于復(fù)雜。
- 字符串比數(shù)字好。
- 一致性比定制更好。
就是這樣——如果你已經(jīng)走到了這一步，恭喜你！希望你學(xué)到了一些東西。
