Pydantic ：資料驗證的超強幫手
Pydantic 是 Python 中強型別資料驗證與處理的標準工具，特別適合用於 API 的請求 / 回應資料結構驗證。
1️⃣ 資料模型定義（BaseModel）
基本用法：定義一個「資料模型」，自動提供初始化、型別檢查、序列化功能。
from pydantic import BaseModel使用方式：
class User(BaseModel):
id: int
name: str
is_active: bool = True # 預設值
user = User(id=1, name="Alice")
print(user.model_dump()) # {'id': 1, 'name': 'Alice', 'is_active': True}
2️⃣ 自動驗證（輸入時）
自動驗證資料類型與格式：
user = User(id="123", name="Bob") # id 自動轉換為 int
print(user.id) # 123
User(id="not_a_number", name="Bob")
# 🚨 ValueError: value is not a valid integer
3️⃣ 輸出轉換（dict / JSON / model_copy）
print(user.model_dump()) # 輸出 Python dict
print(user.model_dump_json()) # 輸出 JSON 字串
new_user = user.model_copy(update={"name": "Charlie"})
4️⃣ 自訂欄位限制（Field）
使用 Field() 來指定：
- 預設值 / 必填
- 描述（給 API 文件看）
- 長度、大小範圍
- 正則表達式
- 限制值域
from pydantic import BaseModel, Field
class Product(BaseModel):
name: str = Field(..., min_length=2, max_length=50, description="商品名稱")
price: float = Field(..., gt=0, description="價格需大於 0")
tag: str = Field(default="general", pattern="^[a-z_]+$")
示例輸入：
Product(name="A", price=-5)
# 🚨 name 太短, price < 0 會報錯
print(Product(name="Apple", price=10.5, tag="fruit").model_dump())
# {'name': 'Apple', 'price': 10.5, 'tag': 'fruit'}
5️⃣ Email、URL、IPv4、Decimal...：特化型別驗證
Pydantic 提供大量內建型別：
from typing import Annotated
from pydantic import BaseModel, EmailStr, HttpUrl, IPvAnyAddress, condecimal
class Contact(BaseModel):
email: EmailStr
website: HttpUrl
ip: IPvAnyAddress
score: Annotated[float, condecimal(gt=0, lt=10)]
6️⃣ Optional / Union（選填與多型別）
from typing import Optional, Union
class Example(BaseModel):
note: Optional[str] # 可以是 str 或 None
value: Union[int, str] # 可以是 int 或 str
example = Example(note=None, value=42)
print(example.model_dump()) # {'note': None, 'value': 42}
7️⃣ 巢狀模型（Nested Models）
class Address(BaseModel):
city: str
zipcode: str
class User(BaseModel):
name: str
address: Address
data = {
"name": "Tom",
"address": {
"city": "Taipei",
"zipcode": "100"
}
}
user = User(**data)
print(user.model_dump()) # {'name': 'Tom', 'address': {'city': 'Taipei', 'zipcode': '100'}}
print(user.address.city) # 'Taipei'
print(user.address.zipcode) # '100'
# 直接使用嵌套模型
print(user.model_dump_json(indent=2)) # 美化的 JSON 輸出
# 嵌套模型的驗證
# user = User(name="Alice", address={"city": "New York", "zipcode": "10001"})
# print(user.model_dump()) # {'name': 'Alice', 'address': {'city': 'New York', 'zipcode': '10001'}}
8️⃣ 自訂欄位轉換（validator）
使用 @field_validator（v2）或 @validator（v1） 來自訂欄位邏輯：
from pydantic import BaseModel, field_validator
class User(BaseModel):
username: str
@field_validator("username")
@classmethod
def check_lowercase(cls, v):
if not v.islower():
raise ValueError("username 必須為小寫")
return v
# 使用小寫字母的 username
user = User(username="alice")
print(user.model_dump()) # {'username': 'alice'}
# 使用大寫字母的 username
try:
user = User(username="Alice")
except ValueError as e:
print(e) # username 必須為小寫
9️⃣ 模型設定（Config）
自訂模型的行為：
Pydantic v2 的設定方法：使用 model_config
from pydantic import BaseModel
class User(BaseModel):
name: str
age: int
model_config = {
"extra": "forbid", # 禁止多餘欄位
"str_strip_whitespace": True, # 自動去除字串空白
"populate_by_name": True, # 允許用欄位別名填值
}
# 使用 model_config 來設定模型行為
user = User(name="Alice", age=30)
print(user.model_dump()) # {'name': 'Alice', 'age': 30}
print(user.model_config) # {'extra': 'forbid', 'str_strip_whitespace': True, 'populate_by_name': True, 'validate_by_alias': True, 'validate_by_name': True}
常用設定選項說明（v2）
🔚 總結表格
此篇了解FastAPI最核心的兩大元件：Starlette、Pydantic的另一個Pydantic，Pydantic做為用來處理資料驗證、序列化與型別安全的模型管理工具，使用 Python 類別定義資料模型、自動進行型別轉換與資料驗證、整合 FastAPI 等框架處理 API 輸入/輸出資料、支援巢狀模型、欄位驗證、自訂邏輯等，是個還蠻完善的驗證與處理工具。
