天堂网www天堂在线中文,手机看片av永久免费,色窝窝无码一区二区三区成人网站,香蕉大视频一二三区乱码

曾經(jīng)因為一個糟糕的API而感到沮喪嗎？

在這個微服務(wù)的世界里，后端API的一致性設(shè)計是必不可少的。

今天，我們將討論一些可遵循的最佳實踐。我們將保持簡短和甜蜜——所以系好安全帶，出發(fā)咯！

首先介紹一些術(shù)語

任何API設(shè)計都遵循一種叫做“面向資源設(shè)計”的原則：

• 資源：資源是數(shù)據(jù)的一部分，例如：用戶

• 集合：一組資源稱為集合，例如：用戶列表

• URL：標(biāo)識資源或集合的位置，例如：/user

1. 對URL使用kebab-case（短橫線小寫隔開形式）

例如，如果你想要獲得訂單列表。

不應(yīng)該：

/systemOrders或/system_orders

應(yīng)該：

/system-orders

2. 參數(shù)使用camelCase（駝峰形式）

例如，如果你想從一個特定的商店購買產(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)識符結(jié)束

如果要保持概念的單一性和一致性。

不應(yīng)該：

GET /shops/:shopId/category/:categoryId/price

這很糟糕，因為它指向的是一個屬性而不是資源。

應(yīng)該：

GET /shops/:shopId/或GET /category/:categoryId

5. 讓動詞遠離你的資源URL

不要在URL中使用動詞來表達你的意圖。相反，使用適當(dāng)?shù)腍TTP方法來描述操作。

不應(yīng)該：

POST /updateuser/{userId}

或：

GET /getusers

應(yīng)該：

PUT /user/{userId}

6. 對非資源URL使用動詞

如果你有一個端點，它只返回一個操作。在這種情況下，你可以使用動詞。例如，如果你想要向用戶重新發(fā)送警報。

應(yīng)該：

POST /alarm/245743/resend

請記住，這些不是我們的CRUD操作。相反，它們被認為是在我們的系統(tǒng)中執(zhí)行特定工作的函數(shù)。

7. JSON屬性使用camelCase駝峰形式

如果你正在構(gòu)建一個請求體或響應(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ù)必須實現(xiàn)/health和/version和/metricsAPI端點。他們將提供以下信息。

/health

用200 OK狀態(tài)碼響應(yīng)對/health的請求。

/version

用版本號響應(yīng)對/version的請求。

/metrics

這個端點將提供各種指標(biāo)，如平均響應(yīng)時間。

也強烈推薦使用/debug和/status端點。

9. 不要使用table_name作為資源名

不要只使用表名作為資源名。從長遠來看，這種懶惰是有害的。

不應(yīng)該：

product_order

應(yīng)該：

product-orders

這是因為公開底層體系結(jié)構(gòu)不是你的目的。

10. 使用API設(shè)計工具

有許多好的API設(shè)計工具用于編寫好的文檔，例如：

• API藍圖：https://apiblueprint.org/

• Swagger：https://swagger.io/

擁有良好而詳細的文檔可以為API使用者帶來良好的用戶體驗。

11. 使用簡單序數(shù)作為版本

始終對API使用版本控制，并將其向左移動，使其具有最大的作用域。版本號應(yīng)該是v1，v2等等。

應(yīng)該：http://api.domain.com/v1/shops/3/products

始終在API中使用版本控制，因為如果API被外部實體使用，更改端點可能會破壞它們的功能。

12. 在你的響應(yīng)體中包括總資源數(shù)

如果API返回一個對象列表，則響應(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

這是因為它對于前端的分頁是必要的。

14. 獲取字段查詢參數(shù)

返回的數(shù)據(jù)量也應(yīng)該考慮在內(nèi)。添加一個fields參數(shù)，只公開API中必需的字段。

例子：

只返回商店的名稱，地址和聯(lián)系方式。

GET /shops?fields=id,name,address,contact

在某些情況下，它還有助于減少響應(yīng)大小。

15. 不要在URL中通過認證令牌

這是一種非常糟糕的做法，因為url經(jīng)常被記錄，而身份驗證令牌也會被不必要地記錄。

不應(yīng)該：

GET /shops/123?token=some_kind_of_authenticaiton_token

相反，通過頭部傳遞它們：

Authorization: Bearer xxxxxx, Extra yyyyy

此外，授權(quán)令牌應(yīng)該是短暫有效期的。

16. 驗證內(nèi)容類型

服務(wù)器不應(yīng)該假定內(nèi)容類型。例如，如果你接受application/x-www-form-urlencoded，那么攻擊者可以創(chuàng)建一個表單并觸發(fā)一個簡單的POST請求。

因此，始終驗證內(nèi)容類型，如果你想使用默認的內(nèi)容類型，請使用：

content-type: application/json

17. 對CRUD函數(shù)使用HTTP方法

HTTP方法用于解釋CRUD功能。

GET：檢索資源的表示形式。

POST：創(chuàng)建新的資源和子資源。

PUT：更新現(xiàn)有資源。

PATCH：更新現(xiàn)有資源，它只更新提供的字段，而不更新其他字段。

DELETE：刪除已存在的資源。

18. 在嵌套資源的URL中使用關(guān)系

以下是一些實際例子：

• GET /shops/2/products：從shop 2獲取所有產(chǎn)品的列表。

• GET /shops/2/products/31：獲取產(chǎn)品31的詳細信息，產(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)建一個新的商店，并返回創(chuàng)建的新商店的詳細信息。在集合url上使用POST。

19. CORS（跨源資源共享）

一定要為所有面向公共的API支持CORS（跨源資源共享）頭部。

考慮支持CORS允許的“*”來源，并通過有效的OAuth令牌強制授權(quán)。

避免將用戶憑證與原始驗證相結(jié)合。

20. 安全

在所有端點、資源和服務(wù)上實施HTTPS（tls加密）。

強制并要求所有回調(diào)url、推送通知端點和webhooks使用HTTPS。

21. 錯誤

當(dāng)客戶端向服務(wù)發(fā)出無效或不正確的請求，或向服務(wù)傳遞無效或不正確的數(shù)據(jù)，而服務(wù)拒絕該請求時，就會出現(xiàn)錯誤，或者更具體地說，出現(xiàn)服務(wù)錯誤。

例子包括無效的身份驗證憑證、不正確的參數(shù)、未知的版本id等。

• 當(dāng)由于一個或多個服務(wù)錯誤而拒絕客戶端請求時，一定要返回4xx HTTP錯誤代碼。

• 考慮處理所有屬性，然后在單個響應(yīng)中返回多個驗證問題。

22. 黃金法則

如果您對API格式的決定有疑問，這些黃金規(guī)則可以幫助我們做出正確的決定。

• 扁平比嵌套好。

• 簡單勝于復(fù)雜。

• 字符串比數(shù)字好。

• 一致性比定制更好。

就是這樣——如果你已經(jīng)走到了這一步，恭喜你！希望你學(xué)到了一些東西。

希望你度過美好的一天！

譯者：Mr.lzc，軟件工程師、DevOpsDays、HDZ深圳核心組織者，目前供職于華為，從事云計算工作，專注于K8s、微服務(wù)領(lǐng)域。