跳轉到

FastAPI 中間件基礎

什麼是中間件？

中間件（Middleware）是一個軟體設計模式，在 Web 應用程序中，它位於客戶端請求和伺服器處理之間，能夠攔截、處理和修改請求和響應。中間件提供了一種機制，允許開發者在不修改核心應用邏輯的情況下，添加額外功能或處理流程。

中間件的核心特點：

  • 可插拔性：中間件可以輕鬆添加或移除，不影響應用的其他部分
  • 鏈式處理：多個中間件可以按順序組合使用
  • 橫切關注點：處理跨多個請求的共同邏輯（如日誌、認證等）
  • 非侵入性：不需要修改現有的路由處理函數

FastAPI 中的中間件

FastAPI 基於 Starlette 框架構建，因此繼承了 Starlette 的中間件系統。在 FastAPI 中，中間件是一個接收請求並返回響應的函數或類，可以在請求到達路由處理函數之前或響應返回客戶端之前執行操作。

from fastapi import FastAPI, Request
from fastapi.responses import Response

app = FastAPI()

@app.middleware("http")
async def example_middleware(request: Request, call_next):
    # 在請求處理前的邏輯
    print("處理請求前...")

    # 調用下一個中間件或路由處理函數
    response = await call_next(request)

    # 在響應返回前的邏輯
    print("處理響應前...")

    return response

中間件工作原理

FastAPI 中間件遵循 ASGI（Asynchronous Server Gateway Interface）規範，支持同步和異步處理模式。中間件的工作原理可以概括為：

  1. 接收客戶端請求
  2. 執行前置處理邏輯（如請求驗證、日誌記錄等）
  3. 將請求傳遞給下一個中間件或路由處理函數
  4. 接收路由處理函數的響應
  5. 執行後置處理邏輯（如響應修改、添加頭信息等）
  6. 返回最終響應給客戶端

中間件參數解析：

  • request：包含當前 HTTP 請求的所有信息
  • call_next：一個函數，用於調用下一個中間件或路由處理函數

請求-響應生命週期

在 FastAPI 應用中，一個完整的請求-響應生命週期如下：

客戶端請求 → ASGI 伺服器 → 中間件 1 → 中間件 2 → ... → 路由處理函數 → ... → 中間件 2 → 中間件 1 → 客戶端響應

值得注意的是，中間件的執行順序遵循「洋蔥模型」：

  1. 中間件按註冊順序執行前置處理邏輯
  2. 路由處理函數執行
  3. 中間件按註冊的反序執行後置處理邏輯

中間件與依賴注入的區別

FastAPI 提供了兩種主要機制來實現橫切關注點：中間件和依賴注入。它們的主要區別在於：

特性 中間件 依賴注入
作用範圍 全局或特定路由組 特定路由或路由組
執行時機 請求進入和響應返回時 路由處理函數執行前
訪問路由信息 有限 完整
修改響應 可以 有限
適用場景 日誌、CORS、壓縮等 驗證、權限檢查等

何時使用中間件？

中間件適合以下場景：

  • 全局操作：需要對所有或大部分請求進行處理
  • 請求/響應修改：需要修改請求或響應的內容
  • 橫切關注點：處理與業務邏輯無關的技術性需求
  • 性能監控：記錄請求處理時間
  • 錯誤處理：捕獲並處理全局異常

總結

中間件是 FastAPI 應用中不可或缺的組件，它提供了一種優雅的方式來處理跨多個請求的共同邏輯。通過理解中間件的基本概念和工作原理，您可以更有效地設計和實現 FastAPI 應用，使其更加模塊化、可維護和可擴展。