【🔒 Python API框架篇 - FastAPI】Ep.2 資料驗證與文檔範例生成
API是我們與其他系統介接的標準化規格， 那一份好的規格勢必要能夠達到引導與驗證的作用， 避免對方介接錯誤， 引發後續的災難性損失， 因此這一章節就是要教我們如何定義每個API的欄位怎麼填？ 資料型態是什麼？ 以及如何生成API文件。
我們在「【🔒 Python API框架篇 - FastAPI】Ep.1 啟航」稍微帶大家認識了FastAPI這個框架， 它讓我們快速的架設一個API服務， 並提供了許多標準化功能， 只要照著規範走就能快速的開發出來， 那這個章節我們主要介紹的是「資料驗證」、「資料綱要」這兩個部份， 其中扮演重要的套件庫角色的便是「pydantic」這套工具， 就讓我們來好好的認識一番吧！
它有以下的功能：
- 資料驗證：驗證輸入資料是否符合定義的格式或類型。
- 數據模型管理：將不規範的輸入資料轉換為 Python 資料類型，並提供類型提示（Type Hints）。
- 自動轉換：將不同類型的資料（例如字串到日期、整數到浮點數）自動轉換。
- 錯誤處理：提供清晰的錯誤訊息，幫助開發者快速定位和解決資料問題。
安裝套件
pip install fastapi uvicorn
這裡我們可能會覺得奇怪， 為什麼不用裝pydantic呢？ 主要是因為這個套件已經被整合到fastapi裡面的其中一個依賴了， 因此我們安裝fastapi時就會自動安裝pydantic了。
一個簡單的使用範例
我們可以發現到， 雖然id=”123”是字串的形式帶入， 但由於我們的資料模型定義為整數， 因此會自動幫我們進行轉換。
from pydantic import BaseModel
# 類別User繼承自BaseModel的特性, pydantic會自動根據我們的型別設計進行轉換及驗證。
class User(BaseModel):
id: int
name: str
is_active: bool = True
# 驗證與轉換輸入資料
user_data = {"id": "123", "name": "Alice"}
user = User(**user_data)
print(user) # User(id=123, name='Alice', is_active=True)
print(user.dict()) # {'id': 123, 'name': 'Alice', 'is_active': True}
當驗證發生錯誤時
根據上面的案例進行一些修改， 我們將id的部份改為error字串， 看看會發生什麼事情？
from pydantic import BaseModel
class User(BaseModel):
id: int
name: str
is_active: bool = True
# 驗證與轉換輸入資料
user_data = {"id": "error", "name": "Alice"}
user = User(**user_data)
print(user) # User(id=123, name='Alice', is_active=True)
print(user.dict()) # {'id': 123, 'name': 'Alice', 'is_active': True}
這段程式碼將發生驗證錯誤， 並且明確的告訴我們 id是整數， 我們卻帶入字串的資料。
與FastAPI整合
這是最關鍵的部份， FastAPI在資料及文檔生成的部份整合了pydantic的套件， 幫助我們在產品的文件化、資料的驗證上更加的具有品質， 減少錯誤的認知開發與錯誤的輸入導致系統當機， 接下來我們試著來寫一段資料模型定義與驗證的程式碼：
from fastapi import FastAPI
from pydantic import BaseModel
app = FastAPI()
# 定義 Pydantic 模型
class Item(BaseModel):
name: str
price: float
is_offer: bool = False
# 建立 POST 路由來處理資料
@app.post("/items/")
async def create_item(item: Item):
return {"message": "Item created successfully!", "item": item}
# 建立 GET 路由來取得資料
@app.get("/items/{item_id}")
async def read_item(item_id: int, q: str = None):
return {"item_id": item_id, "q": q}
接著我們來啟動服務：
uvicorn test:app --reload --port 9880 --host 0.0.0.0
我們可以看到 http://localhost:9880/docs 裡面會包含我們所定義的資料綱要及型別。
接著我們嘗試依照範例去請求！
透過這樣的互動方式， 讓我們更快的理解API如何使用及設計的含意。
結語
過往我們在設計API文件時， 通常都會草擬一份文件並討論之後再開始進行開發， 但這樣的過程難免會有設計與開發不一致的情況， 且來來回回都不知道浪費多少時間去了， 因此現代的開發框架通常結合程式碼進行文檔的生成， 及欄位的範例設計， 讓註解、文件、驗證達到三位一體的效果， 省去許多整合的時間。
當然 pydantic 不僅只有在FastAPI發揮功能而已， 它也可以替我們的環境變數配置進行資料設計及驗證， 歡迎參考我們的：【💊 Python的解憂錦囊】既能管理環境變數又能驗證的pydantic
