Python Pydantic 教程

Pydantic 完全指南：从入门到实战

一、Pydantic 简介

1.1 什么是 Pydantic？

Pydantic 是一个用于数据验证和设置管理的 Python 库，它通过 Python 类型注解来定义数据模型，提供强大的数据验证功能。

1.2 核心功能

• 数据验证：确保输入数据符合预定义的类型和结构
• 序列化：将复杂数据结构转换为 Python 数据类型
• 错误处理：提供详细的错误信息
• 配置管理：支持通过环境变量管理配置

1.3 主要特性

• 基于 Python 类型注解
• 高性能（核心验证逻辑用 Rust 编写）
• 支持 JSON Schema 生成
• 提供严格模式和宽松模式
• 支持数据类和 TypedDict
• 允许自定义验证器和序列化器

1.4 Pydantic 生态系统

FastAPI 深度集成 Pydantic，用于请求/响应模型验证和自动文档生成。

相关工具

• Pydantic-SQLAlchemy：ORM 集成
• Pydantic-Factories：测试数据生成
• Pydantic-Settings：配置管理

二、安装

版本不同，方法差异较大。固定该版本来使用

• pydantic~=2.10.3
• pydantic-settings~=2.2.1

pip install pydantic

三、基础使用

3.1 基本数据模型定义

from pydantic import BaseModel

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

3.2 数据验证示例

user = User(id=1, name="John")
print(user)  # 输出验证后的模型

try:
    invalid_user = User(id="one", name=123)
except ValidationError as e:
    print(e)  # 输出验证错误

四、高级功能

4.1 自定义验证器

4.1.1 基本验证器

from pydantic import BaseModel, field_validator

class User(BaseModel):
    name: str
    age: int
    
    @field_validator('name')
    @classmethod
    def name_must_contain_space(cls, v):
        if ' ' not in v:
            raise ValueError('必须包含空格')
        return v.title()

4.1.2 多字段验证

@field_validator('age')
@classmethod
def age_must_be_positive(cls, v):
    if v <= 0:
        raise ValueError('必须是正整数')
    return v

4.2 嵌套模型

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

class User(BaseModel):
    name: str
    address: Address

4.3 模型配置：定制化模型行为

class ConfigModel(BaseModel):
    name: str
    
    class Config:
        allow_mutation = False  # 使实例不可变
        extra = 'forbid'  # 禁止额外字段

4.3.1 常用配置选项详解

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

class SystemSettings(BaseModel):
    """系统配置模型"""
    
    class Config:
        # 基础配置
        allow_mutation = False  # 模型实例不可变
        extra = 'forbid'       # 禁止额外字段
        validate_all = True    # 验证所有字段（即使没有提供值）
        
        # 日期时间处理
        json_encoders = {
   
   
            datetime: lambda v: v.strftime('%Y-%m-%d %H:%M:%S')
        }
        
        # 错误信息模板
        error_msg_templates = {
   
   
            'value_error.missing': '字段 {field} 是必填项',
            'type_error.integer': '字段 {field} 必须是整数'
        }
    
    hostname: str = Field(..., min_length=3, max_length=63)
    port: int = Field(1024, ge=1024, le=65535)
    last_updated: Optional[datetime] = None
    debug_mode: bool = False

# 使用示例
try:
    settings = SystemSettings(
        hostname="my-server",
        port=8080,  # 端口不在允许范围内
        extra_field="value"  # 额外字段会触发错误
    )
except ValidationError as e:
    print(e.json(indent=2))

4.3.2 高级配置技巧

from pydantic import BaseModel, va