使用正確的名稱和 HTTP 謂詞設(shè)計(jì) API 端點(diǎn)

設(shè)計(jì)清晰易懂的 API 是開發(fā)者的基本目標(biāo)。通過合理的 URI 命名和 HTTP 動(dòng)詞的使用，開發(fā)者可以直觀地理解 API 的功能和行為。

資源命名的基本原則

在 REST 架構(gòu)中，資源是一級(jí)數(shù)據(jù)表示。為資源命名時(shí)，保持一致性是關(guān)鍵。以下是一些命名資源的最佳實(shí)踐：

1. 使用復(fù)數(shù)形式的名詞表示資源：

   • ? /users 表示用戶集合，/users/{userId} 表示單個(gè)用戶。
   • ? /users/{userId}/playlists 表示用戶的播放列表。

2. 使用連字符 - 分隔單詞：

   • ? /users/{userId}/mobile-devices
   • ? /users/{userId}/mobileDevices

3. 使用正斜杠 / 表示層次結(jié)構(gòu)：

   • ? /users/{userId}/orders
   • ? /users-orders/{userId}

4. 統(tǒng)一使用小寫字母：

   • ? /users/{userId}/devices
   • ? /Users/{userId}/Devices

動(dòng)作命名的最佳實(shí)踐

對(duì)于與資源無關(guān)的操作，例如結(jié)賬或運(yùn)行任務(wù)，建議在 URI 中使用動(dòng)詞表示動(dòng)作：

• ? /users/{userId}/cart/checkout 表示執(zhí)行結(jié)賬操作。

同時(shí)，CRUD 操作（創(chuàng)建、讀取、更新、刪除）應(yīng)通過 HTTP 動(dòng)詞來實(shí)現(xiàn)，而非在 URI 中顯式表示。例如：

• GET：用于檢索數(shù)據(jù)，例如 /users 獲取用戶列表。
• POST：用于創(chuàng)建新資源，例如 /users 創(chuàng)建新用戶。
• PUT：用于更新資源，例如 /users/{userId} 更新用戶信息。
• DELETE：用于刪除資源，例如 /users/{userId} 刪除用戶。
• PATCH：用于部分更新資源，例如 /users/{userId} 更新部分用戶信息。

通過這些原則，開發(fā)者可以設(shè)計(jì)出清晰且易于維護(hù)的 API。

如何正確構(gòu)建你的應(yīng)用程序

構(gòu)建 Flask 應(yīng)用程序的方式可能因項(xiàng)目規(guī)模、需求和個(gè)人偏好而異。以下是一個(gè)推薦的項(xiàng)目結(jié)構(gòu)，基于多年的生產(chǎn)經(jīng)驗(yàn)：

project/

├── api/

│   ├── models/

│   │   └── __init__.py

│   ├── routes/

│   │   └── home.py

│   ├── schemas/

│   │   └── __init__.py

│   ├── services/

│   │   └── __init__.py

│   └── __init__.py

├── tests/

│   ├── routes/

│   │   └── test_home.py

│   └── __init__.py

├── app.py

├── Pipfile

└── Pipfile.lock

模塊功能解析

1. models：定義數(shù)據(jù)模型，通常與數(shù)據(jù)庫表結(jié)構(gòu)相關(guān)。
2. routes：定義應(yīng)用程序的 URI 和資源操作。
3. schemas：定義 API 的輸入輸出結(jié)構(gòu)，明確參數(shù)和返回?cái)?shù)據(jù)。
4. services：處理業(yè)務(wù)邏輯，與數(shù)據(jù)庫或其他服務(wù)交互。

在 Flask 中，使用藍(lán)圖（Blueprint）可以更好地組織路由。例如：

from flask import Blueprint

home_api = Blueprint('home', __name__, url_prefix='/home-service')@home_api.route('/')
def welcome():
    return {"message": "Welcome to the Flask Starter Kit"}, 200

通過藍(lán)圖，可以輕松管理路由的分組和前綴。

從代碼構(gòu)建文檔

構(gòu)建 API 后，開發(fā)者需要清晰的文檔來指導(dǎo)使用。使用 Swagger 可以自動(dòng)生成交互式文檔。以下是一個(gè)簡(jiǎn)單的示例：

from flasgger import swag_from

@home_api.route('/')
@swag_from({
    'responses': {
        200: {
            'description': 'Welcome to the Flask Starter Kit',
            'schema': {
                'type': 'object',
                'properties': {
                    'message': {'type': 'string'}
                }
            }
        }
    }
})
def welcome():
    """API 歡迎端點(diǎn)
    ---
    返回歡迎信息。
    """
    return {"message": "Welcome to the Flask Starter Kit"}, 200

通過結(jié)合 Flask 和 Flasgger，可以快速生成動(dòng)態(tài)文檔，提升開發(fā)效率。

測(cè)試驅(qū)動(dòng)開發(fā)（TDD）

測(cè)試是確保代碼質(zhì)量的重要手段。采用測(cè)試驅(qū)動(dòng)開發(fā)（TDD）可以顯著提高開發(fā)效率和代碼可靠性。TDD 的基本流程如下：

1. 編寫測(cè)試：

   def test_sum():
      assert sum_two_numbers(3, 5) == 8

2. 運(yùn)行測(cè)試（失敗）：由于函數(shù)尚未實(shí)現(xiàn)，測(cè)試會(huì)失敗。

3. 實(shí)現(xiàn)功能：

   def sum_two_numbers(a, b):
      return a + b

4. 重新運(yùn)行測(cè)試（通過）：驗(yàn)證功能是否滿足需求。

通過這種方式，開發(fā)者可以在開發(fā)過程中快速發(fā)現(xiàn)并修復(fù)問題。

結(jié)論

在 API 開發(fā)中，最佳實(shí)踐因項(xiàng)目而異，但以下原則可以幫助您構(gòu)建高效、易維護(hù)的 API：

• 在命名上保持一致性。
• 通過模塊化結(jié)構(gòu)組織代碼。
• 利用工具從代碼生成文檔。
• 采用測(cè)試驅(qū)動(dòng)開發(fā)確保代碼質(zhì)量。

希望本文能為您的 Flask API 開發(fā)提供有價(jià)值的參考！

原文鏈接: https://auth0.com/blog/best-practices-for-flask-api-development/