?? Pydantic V2 入門與實戰(zhàn)指南（~=2.10.6 詳解）

適用于初學者到中級開發(fā)者，涵蓋核心概念、最佳實踐、版本控制策略及實際應用示例。
基于 Pydantic v2.10.6（當前穩(wěn)定版），面向現代 Python 項目開發(fā)。

一、pydantic~=2.10.6 是什么意思？—— 版本依賴的精準控制

? 語法解讀：~= 操作符（兼容性釋放，Compatible Release）

pydantic~=2.10.6

這是 PEP 440 定義的“兼容性釋放”操作符，含義如下：

~= 2.10.6 等價于：

>= 2.10.6, == 2.10.*

即：允許安裝 2.10.6 及之后所有小版本更新（如 2.10.7, 2.10.8...），但禁止升級到主版本大于 2 的版本（如 2.11、3.0）。

?? 舉例說明

?? 為什么使用 ~=？

• 避免因無意升級引入破壞性變更。
• 保留安全補?。ㄈ缧迯吐┒础⑿阅軆?yōu)化）。
• 在 CI/CD、生產部署中保障穩(wěn)定性。

?? 注意：雖然 2.10.* 范圍內理論上不會出問題，但建議定期審閱依賴更新日志，尤其是涉及 pydantic-core（底層 Rust 實現）的變動。

二、什么是 Pydantic？—— 數據驗證與配置管理的利器

?? 核心定位

Pydantic 是一個基于 Python 類型注解（Type Hints）構建的 數據驗證、設置管理、序列化 庫。

它讓開發(fā)者可以：

• 用簡潔的類定義數據模型；
• 自動完成類型校驗與轉換；
• 支持復雜嵌套結構與自定義邏輯；
• 無縫集成進 FastAPI、Docker 配置、爬蟲、數據庫等場景。

?? 適用場景一覽

?? 從 V1 到 V2：一次重大的演進

?? 總結：V2 更快、更一致、更安全，但需要遷移成本。

?? 官方遷移指南：Migration Guide

三、核心概念：BaseModel 與字段定義

3.1 基礎模型定義

所有模型均繼承自 BaseModel，字段通過類型注解聲明。

from pydantic import BaseModel

class User(BaseModel):
    id: int              # 必填字段（無默認值）
    name: str = "Guest"  # 可選字段（有默認值）
    age: int | None = None  # 可選字段（推薦寫法，等價于 `Optional[int]`）

?? 字段行為解析：

?? 重要提示：在 Python 3.10+ 中，int | None 是標準寫法；舊版可用 Optional[int]。

3.2 模型實例化與自動類型轉換（類型強制與協(xié)變）

Pydantic 支持在創(chuàng)建模型時進行智能類型轉換（coercion）：

user = User(id="123", name="Alice", age="20")
print(user.id)     # 123 (str -> int)
print(user.name)   # Alice
print(user.age)    # 20 (str -> int)

? 自動轉換規(guī)則（常見情況）

? 不支持的轉換

• "abc" → int ?（拋出錯誤）
• {"a": 1} → List[int] ?（結構不匹配）

3.3 錯誤處理：ValidationError

當輸入數據不符合規(guī)范時，會拋出 pydantic.ValidationError，附帶詳細字段級錯誤信息。

from pydantic import ValidationError

try:
    User(id="abc", name="X", age="xyz")
except ValidationError as e:
    print(e)

?? 輸出示例（簡化版）：

1 validation error for User
id
  Input should be a valid integer, unable to parse string as an integer (type=type_error.integer)

? 優(yōu)勢：錯誤信息精確到字段 + 原因，極大提升調試效率。

四、常用功能速查表（含高級用法）

4.1 字段約束：Field() 函數

Field() 用于為字段添加額外元信息，包括：

from typing import Annotated
from pydantic import BaseModel, Field

class Item(BaseModel):
    name: str = Field(..., min_length=1, max_length=100, description="商品名稱")
    price: float = Field(..., gt=0, description="價格必須 > 0")
    tags: list[str] = Field(default_factory=list, description="標簽列表")

?? 常用參數詳解

? 推薦寫法（結合 Annotated）：

from typing import Annotated
from pydantic import BaseModel, Field

class Model(BaseModel):
    count: Annotated[int, Field(gt=0)]  # 僅正整數

?? 注：Annotated 是 Python 3.9+ 引入的特性，用于附加元數據，是 V2 的推薦方式。

4.2 可選字段與默認值處理

from pydantic import BaseModel
from typing import Optional

class Config(BaseModel):
    debug: bool = False
    timeout: Optional[float] = None  # 可選浮點數
    # 或者更推薦：
    # timeout: float | None = None

? 推薦：使用 float | None 替代 Optional[float]（更直觀、更符合現代風格）

4.3 嵌套模型（復合結構）

from pydantic import BaseModel
from typing import List

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

class User(BaseModel):
    name: str
    addresses: List[Address]

# 構造實例
user = User(
    name="Alice",
    addresses=[
        {"city": "Beijing", "street": "Road 1"},
        {"city": "Shanghai", "street": "Road 2"},
    ],
)

? 動態(tài)解析：addresses 列表中的每個字典都會被自動轉換成 Address 模型實例。

?? 注意：若某個子項不符合結構，會立即拋出 ValidationError。

4.4 序列化：model_dump() 與 model_dump_json()

? V2 新命名方式（取代 .dict()）

user = User(id=1, name="Alice", age=30)

# 轉 Python dict
data = user.model_dump()
print(data)  # {'id': 1, 'name': 'Alice', 'age': 30}

# 轉 JSON 字符串
json_str = user.model_dump_json(indent=2)
print(json_str)

?? 高級參數選項

示例：

user.model_dump(exclude={'age'}, exclude_unset=True, by_alias=True)

4.5 反序列化：model_validate() 與 model_validate_json()

? V2 推薦方式（取代 .parse_obj()）

# 從 dict 構建
data = {"id": 1, "name": "Alice", "age": 30}
user = User.model_validate(data)

# 從 JSON 字符串構建
json_data = '{"id": 1, "name": "Alice", "age": 30}'
user = User.model_validate_json(json_data)

? 兩者都會觸發(fā)完整的校驗流程，失敗則拋出 ValidationError。

?? 重要提示：不要使用 .parse_obj()，已被廢棄。

4.6 自定義校驗：@field_validator

? V2 推薦方式（替代舊版 @validator）

from pydantic import BaseModel, field_validator

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

    @field_validator("email")
    @classmethod
    def validate_email(cls, value: str) -> str:
        if "@" not in value:
            raise ValueError("郵箱格式無效")
        return value

    @field_validator("name")
    @classmethod
    def name_no_spaces(cls, value: str) -> str:
        if " " in value:
            raise ValueError("姓名不能包含空格")
        return value

?? 驗證時機控制（mode 選項）

@field_validator("phone", mode="after")
def validate_phone(cls, v: str) -> str:
    if not v.startswith("+"):
        raise ValueError("電話必須以 + 開頭")
    return v

?? 重點：@field_validator 必須標注 @classmethod，否則無法綁定類上下文。

4.7 內置語義類型：EmailStr, HttpUrl, IPv4Address 等

Pydantic 內置了一系列“語義類型”，用于快速校驗常見格式。

from pydantic import BaseModel, EmailStr, HttpUrl

class Contact(BaseModel):
    email: EmailStr           # ? 自動校驗郵箱格式
    website: HttpUrl          # ? 校驗合法 URL

?? 依賴安裝：這些類型需要額外依賴。

pip install pydantic[email]
# 或
pip install email-validator

? 官方推薦：使用 pydantic[email] 安裝完整擴展包。

五、與 FastAPI 深度集成（典型用法）

? FastAPI 的核心支柱之一就是 Pydantic

from fastapi import FastAPI
from pydantic import BaseModel

app = FastAPI()

class Item(BaseModel):
    name: str
    price: float

@app.post("/items/")
def create_item(item: Item):
    return item  # FastAPI 自動返回標準 JSON

?? FastAPI 如何利用 Pydantic？

? 無需手動編寫 if 判斷或 json.loads，開箱即用。

六、完整示例：用戶 + 地址 + 郵箱校驗

from typing import List, Optional
from pydantic import BaseModel, EmailStr, Field, field_validator
from pydantic.types import StrictInt

class Address(BaseModel):
    city: str = Field(..., min_length=1, description="城市名稱")
    street: str = Field(..., min_length=1)

class User(BaseModel):
    name: str = Field(..., min_length=1, max_length=50)
    age: StrictInt = Field(..., ge=0, le=150)  # 嚴格整數（非字符串可轉換）
    email: EmailStr
    addresses: List[Address] = Field(default_factory=list)
    nickname: Optional[str] = None

    @field_validator("name")
    @classmethod
    def name_cannot_contain_space(cls, v: str) -> str:
        if " " in v:
            raise ValueError("姓名不能包含空格")
        return v

    @field_validator("email")
    @classmethod
    def email_must_be_company_domain(cls, v: str) -> str:
        if not v.endswith("@company.com"):
            raise ValueError("僅允許公司郵箱（@company.com）")
        return v

# 測試用例
if __name__ == "__main__":
    try:
        user = User(
            name="Alice",
            age=25,
            email="alice@company.com",
            addresses=[{"city": "Beijing", "street": "Road 1"}],
        )
        print("? 用戶創(chuàng)建成功！")
        print(user.model_dump_json(indent=2))

    except Exception as e:
        print(f"? 創(chuàng)建失?。簕e}")

? 輸出示例：

{
  "name": "Alice",
  "age": 25,
  "email": "alice@company.com",
  "addresses": [
    {
      "city": "Beijing",
      "street": "Road 1"
    }
  ],
  "nickname": null
}

七、Pydantic V2 關鍵改進摘要（與 V1 對比）

?? 遷移建議：

• 檢查是否使用了 .dict()、.parse_obj()；
• 替換所有 @validator 為 @field_validator；
• 添加 strict=True 以避免意外轉換；
• 升級 pydantic-core 依賴；
• 仔細閱讀官方文檔。

八、小結 & 實用建議

? 推薦學習路徑：

1. Pydantic 官網 Docs
2. Migration Guide
3. GitHub 源碼：github.com/pydantic/pydantic

Pydantic V2 已成為主流，V1 停止維護。
無論你是做 Web API、自動化腳本、還是配置管理，現在開始用 V2 是最優(yōu)選擇。