FastAPI構建API檔案與引數處理

FastAPI 框架簡化了 API 開發流程，自動生成互動式檔案是其一大亮點。透過整合 Swagger UI 和 Redoc，開發者能輕鬆瀏覽 API 規格，測試各個端點。此外，FastAPI 藉助 Pydantic 模型，提供強大的引數驗證功能，涵蓋路徑引數、查詢引數和請求體，確保 API 的輸入資料符合預期格式，減少錯誤處理成本。文章也示範瞭如何定義選用引數、巢狀模型，以及處理驗證錯誤，讓 API 設計更具彈性且穩固。

使用 FastAPI 建構 API 檔案與引數處理

API 檔案自動生成：Swagger 與 Redoc

FastAPI 提供了自動生成 API 檔案的功能，主要透過 Swagger UI 和 Redoc 實作。這些工具能夠將 API 的結構和細節以使用者友好的介面呈現，方便開發者理解和使用 API。

Swagger UI

Swagger UI 是其中一個用於視覺化 API 檔案的工具。啟動 Uvicorn 伺服器後，可以透過存取 http://localhost:8000/docs 來檢視 Swagger 檔案。Swagger 檔案中列出了所有的路徑操作（path operations）及其對應的函式，並且提供了一個搜尋欄以方便查詢特定的 API 端點。

Redoc

另一個類別似的工具是 Redoc，可以透過存取 http://localhost:8000/redoc 來檢視。Redoc 提供了一個乾淨且易於閱讀的介面，同樣列出了所有的路徑操作及其詳細資訊。

from fastapi import FastAPI

app = FastAPI()

@app.get("/")
async def index():
    return {"message": "Welcome to the FastAPI application"}

@app.get("/employee/{name}/{age}")
async def get_employee(name: str, age: int):
    return {"name": name, "age": age}

JSON Schema

Swagger 和 Redoc 實際上是透過解析 API 的 JSON 表示來生成檔案。這個 JSON 表示遵循 OpenAPI 規範，可以透過存取 http://localhost:8000/openapi.json 來檢視原始的 OpenAPI schema。

{
  "openapi": "3.0.2",
  "info": {
    "title": "FastAPI",
    "version": "0.1.0"
  },
  "paths": {
    "/": {
      "get": {
        "summary": "Index",
        "operationId": "index__get",
        "responses": {
          "200": {
            "description": "Successful Response",
            "content": {
              "application/json": {
                "schema": {}
              }
            }
          }
        }
      }
    }
  }
}

路徑引數（Path Parameters）

在 HTTP 請求中，URL 的路徑部分可以用於傳遞引數。FastAPI 允許開發者使用路徑引數來捕捉 URL 中的變數部分。例如，對於 URL http://mysite.com/employee/Rahul/20，可以使用如下的路徑操作來處理：

from fastapi import FastAPI

app = FastAPI()

@app.get("/employee/{name}/{age}")
async def get_employee(name: str, age: int):
    return {"name": name, "age": age}

使用型別提示（Type Hints）

在上述範例中，name 和 age 被定義為路徑引數，並且使用了型別提示來指定它們的資料型別。name 被指定為 str 型別，而 age 被指定為 int 型別。這樣，FastAPI 就能夠根據型別提示自動進行資料型別的轉換。

型別解析（Type Parsing）

當客戶端傳送請求時，FastAPI 會根據型別提示嘗試將路徑引數轉換為指定的型別。如果轉換失敗，FastAPI 將傳回一個錯誤訊息。例如，如果存取 http://localhost:8000/employee/Rahul/Kumar，由於 age 不是一個整數，FastAPI 將傳回一個錯誤訊息：

{
  "detail": [
    {
      "loc": [
        "path",
        "age"
      ],
      "msg": "value is not a valid integer",
      "type": "type_error.integer"
    }
  ]
}

查詢引數（Query Parameters）

除了路徑引數之外，FastAPI 也支援查詢引數。如果一個路徑操作函式定義了額外的引數，而這些引數並不是路徑的一部分，那麼它們就會被視為查詢引數。

from fastapi import FastAPI

app = FastAPI()

@app.get("/employee/{name}")
async def get_employee(name: str, age: int):
    return {"name": name, "age": age}

在上述範例中，age 被視為一個查詢引數。因此，當存取 /employee/Rahul?age=20 時，age 的值將被正確解析。

隨著 FastAPI 的不斷發展，未來可能會出現更多增強功能，例如對更多檔案生成工具的支援、更靈活的引數處理機制等。開發者可以期待這些新功能進一步簡化 API 的開發和管理流程。

安全性考量

在使用 FastAPI 建構 API 時，需要注意安全性問題。例如，應當對輸入的引數進行適當的驗證和清理，以避免潛在的安全風險。此外，使用 HTTPS 等安全協定也是保護資料傳輸安全的重要措施。

FastAPI 中的引數處理與驗證

前言

在現代的 Web 開發中，API 的設計和實作需要考慮到各種引數的處理和驗證。FastAPI 作為一個現代化的 Python Web 框架，提供了強大的引數處理和驗證功能。本文將探討 FastAPI 中的路徑引數、查詢引數以及它們的驗證機制。

路徑引數與查詢引數

在設計 API 時，我們經常需要從 URL 中提取資訊。FastAPI 支援兩種主要的引數型別：路徑引數（Path Parameters）和查詢引數（Query Parameters）。

路徑引數

路徑引數是 URL 路徑的一部分，用於識別特定的資源。例如，在 URL http://localhost:8000/employee/Rahul 中，Rahul 就是一個路徑引數。

from fastapi import FastAPI

app = FastAPI()

@app.get("/employee/{name}")
async def get_employee(name: str):
    return {"name": name}

查詢引數

查詢引數則是附加在 URL 後面的鍵值對，用於提供額外的資訊。例如，在 URL http://localhost:8000/employee/Rahul?age=20 中，age=20 就是一個查詢引數。

from fastapi import FastAPI

app = FastAPI()

@app.get("/employee/{name}")
async def get_employee(name: str, age: int = 20):
    return {"name": name, "age": age}

選用引數

FastAPI 允許開發者定義選用的查詢引數。這可以透過設定預設值或使用 Optional 型別來實作。

設定預設值

透過設定預設值，可以讓查詢引數變成選用。

from fastapi import FastAPI

app = FastAPI()

@app.get("/employee/{name}")
async def get_employee(name: str, age: int = 20):
    return {"name": name, "age": age}

使用 Optional 型別

使用 Optional 型別可以明確表示引數是選用的。

from typing import Optional
from fastapi import FastAPI

app = FastAPI()

@app.get("/employee/{name}")
async def get_employee(name: str, age: Optional[int] = None):
    return {"name": name, "age": age}

引數順序

雖然路徑引數在 URL 中位於查詢引數之前，但在函式定義中，它們的順序可以是任意的。FastAPI 會自動根據 URL 結構進行正確的匹配。

from typing import Optional
from fastapi import FastAPI

app = FastAPI()

@app.get("/employee/{name}/branch/{branch_id}")
async def get_employee(name: str, brname: str, branch_id: int, age: Optional[int] = None):
    employee = {'name': name, 'Branch': brname, 'Branch ID': branch_id, 'age': age}
    return employee

引數驗證

為了確保 API 的穩定性和安全性，FastAPI 提供了強大的引數驗證功能。開發者可以透過 Path 和 Query 物件來定義驗證規則。

字串長度驗證

可以對字串型別的引數進行最小和最大長度驗證。

from fastapi import FastAPI, Path, Query
from typing import Optional

app = FastAPI()

@app.get("/employee/{name}/branch/{branch_id}")
async def get_employee(branch_id: int, name: str = Path(None, min_length=10), brname: str = Query(None, min_length=5, max_length=10), age: Optional[int] = None):
    employee = {'name': name, 'Branch': brname, 'Branch ID': branch_id, 'age': age}
    return employee

錯誤處理

當驗證失敗時，FastAPI 會傳回詳細的錯誤資訊。這有助於客戶端理解錯誤的原因並進行相應的處理。

{
    "detail": [
        {
            "loc": ["path", "name"],
            "msg": "ensure this value has at least 10 characters",
            "type": "value_error.any_str.min_length",
            "ctx": {"limit_value": 10}
        },
        {
            "loc": ["query", "brname"],
            "msg": "ensure this value has at most 10 characters",
            "type": "value_error.any_str.max_length",
            "ctx": {"limit_value": 10}
        }
    ]
}

隨著 Web 開發的不斷進步，FastAPI 將繼續演進，提供更多強大的功能和改進。開發者應該持續關注 FastAPI 的最新發展，以充分利用其提供的各種優勢。

  graph LR
    A[開始] --> B[定義路由]
    B --> C[處理路徑引數]
    C --> D[處理查詢引數]
    D --> E[進行引數驗證]
    E --> F[傳回結果或錯誤資訊]

圖表翻譯： 此圖示展示了 FastAPI 處理請求的基本流程。首先定義路由，然後處理路徑引數和查詢引數，接著進行引數驗證，最後根據驗證結果傳回相應的結果或錯誤資訊。

詳細解說

定義路由：使用 @app.get() 或其他相關裝飾器定義 API 的路由。
處理路徑引數：在路由中定義路徑引數，並在函式中進行處理。
處理查詢引數：定義查詢引數，並在函式中進行處理。可以設定預設值或使用 Optional 型別。
進行引數驗證：使用 Path 和 Query 物件對引數進行驗證。可以設定最小和最大長度等驗證規則。
傳回結果或錯誤資訊：根據驗證結果，傳回正確的資料或詳細的錯誤資訊。

透過以上步驟，FastAPI 提供了一個強大且靈活的方式來處理 API 請求，確保了應用程式的穩定性和安全性。

使用FastAPI進行請求體驗證與處理

在前一章中，我們探討瞭如何使用FastAPI處理客戶端GET請求中的路徑引數和查詢引數。本章將重點介紹如何在客戶端的HTTP請求中包含所需資料作為請求體。

POST方法

網頁瀏覽器軟體只能透過GET方法傳送請求。我們知道GET請求用於從HTTP伺服器檢索一個或多個資源。請求URL中的路徑和/或查詢引數作為篩選器，用於取得特定資源的資料。

為什麼使用POST方法？

POST方法用於向伺服器傳送資料，以建立或更新資源。這種方法通常用於提交表單資料、上傳檔案等。

請求體引數

在FastAPI中，可以使用Pydantic模型來定義請求體的結構。Pydantic是一個用於構建資料模型的Python函式庫，它提供了資料驗證和解析功能。

使用Pydantic定義資料模型

Pydantic模型是用於定義請求體結構的核心。下面是一個簡單的例子，展示瞭如何使用Pydantic定義一個使用者模型：

from pydantic import BaseModel

class User(BaseModel):
    name: str
    age: int
    email: str

    class Config:
        schema_extra = {
            "example": {
                "name": "John Doe",
                "age": 30,
                "email": "john@example.com"
            }
        }

內容解密：

User類別繼承自BaseModel，定義了一個具有name、age和email屬性的使用者模型。
schema_extra屬性用於為模型提供一個示例，這將顯示在API檔案中。

請求體驗證

FastAPI使用Pydantic模型自動驗證請求體。如果請求體不符合模型定義，FastAPI將傳回一個錯誤回應。

from fastapi import FastAPI
from pydantic import BaseModel

app = FastAPI()

class User(BaseModel):
    name: str
    age: int
    email: str

@app.post("/users/")
async def create_user(user: User):
    return user

內容解密：

create_user函式接受一個User型別的引數user。
FastAPI自動將請求體解析為User模型，並進行驗證。
如果驗證成功，函式傳回使用者資料。

巢狀模型

Pydantic支援巢狀模型，這允許您建立複雜的資料結構。

from pydantic import BaseModel

class Address(BaseModel):
    street: str
    city: str
    state: str
    zip_code: str

class User(BaseModel):
    name: str
    age: int
    email: str
    address: Address

內容解密：

Address模型定義了一個具有地址相關屬性的模型。
User模型現在包含了一個address屬性，其型別為Address。

請求體驗證與錯誤處理

當請求體不符合Pydantic模型定義時，FastAPI將傳回一個錯誤回應，指示驗證失敗的原因。

{
    "detail": [
        {
            "loc": ["body", "name"],
            "msg": "field required",
            "type": "value_error.missing"
        }
    ]
}

內容解密：

錯誤回應指示在請求體中缺少了name欄位。
loc屬性指示錯誤的位置，在本例中是請求體中的name欄位。

玄貓

技術愛好者，專注於分享程式開發、雲端技術與 AI 應用的心得體會。