• <bdo id="ec2ec"><center id="ec2ec"></center></bdo>
  • 首頁 我們 服務 網站建設 移動應用 案例 資訊 聯系
    業務專線:15989169178

    期待聆聽您的聲音

    15989169178

    不忽悠,不作惡,不欺詐;敬天理,存良知,思利他。
    QQ咨詢 QQ咨詢 QQ咨詢
    服務網點:廣州 深圳 佛山 粵西

    與我們一起分享美好

    22條API設計的最佳實踐

    發布時間:2022-02-24 發布作者:睿思設計 查閱次數:307次 標簽:API
    曾經因為一個糟糕的API而感到沮喪嗎?
    在這個微服務的世界里,后端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格式的決定有疑問,這些黃金規則可以幫助我們做出正確的決定。

    • 扁平比嵌套好。

    • 簡單勝于復雜。

    • 字符串比數字好。

    • 一致性比定制更好。

    就是這樣——如果你已經走到了這一步,恭喜你!希望你學到了一些東西。

    希望你度過美好的一天!


    譯者:Mr.lzc,軟件工程師、DevOpsDays、HDZ深圳核心組織者,目前供職于華為,從事云計算工作,專注于K8s、微服務領域。

    虛擬主機怎樣將網站根目錄指向public目錄

    網站信息無障礙設計研究

    我們的位置

    廣州 廣州市黃埔區科學大道18號芯大廈 159 8916 9178

    深圳 深圳市南山區大沖國際中心九樓 159 1543 2684

    粵西 茂名市茂南區油城三路粵西創業創新孵化基地B110 157 6767 8148

    我們的服務

    網站及移動應用 高端品牌網站 APP開發 小程序開發 微信運營

    系統應用開發 OA/ERP/CRM/HR系統開發 教學管理系統 電商系統 應用型軟件系統定制開發

    了解我們

    公司簡介 聯系我們 我們的案例 新聞資訊

    使用條款 隱私聲明 Cookies

    © 2009-2022 廣州睿網信息科技有限公司 版權所有 粵ICP備16051058號

    毛豆视频,没有废话全色肉的黄文,中国女人18毛片A级毛片视频
  • <bdo id="ec2ec"><center id="ec2ec"></center></bdo>