Python 数据验证库：Pydantic

作者：马育民 • • 阅读：10088

介绍

Pydantic 是一个非常流行的 Python 数据验证和设置管理库，它基于 Python 类型注解（Type Hints）工作，能自动校验数据类型和值的合法性，广泛用于 API 开发（如 FastAPI）、数据解析、配置管理等场景。

优点

  • 类型校验：基于类型注解自动校验输入数据的类型（如 int、str、list 等）；
  • 数据转换：自动将合法的输入转换为目标类型（如字符串 “123” 转为 int 123）；
  • 错误提示：校验失败时返回清晰的错误信息，便于调试；
  • 易集成：与 FastAPI、Django、SQLAlchemy 等框架无缝配合。

V2版本

Pydantic v2 是 2023 年 6 月发布的重大版本，核心用 Rust 重写，性能比 v1 快 5–50 倍，同时带来更严谨的类型校验、全新的验证器与序列化 API、原生计算字段等能力。下面从核心变革、安装使用、模型定义、校验、序列化、配置、迁移与实战几方面详细说明。

核心变革（v1 → v2）

1. 性能飞跃

  • 底层验证引擎由纯 Python 改为 Rust 实现（pydantic-core），解析/验证速度提升 5–50 倍，内存占用更低。
  • schema 构建与实例化大幅优化，适合高并发、大数据场景。

2. API 重构（关键更名）

功能 Pydantic v1 Pydantic v2
基类 BaseModel BaseModel（兼容，推荐新写法）
配置类 class Config: model_config = ConfigDict(...)
字段验证器 @validator @field_validator
模型验证器 @root_validator @model_validator
序列化 .dict() / .json() .model_dump() / .model_dump_json()
从 ORM 实例创建 orm_mode = True from_attributes = True
自定义根模型 __root__ 字段 RootModel 类

3. 类型系统增强

  • 原生支持 PEP 695（类型参数）、PEP 696（类型默认值）。
  • 严格类型（StrictStr/StrictInt 等）默认更严格，减少隐式转换（如 '1' 不再自动转 1）。
  • Annotated 成为推荐方式，显式绑定类型与元数据。

4. 新特性

安装 Pydantic

首先需要安装 Pydantic（推荐安装最新的 v2 版本，性能和功能更优）：

# 安装基础版本
pip install pydantic

# 若需要兼容旧版（v1）特性，可安装兼容包
pip install pydantic[compat]

基础用法

Pydantic 的核心是 BaseModel 类，所有数据模型都需要继承它。下面是最基础的示例：

from pydantic import BaseModel, ValidationError

# 定义数据模型（基于类型注解）
class User(BaseModel):
    name: str          # 必选字段，字符串类型
    age: int           # 必选字段，整数类型
    email: str | None  # 可选字段，字符串或 None（Python 3.10+ 写法）
    is_active: bool = True  # 有默认值的字段，可选

# 1. 正确的数据示例（自动校验+转换）
user_data = {
    "name": "张三",
    "age": "25",  # 字符串会自动转为 int
    "email": "zhangsan@example.com"
}
user = User(**user_data)
print(user.name)  # 输出：张三
print(user.age)   # 输出：25（int 类型）
# 转为字典/JSON
print(user.model_dump())  # 转为字典
print(user.model_dump_json())  # 转为 JSON 字符串

# 2. 错误的数据示例（校验失败）
bad_user_data = {
    "name": 123,  # 类型错误（应为 str）
    "age": "二十五"  # 无法转为 int
}
try:
    User(**bad_user_data)
except ValidationError as e:
    print(e.json())  # 输出清晰的错误信息

进阶用法

Pydantic 支持更精细的校验规则，比如字段长度、数值范围、正则匹配等，需要用到 Field 函数：

from pydantic import BaseModel, Field, EmailStr

class User(BaseModel):
    # 姓名：字符串，长度 2-10
    name: str = Field(min_length=2, max_length=10)
    # 年龄：整数，18-100 之间
    age: int = Field(ge=18, le=100, description="用户年龄（18-100）")
    # 邮箱：自动校验邮箱格式（需安装 email-validator：pip install email-validator）
    email: EmailStr
    # 手机号：正则匹配（中国大陆手机号）
    phone: str = Field(pattern=r"^1[3-9]\d{9}$")

# 正确示例
valid_user = User(
    name="李四",
    age=30,
    email="lisi@example.com",
    phone="13812345678"
)
print(valid_user)

# 错误示例（手机号格式错误）
try:
    User(
        name="李四",
        age=30,
        email="lisi@example.com",
        phone="12345678901"
    )
except ValidationError as e:
    print(e)

应用场景

  1. API 数据校验（FastAPI 核心依赖）：
    FastAPI 内置 Pydantic，定义请求体/响应体时直接用 Pydantic 模型，自动完成数据校验和接口文档生成。
  2. 配置管理：
    解析配置文件（如 JSON/YAML）时，用 Pydantic 模型校验配置项的类型和值，避免配置错误。
  3. 数据解析：
    处理外部数据（如 CSV、数据库返回值）时，用 Pydantic 校验数据格式，确保数据合规。

总结

  1. Pydantic 是基于 Python 类型注解的数据验证库，核心是 BaseModel 类，能自动校验数据类型和值的合法性；
  2. 核心优势是类型校验、自动转换、清晰的错误提示，是 FastAPI 等框架的核心依赖；
  3. 进阶用法可通过 Field 函数定义精细的校验规则（长度、范围、正则等），满足复杂场景需求。

原文出处：/show_1GW2qlZA2a1y.html

吉ICP备15003043号