摘要：pydantic 是一个基于 Python 类型注解的数据验证与解析库，支持自动校验、类型转换、嵌套模型、导入导出、配置管理等功能。它广泛用于数据清洗、API 参数校验、配置系统构建，尤其是 FastAPI 等现代 Web 框架的核心组件之一。
pydantic 是一个基于 Python 类型注解的数据验证与解析库，支持自动校验、类型转换、嵌套模型、导入导出、配置管理等功能。它广泛用于数据清洗、API 参数校验、配置系统构建，尤其是 FastAPI 等现代 Web 框架的核心组件之一。
其核心优势在于：类型驱动的声明式编程 + 自动数据转换 + 详细错误信息 + 高性能。
安装 ：
pip install pydantic提示：
pydantic v2 为重写版本，性能大幅提升，推荐新项目使用。
若需保持旧版本兼容性，指定版本安装：
pip install "pydantic常见应用场景：
（1）定义结构化数据模型，并自动验证字段类型。
（2）将 dict / JSON 数据解析为强类型对象。
（3）使用嵌套模型表示复杂数据结构。
（4）从 .env 或环境变量中加载配置。
（5）配合 FastAPI 实现请求/响应体校验与文档生成。
（6）将模型对象导出为 dict / JSON / 标准数据结构。
◆ ◆ ◆
核心概念
1、BaseModel 数据模型
所有模型类需继承自 BaseModel，字段使用类型注解定义。
2、自动类型转换与验证
支持将字符串转为数字、解析布尔值、解析嵌套对象等。
3、清晰的错误提示
当验证失败时，自动提供字段级别的详细错误信息。
4、嵌套模型与类型支持
字段可为其他模型、List、Dict、Union、Optional 等复杂结构。
5、数据导出与序列化
支持 .dict、.json、.model_dump 等方法导出清洗后的数据。
6、自定义验证器
可通过装饰器编写字段级或模型级的验证逻辑。
◆ ◆ ◆
应用举例
例 1：定义基本模型并验证输入
from pydantic import BaseModelclass User(BaseModel):id: intname: strage: int = 18user = User(id="123", name="Alice")print(user.age) # 18print(user.id) # 123（自动转换为 int）例 2： 嵌套模型与列表字段
from typing import Listfrom pydantic import BaseModelclass Address(BaseModel):city: strzip_code: strclass User(BaseModel):name: straddresses: List[Address]data = {"name": "mediaTEA","addresses": [{"city": "Changsha", "zip_code": "410-0001"}]}user = User(**data)print(user.addresses[0].city) # Changsha例 3：校验失败时的错误信息
from pydantic import BaseModel, ValidationErrorclass Product(BaseModel):name: strprice: floattry:Product(name="Book", price="not a number")except ValidationError as e:print(e)例 4：自定义字段验证器
from lxml import htmlfrom pydantic import BaseModel, field_validator # pydantic v2class User(BaseModel):name: str@field_validator("name")def not_empty(cls, v):if not v.strip:raise ValueError("name 不能为空")return v例 5：导出模型为 dict / JSON
from pydantic import BaseModel, field_validatorclass User(BaseModel):name: str@field_validator("name")@classmethoddef not_empty(cls, v):if not v.strip:raise ValueError("name 不能为空")return vuser = User(name="Alice")print(user.model_dump) # 导出为 dict：{'name': 'Alice'}print(user.model_dump_json) # 导出为 JSON：'{"name": "Alice"}'例 6：配置管理（BaseSettings）
安装新的依赖：
pip install pydantic-settings（Pydantic V2）加载配置（需在脚本所在目录创建 .env 文件）：
from pydantic_settings import BaseSettingsclass AppConfig(BaseSettings):host: strport: int = 8000class Config:env_file = ".env" # 可选：指定环境变量文件config = AppConfigprint(config.host)◆ ◆ ◆
常用 API 与方法
（Pydantic v2 版）
BaseModel(**data)
创建模型实例，同时执行字段校验与类型转换。
参数：
data：字典或类似结构的数据（可嵌套）
返回：模型对象
异常：若校验失败，抛出 ValidationError
model_validate(data)
Pydantic v2 推荐的模型构造入口，功能等价于 BaseModel(**data)。
用途：适用于外部数据入模（如 JSON 请求体、配置字典等）
model_dump(*, mode='python', include=None, exclude=None, by_alias=False)
将模型导出为标准 Python 字典，默认用于业务处理或数据持久化。
参数：
mode：导出模式，"python"（默认）或 "json"（会将日期等序列化）
include / exclude：指定包含或排除字段（可传字段名集合）
by_alias：是否使用字段别名
返回：dict
model_dump_json(*, indent=None, include=None, exclude=None, by_alias=False)
导出为 JSON 字符串，等价于 v1 的 .json 方法。
参数：同 model_dump，新增 indent 控制格式化输出。
返回：str（JSON 字符串）
@field_validator(field_name, mode='after')
用于字段级校验与值清洗。mode='before' 表示转换前、after 表示转换后。
@field_validator("name")@classmethoddef check_name(cls, v): ...支持多个字段联用：
@field_validator("name", "email")@model_validator(mode='after'|'before')
用于模型级校验，可访问多个字段值组合判断是否合理。
@model_validator(mode="after")@classmethoddef validate_model(cls, values): ...model_construct(**data)
绕过验证快速创建模型，仅用于受信数据，如数据库原始值。
model_fields
返回字段定义的元数据字典：
print(User.model_fields)# {'name': FieldInfo(...), 'age': FieldInfo(...)}model_copy(update={})
复制模型实例，并可指定字段更新。
ValidationError
当输入数据不符合模型定义时抛出，包含完整的错误详情：
from pydantic_core import ValidationError◆ ◆ ◆
补充说明
1、Pydantic v1 与 v2 差异显著
2、类型系统兼容性更强
支持标准库中的 typing（如 Union, Literal, Annotated, NewType 等）。
可嵌套复杂结构（如 List[Dict[str, Union[int, None]]]）。
3、性能大幅提升
Pydantic v2 基于 Rust 实现的 pydantic-core。
序列化与验证速度比 v1 快 5~50 倍，适用于高性能服务（如 FastAPI）。
4、字段控制选项丰富
支持：
default、default_factory
alias（字段别名）
frozen=True（只读模型）
exclude=True（默认不导出）
json_schema_extra（添加 schema 元数据）
5、配置加载应使用 pydantic-settings
Pydantic v2 已将配置系统迁出主库：
6、错误信息与调试体验优化
校验错误信息结构化输出，便于日志记录、API 响应封装、自动化表单校验提示等。
7、生态适配广泛
Pydantic 是以下主流库的核心依赖：
FastAPI（API 参数与响应验证）
SQLModel（数据库 ORM 模型）
Typer（命令行参数绑定）
Beanie（MongoDB ODM）
LangChain（结构化数据建模）
“点赞有美意，赞赏是鼓励”
来源：鱼大科技说
