Pydantic

Pydantic 基于类型注解实现数据验证，支持自动类型转换、序列化和结构化错误处理。

核心能力

能力	说明
数据验证	类型、格式、约束检查
自动转换	JSON/dict → Python 类型
序列化	模型 ↔ JSON/dict
错误处理	结构化错误信息

基础用法

from pydantic import BaseModel, Field
 
class User(BaseModel):
    id: int
    name: str = Field(min_length=2, max_length=10)
    email: str | None = None
 
user = User(id="123", name="Alice")  # id 自动转 int

字段约束

class Product(BaseModel):
    name: str = Field(min_length=1, max_length=100)
    price: float = Field(ge=0, le=10000)  # 0 ≤ price ≤ 10000
    tags: list[str] = Field(default_factory=list)

自定义验证器

from pydantic import field_validator
 
class Product(BaseModel):
    price: float
 
    @field_validator("price")
    @classmethod
    def validate_price(cls, v):
        if v <= 0:
            raise ValueError("价格必须为正数")
        return v

嵌套模型

class Address(BaseModel):
    city: str
    street: str
 
class Company(BaseModel):
    name: str
    address: Address
 
company = Company(name="TechCorp", address={"city": "Beijing", "street": "Main St"})

FastAPI 集成

from fastapi import FastAPI
 
app = FastAPI()
 
class Item(BaseModel):
    name: str
    price: float
 
@app.post("/items/")
async def create_item(item: Item):
    return {"name": item.name, "price": item.price}

配置管理

from pydantic_settings import BaseSettings
 
class Settings(BaseSettings):
    api_key: str
    debug: bool = False
 
    class Config:
        env_file = ".env"
 
settings = Settings()

V2 新语法

# 序列化
user.model_dump()        # → dict
user.model_dump_json()   # → JSON string
 
# 反序列化
User.model_validate(data)          # dict → model
User.model_validate_json(json_str) # JSON → model

工具对比

工具	优势	适用场景
Pydantic	类型注解集成、高性能	API 验证、配置管理
Marshmallow	灵活自定义 Schema	复杂序列化
Dataclasses	轻量级	无需验证的简单结构