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

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

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

? 語法解讀：~= 操作符（兼容性釋放，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）。

?? 舉例說明

?? 為什么使用 ~=？

• 避免因無意升級引入破壞性變更。
• 保留安全補(bǔ)?。ㄈ缧迯?fù)漏洞、性能優(yōu)化）。
• 在 CI/CD、生產(chǎn)部署中保障穩(wěn)定性。

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

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

?? 核心定位

Pydantic 是一個基于 Python 類型注解（Type Hints）構(gòu)建的 數(shù)據(jù)驗證、設(shè)置管理、序列化 庫。

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

• 用簡潔的類定義數(shù)據(jù)模型；
• 自動完成類型校驗與轉(zhuǎn)換；
• 支持復(fù)雜嵌套結(jié)構(gòu)與自定義邏輯；
• 無縫集成進(jìn) FastAPI、Docker 配置、爬蟲、數(shù)據(jù)庫等場景。

?? 適用場景一覽

?? 從 V1 到 V2：一次重大的演進(jìn)

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

?? 官方遷移指南：Migration Guide

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

3.1 基礎(chǔ)模型定義

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

from pydantic import BaseModel

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

?? 字段行為解析：

?? 重要提示：在 Python 3.10+ 中，int | None 是標(biāo)準(zhǔn)寫法；舊版可用 Optional[int]。

3.2 模型實例化與自動類型轉(zhuǎn)換（類型強(qiáng)制與協(xié)變）

Pydantic 支持在創(chuàng)建模型時進(jìn)行智能類型轉(zhuǎn)換（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)

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

? 不支持的轉(zhuǎn)換

• "abc" → int ?（拋出錯誤）
• {"a": 1} → List[int] ?（結(jié)構(gòu)不匹配）

3.3 錯誤處理：ValidationError

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

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)勢：錯誤信息精確到字段 + 原因，極大提升調(diào)試效率。

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

4.1 字段約束：Field() 函數(shù)

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="標(biāo)簽列表")

?? 常用參數(shù)詳解

? 推薦寫法（結(jié)合 Annotated）：

from typing import Annotated
from pydantic import BaseModel, Field

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

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

4.2 可選字段與默認(rèn)值處理

from pydantic import BaseModel
from typing import Optional

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

? 推薦：使用 float | None 替代 Optional[float]（更直觀、更符合現(xiàn)代風(fēng)格）

4.3 嵌套模型（復(fù)合結(jié)構(gòu)）

from pydantic import BaseModel
from typing import List

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

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

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

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

?? 注意：若某個子項不符合結(jié)構(gòu)，會立即拋出 ValidationError。

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

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

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

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

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

?? 高級參數(shù)選項

示例：

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

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

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

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

# 從 JSON 字符串構(gòu)建
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

?? 驗證時機(jī)控制（mode 選項）

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

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

4.7 內(nèi)置語義類型：EmailStr, HttpUrl, IPv4Address 等

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

from pydantic import BaseModel, EmailStr, HttpUrl

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

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

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

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

五、與 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 自動返回標(biāo)準(zhǔn) 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)  # 嚴(yán)格整數(shù)（非字符串可轉(zhuǎn)換）
    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 關(guān)鍵改進(jìn)摘要（與 V1 對比）

?? 遷移建議：

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

八、小結(jié) & 實用建議

? 推薦學(xué)習(xí)路徑：

1. Pydantic 官網(wǎng) Docs
2. Migration Guide
3. GitHub 源碼：github.com/pydantic/pydantic

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