FastAPI 整合 Pydantic 資料驗證與應用

– 7 分鐘閱讀

FastAPI 框架與 Pydantic 資料驗證函式庫的結合，簡化了資料模型定義和驗證流程，提升了 API 開發效率。Pydantic 的 BaseModel 能夠清晰地定義資料結構，並透過 orm_mode 與 SQLAlchemy 等 ORM 工具無縫銜接，方便地將資料函式庫物件轉換為 Pydantic 模型例項。此外，Field() 函式允許開發者自定義欄位驗證規則，例如設定數值範圍或字串長度限制，而 validator 裝飾器則能實作更複雜的驗證邏輯。Pydantic 也提供了 HttpUrl、EmailStr、SecretStr 等特殊資料型別，簡化了對特定格式資料的處理。除了 API 開發，FastAPI 也支援 HTML 渲染，可以透過 HTMLResponse 物件傳回 HTML 內容。

Pydantic 與 FastAPI 的整合應用

在 FastAPI 中，Pydantic 的 BaseModel 被廣泛用於定義資料模型，用以處理請求主體（Request Body）。本章節將探討如何使用 Pydantic 模型與 FastAPI 進行無縫整合，並展示其強大的資料驗證功能。

從 SQLAlchemy 到 Pydantic 模型轉換

在現代化的應用程式架構中，資料函式庫操作與資料驗證是兩個不可或缺的環節。SQLAlchemy 是 Python 中著名的 ORM（Object-Relational Mapping）工具，而 Pydantic 則專注於資料驗證與解析。兩者的結合能夠提供強大的資料處理能力。

ORM 模型定義

首先，我們定義一個 SQLAlchemy 的 ORM 模型 ProductORM：

from sqlalchemy import Column, Integer, String, Float

class ProductORM(Base):
    __tablename__ = "products"
    prodId = Column(Integer, primary_key=True)
    prodName = Column(String(63), unique=True)
    price = Column(Float)
    stock = Column(Integer)

Pydantic 模型定義與轉換

接著，我們定義對應的 Pydantic 模型 Product：

from pydantic import BaseModel

class Product(BaseModel):
    prodId: int
    prodName: str
    price: float
    stock: int

    class Config:
        orm_mode = True

Pydantic 的 from_orm() 方法允許我們從 ORM 物件建立 Pydantic 模型例項：

prod_alchemy = ProductORM(
    prodId=1,
    prodName='Ceiling Fan',
    price=2000,
    stock=50
)

product = Product.from_orm(prod_alchemy)

內容解密：

  1. ProductORM 是 SQLAlchemy 定義的 ORM 模型，用於資料函式庫操作。
  2. Product 是 Pydantic 模型，主要用於資料驗證和轉換。
  3. from_orm() 方法實作了從 ORM 物件到 Pydantic 模型的轉換。
  4. 這種轉換機制使得資料函式庫物件可以直接轉換為具有驗證功能的 Pydantic 模型。

Pydantic 欄位自定義

Pydantic 允許我們使用 Field() 函式來自定義欄位行為，類別似於 FastAPI 中的 Path()、Query() 和 Body()。例如，我們可以對數字欄位應用 gt、ge、lt、le 等驗證條件，對字串欄位使用 min_length 和 max_length 進行長度限制。

自定義 Student 模型

from pydantic import BaseModel, Field
from typing import Dict

class Student(BaseModel):
    StudentID: int
    name: str
    subjects: Dict[str, int]

    class Config:
        schema_extra = {
            "example": {
                "StudentID": 1,
                "name": "John Doe",
                "subjects": {"Math": 90, "Science": 85}
            }
        }

FastAPI 中的應用

app = FastAPI()

@app.post("/student")
async def addnew(student: Student):
    return student

內容解密：

  1. 使用 Field() 可以對欄位新增額外的驗證條件。
  2. 在 Student 模型中，subjects 欄位被定義為字典型別，用於儲存科目成績。
  3. 在 FastAPI 端點中使用 Pydantic 模型作為引數型別，能夠自動進行資料驗證。

Pydantic 自定義資料型別

Pydantic 提供了一系列自定義資料型別，如 HttpUrl、EmailStr 和 SecretStr，用於處理特定格式的資料。

Employee 模型範例

from pydantic import BaseModel, SecretStr, HttpUrl, Json

class Employee(BaseModel):
    ID: str
    pwd: SecretStr
    salary: int
    details: Json
    FBProfile: HttpUrl

使用範例

@app.post("/employee")
async def addnew(emp: Employee):
    return emp

請求主體範例：

{
    "ID": "A001",
    "pwd": "asdf",
    "salary": 25000,
    "details": "{\"Designation\": \"Manager\", \"Branch\": \"Mumbai\"}",
    "FBProfile": "https://www.facebook.com/dummy.employee/"
}

內容解密：

  1. SecretStr 用於儲存敏感資訊，如密碼，在輸出時會被遮蔽。
  2. HttpUrl 確保提供的 URL 符合 HTTP/HTTPS 格式要求。
  3. Json 用於解析 JSON 字串，並可進一步轉換為指定的資料型別。
  4. 自動化的資料驗證是 Pydantic 的核心優勢，能夠在處理請求資料時提供強大的錯誤檢查功能。

資料驗證的重要性

Pydantic 的強大之處在於其內建的資料驗證機制。當輸入資料不符合定義的模型結構時，Pydantic 能夠提供詳細的錯誤資訊。

錯誤處理範例

當 details 欄位的 JSON 值錯誤時，伺服器會傳回如下錯誤回應：

{
    "detail": [
        {
            "loc": [
                "body",
                "details"
            ],
            "msg": "JSON object must be str, bytes or bytearray",
            "type": "type_error.json"
        }
    ]
}

內容解密：

  1. 自動化的驗證機制能夠捕捉並回報輸入資料的錯誤。
  2. 詳細的錯誤資訊有助於開發者快速定位問題所在。
  3. 這種機制大大提高了 API 的健壯性和開發效率。

隨著 FastAPI 和 Pydantic 的不斷發展，未來將會有更多進階功能和最佳實踐出現。開發者應持續關注相關更新，以便更好地利用這些強大的工具提升應用程式的品質和開發效率。

最佳實踐建議

  1. 充分利用 Pydantic 的驗證功能：在定義模型時，應盡可能使用 Pydantic 提供的各種驗證選項，以確保資料的正確性。
  2. 結合 SQLAlchemy 使用：在需要操作資料函式庫的應用中，將 SQLAlchemy 的 ORM 功能與 Pydantic 的驗證功能結合使用，能夠大大簡化開發流程。
  3. 善用自定義資料型別：Pydantic 提供了一系列實用的自定義資料型別，如 HttpUrl 和 SecretStr，能夠幫助開發者處理特定格式的資料。

透過遵循這些最佳實踐，開發者能夠在 FastAPI 專案中充分發揮 Pydantic 的優勢，開發出更為健壯和高效的應用程式。

使用Pydantic進行請求體驗證與自定義驗證

在FastAPI中，Pydantic扮演著至關重要的角色，用於定義請求體的結構並進行資料驗證。本章節將探討Pydantic模型的使用、自定義驗證以及巢狀模型的建立。

請求體驗證

FastAPI利用Pydantic模型來解析和驗證請求體中的資料。當客戶端傳送POST請求時，請求體中的JSON資料會被自動轉換為Pydantic模型定義的Python物件。

內建驗證

Pydantic提供了多種內建的驗證功能，例如檢查欄位型別、檢查必填欄位等。以下是一個簡單的範例（Listing 3-20），展示瞭如何定義一個名為Employee的Pydantic模型：

from pydantic import BaseModel, SecretStr, HttpUrl
from typing import Dict

class Employee(BaseModel):
    ID: str
    pwd: SecretStr
    salary: int
    details: Dict
    FBProfile: HttpUrl

自定義驗證

除了內建的驗證功能，Pydantic還允許開發者自定義驗證邏輯。透過使用@validator裝飾器，可以為特定的欄位新增自定義的驗證規則。例如，以下程式碼（Listing 3-22）展示瞭如何為ID欄位新增驗證邏輯，確保其值為英數字元：

from pydantic import BaseModel, validator

class Employee(BaseModel):
    ID: str
    # ... 其他欄位定義

    @validator('ID')
    def alphanum(cls, x):
        if not x.isalnum():
            raise ValueError('Must be alphanumeric')
        return x

巢狀模型

Pydantic模型支援巢狀結構，可以將一個模型作為另一個模型的欄位。這種設計使得複雜的資料結構可以被有效地建模。例如，以下程式碼（Listing 3-25至Listing 3-27）展示瞭如何定義巢狀模型，包括Suppliers、Products和Customers：

from pydantic import BaseModel
from typing import List

class Suppliers(BaseModel):
    supplierID: int
    supplierName: str

class Products(BaseModel):
    productID: int
    productName: str
    price: int
    suppler: List[Suppliers]

class Customers(BaseModel):
    custID: int
    custName: str
    products: List[Products]

FastAPI中的範本渲染

FastAPI主要用於開發API，但也可以用於構建傳統的網頁應用。本章節將介紹如何使用範本引擎在FastAPI中渲染網頁。

HTML回應

預設情況下，FastAPI的操作函式傳回JSON型別的回應。但是，可以透過傳回HTMLResponse物件來渲染HTML內容。以下是一個簡單的範例（Listing 4-2），展示瞭如何傳回一個包含"Hello World!“字串的HTML頁面：

from fastapi import FastAPI, Response

app = FastAPI()

@app.get("/")
async def index():
    ret = '''
    <html>
    <body>
    <h2>Hello World!</h2>
    </body>
    </html>
    '''
    return Response(content=ret, media_type="text/html")

結語

本章節介紹了Pydantic模型在FastAPI中的應用，包括請求體驗證、自定義驗證和巢狀模型的建立。同時，也簡要介紹瞭如何在FastAPI中使用範本引擎渲染網頁。在接下來的章節中，我們將進一步探討如何在FastAPI中使用Jinja範本引擎，以及如何處理靜態資源和表單資料。

章節重點整理：

  1. Pydantic模型的使用：介紹瞭如何定義Pydantic模型，以及如何利用Pydantic進行請求體驗證。
  2. 自定義驗證：展示瞭如何使用@validator裝飾器進行自定義驗證。
  3. 巢狀模型：介紹瞭如何建立巢狀的Pydantic模型，以處理複雜的資料結構。
  4. FastAPI中的範本渲染：簡要介紹瞭如何在FastAPI中傳回HTML回應。

這些內容為開發者在FastAPI中處理請求體和渲染網頁提供了基礎。接下來的章節將進一步探討相關主題，包括使用Jinja範本引擎、處理靜態資源和表單資料等。

在未來的章節中，我們將繼續探討FastAPI的其他高階功能，包括但不限於：

  • Jinja範本引擎的使用：將介紹如何在FastAPI中整合Jinja範本引擎，以實作更靈活的網頁渲染。
  • 靜態資源處理：將討論如何處理靜態資源，如圖片、CSS和JavaScript檔案。
  • 表單資料處理：將介紹如何在FastAPI中處理來自客戶端的表單資料。

這些主題將進一步擴充套件開發者在FastAPI中的技能，使其能夠構建更為複雜和功能豐富的網頁應用。

參考資料與延伸閱讀

對於希望深入瞭解Pydantic和FastAPI的讀者，可以參考以下資源：

  • Pydantic官方檔案：提供了Pydantic模型的詳細介紹和使用範例。
  • FastAPI官方檔案：包含了FastAPI的全面，包括請求處理、範本渲染等主題。

透過這些資源，讀者可以獲得更深入的理解和實踐經驗，從而更好地應用Pydantic和FastAPI於實際專案中。

玄貓

玄貓

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