Pydantic的主要用法

Pydantic的主要用法

• Pydantic 是一个基于 Python 类型注解的数据验证和设置管理库。
• Pydantic在 AI 产品中扮演着数据验证、类型安全、序列化与配置管理的核心角色，它通过基于 Python 类型注解的声明式编程，显著提升了 AI 系统的可靠性、可维护性和开发效率。
• Pydantic在数据质量决定模型性能的 AI 领域已成为保障系统稳定性的关键工具。

1. 基础模型定义

from pydantic import BaseModel
from datetime import datetime
from typing import Optional, List

class User(BaseModel):
    id: int
    name: str
    email: str
    age: Optional[int] = None
    created_at: datetime = datetime.now()
    
# 创建实例
user = User(id=1, name="张三", email="zhangsan@example.com")
print(user)
# 输出: id=1 name='张三' email='zhangsan@example.com' age=None created_at=datetime.datetime(...)

# 访问属性
print(user.name)  # 张三
print(user.model_dump())  # 转换为字典

2. 数据验证

from pydantic import BaseModel, Field, ValidationError, EmailStr

class User(BaseModel):
    name: str = Field(..., min_length=2, max_length=50, description="用户名")
    age: int = Field(..., ge=0, le=150, description="年龄")
    email: EmailStr  # 自动验证邮箱格式
    
try:
    # 无效数据
    user = User(name="A", age=200, email="invalid-email")
except ValidationError as e:
    print(e.json())
    # 输出详细的验证错误信息

3. 嵌套模型

from pydantic import BaseModel
from typing import List

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

class User(BaseModel):
    name: str
    age: int
    address: Address
    tags: List[str] = []
    
# 创建嵌套对象
user = User(
    name="李四",
    age=25,
    address={"street": "中山路123号", "city": "北京", "zipcode": "100000"},
    tags=["python", "developer"]
)

print(user.address.city)  # 北京

4. 自定义验证器

from pydantic import BaseModel, validator, field_validator

class Product(BaseModel):
    name: str
    price: float
    discount: float = 0.0
    
    @field_validator('price')
    def price_must_be_positive(cls, v):
        if v <= 0:
            raise ValueError('价格必须大于0')
        return v
    
    @field_validator('discount')
    def discount_valid(cls, v, info):
        if v < 0 or v > 1:
            raise ValueError('折扣必须在0-1之间')
        return v
    
    @property
    def final_price(self) -> float:
        """计算最终价格"""
        return self.price * (1 - self.discount)

# 使用
product = Product(name="笔记本电脑", price=5999.99, discount=0.1)
print(product.final_price)  # 5399.991

5. 数据转换

from pydantic import BaseModel
from datetime import date

class Event(BaseModel):
    name: str
    date: date  # 自动将字符串转换为date对象
    attendees: int
    
# 从字典创建
data = {
    "name": "Python会议",
    "date": "2024-12-25",
    "attendees": "100"  # 字符串会自动转换为int
}
event = Event(**data)
print(event.date)  # 2024-12-25 (date对象)
print(type(event.attendees))  # <class 'int'>

6. 配置和序列化

from pydantic import BaseModel
from datetime import datetime

class User(BaseModel):
    id: int
    name: str
    password: str
    
    class Config:
        # 从ORM对象创建
        from_attributes = True
        # 自定义字段名
        alias_generator = lambda field: field.upper()
        # 排除某些字段
        fields = {'password': {'exclude': True}}
        
# 序列化时排除密码
user = User(id=1, name="王五", password="secret123")
print(user.model_dump())  # {'id': 1, 'name': '王五'}

7. 泛型支持

from pydantic import BaseModel
from typing import Generic, TypeVar, List

T = TypeVar('T')

class APIResponse(BaseModel, Generic[T]):
    code: int
    message: str
    data: T

# 使用
class User(BaseModel):
    id: int
    name: str

# 单个用户响应
response = APIResponse[User](
    code=200,
    message="success",
    data={"id": 1, "name": "张三"}
)

# 用户列表响应
response_list = APIResponse[List[User]](
    code=200,
    message="success",
    data=[{"id": 1, "name": "张三"}, {"id": 2, "name": "李四"}]
)

8. 实际应用场景：FastAPI集成

from fastapi import FastAPI
from pydantic import BaseModel, Field

app = FastAPI()

class UserCreate(BaseModel):
    username: str = Field(..., min_length=3, max_length=20)
    email: str
    password: str = Field(..., min_length=8)
    
@app.post("/users/")
async def create_user(user: UserCreate):
    # 自动验证请求数据
    return {"message": f"用户 {user.username} 创建成功"}

9. 高级特性：递归模型

from pydantic import BaseModel
from typing import List, Optional

class Category(BaseModel):
    id: int
    name: str
    children: List['Category'] = []  # 自引用
    
    class Config:
        # 允许自引用
        arbitrary_types_allowed = True
        
# 创建树形结构
root = Category(
    id=1,
    name="电子产品",
    children=[
        Category(id=2, name="手机", children=[]),
        Category(id=3, name="电脑", children=[
            Category(id=4, name="笔记本", children=[]),
            Category(id=5, name="台式机", children=[])
        ])
    ]
)

10. 环境变量支持

from pydantic_settings import BaseSettings
from typing import Optional

class Settings(BaseSettings):
    app_name: str = "MyApp"
    database_url: str
    debug: bool = False
    api_key: Optional[str] = None
    
    class Config:
        env_file = ".env"  # 从.env文件读取环境变量
        
# 使用
settings = Settings()
print(settings.database_url)  # 从环境变量或.env文件读取

Pydantic的主要优势：

1. 类型安全：自动进行类型检查和转换
2. 数据验证：丰富的验证器
3. IDE友好：完整的类型提示支持
4. 性能优异：基于Python类型提示，性能好
5. 易于集成：与FastAPI等框架无缝集成

这些例子展示了Pydantic的主要特性，实际开发中可以根据需求灵活使用。

关于"6. 配置和序列化"详解

Config基础概念

在Pydantic中，Config类是用来配置模型行为的特殊内部类。

1. 基本模型

from pydantic import BaseModel
from datetime import datetime

class User(BaseModel):
    id: int
    name: str
    password: str
    
# 创建用户
user = User(id=1, name="王五", password="secret123")

# 默认序列化：所有字段都会输出
print(user.model_dump())  
# 输出: {'id': 1, 'name': '王五', 'password': 'secret123'}

2. 添加Config配置

class User(BaseModel):
    id: int
    name: str
    password: str
    
    class Config:
        # 1. from_attributes = True
        from_attributes = True
        
        # 2. alias_generator = lambda field: field.upper()
        alias_generator = lambda field: field.upper()
        
        # 3. fields = {'password': {'exclude': True}}
        fields = {'password': {'exclude': True}}

现在我来详细解释每个配置项：

配置1：from_attributes = True

这个配置允许从其他对象创建Pydantic模型实例，比如从数据库ORM对象：

# 假设有一个SQLAlchemy的User模型
class SQLAlchemyUser:
    def __init__(self, id, name, password):
        self.id = id
        self.name = name
        self.password = password

# 创建ORM对象
db_user = SQLAlchemyUser(id=1, name="赵六", password="pass456")

# 没有from_attributes = True时，这样会报错
# user = User.model_validate(db_user)  # 错误！

# 有了from_attributes = True，就可以直接从ORM对象创建
user = User.model_validate(db_user)  # 正确！
print(user.name)  # 输出: 赵六

实际应用场景：

# 从数据库查询出来的对象
db_user = db.query(User).first()  # 这是一个SQLAlchemy对象
# 直接转换为Pydantic模型用于API响应
pydantic_user = User.model_validate(db_user)

配置2：alias_generator = lambda field: field.upper()

这个配置定义了字段别名生成规则。upper()表示将字段名转换为大写：

class User(BaseModel):
    id: int
    name: str
    password: str
    
    class Config:
        alias_generator = lambda field: field.upper()

# 创建对象时可以使用大写字段名
user = User(ID=1, NAME="王五", PASSWORD="secret123")
# 虽然字段名是小写的，但可以用大写传入

print(user.id)      # 1
print(user.name)    # 王五

# 序列化时也会使用别名
print(user.model_dump(by_alias=True))  
# 输出: {'ID': 1, 'NAME': '王五', 'PASSWORD': 'secret123'}

print(user.model_dump())  
# 输出: {'id': 1, 'name': '王五', 'password': 'secret123'}  # 默认还是原字段名

实际应用场景：处理不同命名规范的API（例如，Python使用小写，但API使用大写或驼峰）

# 处理使用驼峰命名的API
class User(BaseModel):
    user_id: int
    user_name: str
    
    class Config:
        alias_generator = lambda field: ''.join(
            word.capitalize() if i > 0 else word 
            for i, word in enumerate(field.split('_'))
        )  # 转换为驼峰: user_name -> userName

# 现在可以接收驼峰格式的数据
user = User(userId=1, userName="张三")  # 使用驼峰

配置3：fields = {'password': {'exclude': True}}

这个配置指定在序列化时排除某些字段：

class User(BaseModel):
    id: int
    name: str
    password: str
    
    class Config:
        fields = {'password': {'exclude': True}}

user = User(id=1, name="王五", password="secret123")

# 序列化时自动排除password字段
print(user.model_dump())  
# 输出: {'id': 1, 'name': '王五'}
# 注意：password被排除了

# 即使想包含password也包含不了
print(user.model_dump(exclude={'password': False}))  # 依然没有password

完整示例对比

from pydantic import BaseModel

# 无配置版本
class UserSimple(BaseModel):
    id: int
    name: str
    password: str

# 完整配置版本
class UserConfigured(BaseModel):
    id: int
    name: str
    password: str
    
    class Config:
        from_attributes = True
        alias_generator = lambda field: field.upper()
        fields = {'password': {'exclude': True}}

# 演示对比
print("=== 简单版本 ===")
user1 = UserSimple(id=1, name="张三", password="123")
print(user1.model_dump())  # {'id': 1, 'name': '张三', 'password': '123'}

print("n=== 配置版本 ===")
# 1. 可以使用大写别名
user2 = UserConfigured(ID=1, NAME="李四", PASSWORD="456")
print(user2.name)  # 李四

# 2. 序列化时排除password
print(user2.model_dump())  # {'id': 1, 'name': '李四'}

# 3. 可以输出带别名的版本
print(user2.model_dump(by_alias=True))  # {'ID': 1, 'NAME': '李四'}

print("n=== 从ORM对象创建 ===")
class ORMUser:
    def __init__(self, id, name, password):
        self.id = id
        self.name = name
        self.password = password

# 从ORM对象直接创建
orm_user = ORMUser(id=3, name="王五", password="789")
pydantic_user = UserConfigured.model_validate(orm_user)
print(pydantic_user.model_dump())  # {'id': 3, 'name': '王五'}
# password字段被自动排除

其他常用Config配置

class User(BaseModel):
    id: int
    name: str
    email: str
    
    class Config:
        # 1. 允许额外字段
        extra = "allow"  # 或 "forbid"（禁止）或 "ignore"（忽略）
        
        # 2. 设置JSON编码器
        json_encoders = {
            datetime: lambda v: v.isoformat()
        }
        
        # 3. 验证赋值
        validate_assignment = True  # 赋值时重新验证
        
        # 4. 标题
        title = "User Model"

总结

这个示例展示了Pydantic的三个重要配置：

1. from_attributes = True：让模型可以从其他Python对象（如数据库ORM对象）创建
2. alias_generator：自动生成字段别名，用于处理不同命名规范的输入输出
3. fields = {'password': {'exclude': True}}：永久排除敏感字段（如密码），防止意外泄露

这些配置让Pydantic模型更加灵活和安全，特别适合在实际项目中使用。

补充：示例中V1代码在V2环境下可能执行出错，为此补充如下V1和V2的差异

Pydantic V1 vs V2 主要区别

Pydantic V2 是一次完全重写，在性能、API设计和功能上都有重大改进。V2 引入了许多不兼容的更改，但也带来了显著的性能提升和新特性。以下是详细对比：

核心差异速览表

1. 方法名称变更（最直接的改动）

V2 统一了命名规范，所有主要方法都采用 model_* 前缀：

代码示例对比

# V1 写法
from pydantic import BaseModel

class User(BaseModel):
    id: int
    name: str

user = User(id=1, name="张三")
print(user.dict())        # {'id': 1, 'name': '张三'}
print(user.json())        # {"id": 1, "name": "张三"}

# V2 写法
from pydantic import BaseModel

class User(BaseModel):
    id: int
    name: str

user = User(id=1, name="张三")
print(user.model_dump())      # {'id': 1, 'name': '张三'}
print(user.model_dump_json()) # {"id":1,"name":"张三"}

2. 泛型模型（GenericModel 移除）

V1 需要专门的 GenericModel 类，V2 直接继承 BaseModel 和 Generic：

# V1 写法
from pydantic.generics import GenericModel
from typing import Generic, TypeVar

T = TypeVar('T')

class Response(GenericModel, Generic[T]):
    data: T
    code: int

# V2 写法
from pydantic import BaseModel
from typing import Generic, TypeVar

T = TypeVar('T')

class Response(BaseModel, Generic[T]):
    data: T
    code: int

3. ORM模式配置变更

# V1
class User(BaseModel):
    id: int
    name: str
    
    class Config:
        orm_mode = True  # 从ORM对象读取

# V2
class User(BaseModel):
    id: int
    name: str
    
    class Config:
        from_attributes = True  # 新的配置名

使用方式也变了：

# V1: 使用 from_orm()
user = User.from_orm(db_user)

# V2: 使用 model_validate() + from_attributes=True
user = User.model_validate(db_user)  # 需要 Config 中设置 from_attributes=True

4. 自定义根模型（RootModel）

V1 使用 __root__ 字段，V2 引入专门的 RootModel 类型：

# V1 写法
class Data(BaseModel):
    __root__: List[int]

data = Data(__root__=[1, 2, 3])
print(data.__root__)  # [1, 2, 3]

# V2 写法
from pydantic import RootModel

Data = RootModel[List[int]]
data = Data([1, 2, 3])
print(data.root)  # [1, 2, 3]

5. Field 字段约束变更

多个字段参数被重命名或移除：

示例

# V1
class Model(BaseModel):
    name: str = Field(..., regex="^[A-Z]")

# V2
class Model(BaseModel):
    name: str = Field(..., pattern="^[A-Z]")

6. JSON Schema 自定义

V2 将 JSON Schema 的额外数据统一到 json_schema_extra 参数：

# V1
class Model(BaseModel):
    name: str = Field(..., title="姓名", description="用户姓名")

    class Config:
        schema_extra = {"examples": [{"name": "张三"}]}

# V2
class Model(BaseModel):
    name: str = Field(..., title="姓名", description="用户姓名")
    
    class Config:
        json_schema_extra = {"examples": [{"name": "张三"}]}

7. 序列化器（重要新功能）

V2 提供了更灵活的序列化控制：

from pydantic import BaseModel, field_serializer, model_serializer

class User(BaseModel):
    name: str
    password: str
    
    # 字段级序列化器
    @field_serializer('password')
    def hide_password(self, password: str) -> str:
        return '***'
    
    # 模型级序列化器
    @model_serializer
    def custom_serialize(self):
        return {k: v for k, v in self.__dict__.items() if k != 'password'}

user = User(name="张三", password="secret")
print(user.model_dump())  # {'name': '张三', 'password': '***'}

8. 配置系统升级

V2 使用 ConfigDict 替代原有的 Config 类，提供更好的类型提示：

from pydantic import BaseModel, ConfigDict

class User(BaseModel):
    id: int
    name: str
    
    model_config = ConfigDict(
        from_attributes=True,
        extra='forbid',
        frozen=False,
        str_strip_whitespace=True
    )

9. 新功能亮点（V2独有）

Python 3.14 支持

V2.12+ 支持 Python 3.14 的延迟类型注解评估（PEP 649）

MISSING 哨兵（实验性）

区分"未提供"和"None"值：

from pydantic import BaseModel
from pydantic.experimental.missing_sentinel import MISSING

class Config(BaseModel):
    timeout: int | None | MISSING = MISSING

排除条件字段

from pydantic import BaseModel, Field

class Transaction(BaseModel):
    id: int
    value: int = Field(ge=0, exclude_if=lambda v: v == 0)

时间戳单位控制

from pydantic import BaseModel, ConfigDict
from datetime import datetime

class Model(BaseModel):
    d: datetime
    model_config = ConfigDict(val_temporal_unit='milliseconds')

10. 向后兼容策略

V2 提供了 pydantic.v1 模块以兼容旧代码：

# 仍然可以使用 V1 API
from pydantic.v1 import BaseModel  # V1 风格

class User(BaseModel):
    name: str

V1 将在 2024年6月30日后停止安全更新。

升级建议

1. 使用自动迁移工具 bump-pydantic：

   pip install bump-pydantic
   bump-pydantic your_package/
   

2. 逐步迁移：利用 pydantic.v1 命名空间分模块升级

3. 重点检查：

   • 所有 .dict() / .json() 调用
   • orm_mode 配置
   • __root__ 根模型
   • GenericModel 泛型
   • 自定义 Field 约束参数

V2 虽然改动较大，但性能提升和 API 统一让长期维护更加轻松。