Pydantic BaseModel介绍

江一破

于 2025-06-26 16:06:34 发布

阅读量882

点赞数 8

CC 4.0 BY-SA版权

文章标签： python

本文链接：https://blog.youkuaiyun.com/qq_42758052/article/details/148926597

1. 定义

BaseModel是Python库Pydantic的核心类，用于定义数据结构并强制执行类型验证。其诞生背景源于Python动态类型的弱点——开发中难以保证数据结构的正确性，尤其在API、配置文件解析等场景。

Pydantic于2017年由Samuel Colvin创建，随着Python类型提示（Type Hints）的普及（Python 3.5+），它利用类型注解在运行时自动验证数据，将动态语言的灵活性与静态类型的安全性结合，专注于运行时数据校验和序列化。

2. 核心功能

核心功能1：数据验证与自动类型转换

当数据传入BaseModel时，Pydantic会：
1. 检查字段类型（如将字符串"123"自动转为整数123）
2. 验证数据合法性（如邮箱格式、URL格式）
3. 对无效数据抛出清晰错误（含错误字段和原因）

from pydantic import BaseModel, EmailStr

class User(BaseModel):
    id: int
    name: str = "Anonymous"
    email: EmailStr  # 专用类型验证邮箱格式

# 自动转换类型 + 验证
user = User(id="123", email="user@example.com") 
print(user.id)  # 输出: 123 (自动转int)

# 无效数据触发异常
User(id="abc", email="invalid")  # 抛出ValidationError：id非整数，邮箱格式错误

核心功能2：序列化与数据导出

一键将模型转为字典或JSON：

user_dict = user.model_dump()  # 输出: {'id': 123, 'name': 'Anonymous', 'email': 'user@example.com'}
user_json = user.model_dump_json()  # 输出: JSON字符串

其他功能：

嵌套模型验证
自定义验证器（@validator装饰器）
配置管理（如model_config设置别名、额外字段禁止）
与FastAPI深度集成（自动生成API文档）

3. 使用示例

场景：用户注册数据校验

from datetime import datetime
from pydantic import BaseModel, field_validator

class UserCreate(BaseModel):
    username: str
    password: str
    birthdate: datetime  # 自动解析时间字符串
    tags: list[str] = []  # 默认值

    @field_validator("password")
    def validate_password(cls, v):
        if len(v) < 8:
            raise ValueError("密码至少8位")
        return v

# 使用
data = {
    "username": "pydantic_user",
    "password": "short",  # 触发自定义错误
    "birthdate": "2023-01-01T12:00"
}
try:
    user = UserCreate(**data)
except ValueError as e:
    print(e)  # 输出: 1 validation error: password -> Value error, 密码至少8位

4. 与其它工具对比

特性	Pydantic	Marshmallow	attrs	Python Dataclasses
类型提示驱动	✅ 原生支持	❌ 需单独定义	⚠️ 需扩展	✅ 原生支持
运行时验证	✅ 核心功能	✅ 核心功能	⚠️ 需`validated`	❌ 无内置
序列化/反序列化	✅ 内置	✅ 核心功能	❌ 需第三方库	❌ 需手动实现
OpenAPI集成	✅ 深度支持	⚠️ 需扩展	❌ 无	❌ 无
性能	⚡️ 快 (Rust加速)	🐢 中等	⚡️ 快	⚡️ 极快
依赖	仅Python标准库	纯Python	纯Python	Python标准库