[Python/数据模型/数据校验] Python Pydantic 库 = Python 类型提示 + 自动数据校验 + 数据转换
0 序
- FASTAPI 框架的核心依赖: Pydantic,不得不学习一二。
1 Pydantic = Python 类型提示 + 自动数据校验 + 数据转换
Pydantic 是什么?
Pydantic是 Python 里一个主流的数据验证与数据模型构建库。其最大的特点是用 Python 类型注解(type hints)来做数据验证和转换。
Pydantic 是 Python 中使用最广泛的数据验证库。
Pydantic = Python 类型提示 + 自动数据校验 + 数据转换
- 想象你在写一个 API,用户传来的 JSON 数据乱七八糟:年龄传了字符串
"18"、邮箱格式不对、必填字段缺失……Pydantic 帮你自动检查这些问题,而且写法极其简洁。
即:
Pydantic是一个基于 Python 类型注解 的数据验证和模型管理库,广泛应用于需要处理复杂数据结构和确保数据一致性的场景。
它通过高效的验证逻辑和灵活的模型定义,帮助开发者提高代码的稳定性和可维护性。
- Pydantic
Pydantic 命名的由来 : Pydantic = Py + pedantic(学究式的、严谨的)
- 根据官方文档,Pydantic 的命名来源非常有趣:
Pydantic = Py + pedantic(学究式的、严谨的)
这是一个混成词(portmanteau)
| 部分 | 含义 | 解释 |
|---|---|---|
| Py | Python | 表明这是 Python 库 |
| pedantic | 学究式的、严谨的、一丝不苟的 | 指代库对数据验证的严苛态度 |
- 为什么叫"pedantic"?
官方文档的解释是:"
pedantic refers to the library's meticulous approach to data validation and type enforcement"
换句话说,Pydantic 像"学究"一样吹毛求疵地检查你的数据——类型不对就报错、格式不符就拒绝、约束不满足就抛异常。
- Pydantic 就是一个对数据"吹毛求疵"的 Python 库——宁可报错也不让脏数据溜过去。
这个命名既体现了技术特征(Python + 严格验证),又带点幽默感,非常符合开源社区的风格。
核心功能
-
Pydantic 的核心是
BaseModel类 -
自动类型转换:即使输入的类型不完全正确,也会自动尝试转换(比如字符串 "123" 自动转为整数)。
-
数据验证:根据字段的类型和限制条件自动校验。
-
自动文档化:配合 FastAPI 直接生成
Swagger接口设计文档。 -
嵌套模型:字段里可以嵌套另一个模型。
-
JSON 解析/导出:模型可以很方便地从/转为 JSON、字典等。
JSON Schema 生成:自动生成 JSON Schema,便于与其他工具集成。
-
高性能:核心验证逻辑使用 Rust 编写,速度快于大多数其他验证库。
-
类型注解支持:利用 Python 类型注解简化模型定义。
-
严格模式与宽松模式:支持严格模式(不自动转换数据类型)和宽松模式(尝试将数据转换为正确类型)。
-
自定义验证器:允许开发者定义自定义验证逻辑以满足特定需求。
-
错误处理:当数据验证失败时,Pydantic 会抛出详细的错误信息,帮助开发者快速定位问题。例如:
from pydantic import ValidationError
try:
User(id="not an int", signup_ts="invalid date")
except ValidationError as e:
print(e.errors())
输出将包含错误的字段、错误类型以及详细的错误描述。
安装与生态系统
- 安装 Pydantic 非常简单,只需运行以下命令:
pip install pydantic
Pydantic 被广泛应用于许多流行的 Python 项目,如 FastAPI、SQLModel 和 LangChain,并被全球众多知名公司使用。它的生态系统丰富,适用于各种数据处理场景。
Pydantic 是 Python 数据验证的强大工具,能够显著提升开发效率和代码质量。
2 核心概念、组件与工作原理
核心概念/核心组件:BaseModel
1. 最基础用法:定义 + 实例化
from pydantic import BaseModel
class User(BaseModel):
name: str
age: int
email: str
# 自动转换类型!"18" → 18
user = User(name="张三", age="18", email="zhangsan@example.com")
print(user.age) # 18 (int类型)
核心洞察:Pydantic 会尝试强制类型转换,只要合理就帮你转好。
2. 校验失败会怎样?
# 传错类型,自动抛错
user = User(name="张三", age="不是数字", email="invalid-email")
输出清晰的错误信息:
ValidationError: 2 validation errors for User
age
value is not a valid integer (type=type_error.integer)
email
value is not a valid email address (type=value_error.email)
这比你自己写 if isinstance(...) 优雅 100 倍。
最该掌握的核心特性与组件
1. 字段默认值与可选字段: pydantic.Field / typing.Optional
from typing import Optional
from pydantic import Field # Field 用于更复杂的配置
class Product(BaseModel):
name: str
price: float = 0.0 # 有默认值 → 可选
description: Optional[str] = None # 明确可为空
tags: list[str] = [] # 默认空列表
# 用 Field 加约束和描述
stock: int = Field(default=0, ge=0, description="库存必须≥0")
-
关键理解:
Optional[str]=str | None(Python 3.10+),表示可空。 -
ge即 "≥"
| 缩写 | 全称 | 含义 | 示例 |
|---|---|---|---|
ge |
greater than or equal | ≥ 大于等于 | ge=13 → 必须 ≥13 |
le |
less than or equal | ≤ 小于等于 | le=120 → 必须 ≤120 |
gt |
greater than | > 严格大于 | gt=0 → 必须 >0 |
lt |
less than | < 严格小于 | lt=100 → 必须 <100 |
min_length |
- | 最小长度 | min_length=2 |
max_length |
- | 最大长度 | max_length=20 |
pattern |
- | 正则匹配 | pattern=r"^\d+$" |
2. 嵌套模型(处理复杂 JSON): 基于 BaseModel
class Address(BaseModel):
city: str
street: str
class User(BaseModel):
name: str
# address: Address # 嵌套另一个模型!
address: Optional[Address] = None # ← 加 = None,变成可选
# 自动解析嵌套结构
data = {
"name": "李四",
"address": {"city": "北京", "street": "中关村大街"}
}
user = User(**data)
print(user.address.city) # 北京
这在做数据库模型、API 响应时极其常见。
3. 从字典/JSON 快速创建(实际开发最常用) : XxxBeanClass.model_validate/model_validate_json/model_dump/model_dump_json(xxxBeanData)
# 从字典
user_dict = {"name": "王五", "age": 20, "email": "wangwu@qq.com"}
user = User.model_validate(user_dict) # Pydantic V2 语法
# 从 JSON 字符串
json_str = '{"name": "赵六", "age": 25, "email": "zhao@qq.com"}'
user = User.model_validate_json(json_str)
# 转回字典/JSON(序列化)
print(user.model_dump()) # 字典 | eg: {'name': '赵六', 'address': None}
print(user.model_dump_json()) # JSON 字符串 | eg: {"name":"赵六","address":null}
⚠️ 注意:旧教程可能写
dict()和json(),那是 Pydantic V1。现在用model_dump()和model_dump_json()。
4. 数据转换与严格模式 : ConfigDict(strict属性)
from pydantic import BaseModel, ConfigDict
class StrictUser(BaseModel):
model_config = ConfigDict(strict=True) # 严格模式
name: str
age: int
# 严格模式下,"18" 不会自动转 int,必须传数字
StrictUser(name="张三", age=18) # ✅ 成功
# StrictUser(name="张三", age="18") # ❌ 失败(严格模式不转换)
什么时候用严格模式? 当你想强制前端传正确的类型,避免隐式转换带来的隐患。
实用技巧
配置类(ConfigDict)
class User(BaseModel):
model_config = ConfigDict(
strict=True # 是否开启严格模式
str_strip_whitespace=True, # 自动去空格 " 张三 " → "张三"
str_to_lower=True, # 自动转小写
frozen=True, # 冻结模式,创建后不可修改(类似 dataclass frozen)
extra='ignore', # 忽略未知字段('forbid' 则报错)
)
name: str
age: int
pydantic_settings.BaseSettings : 为加载配置而设计的、特殊的 Pydantic Model

-
pydantic_settings.BaseSettings来自pydantic-settings,本质上是一个特殊的 Pydantic Model。 -
它和普通 BaseModel 的最大区别是:
- 普通 BaseModel:只从你显式传入的数据创建对象。
- BaseSettings:会自动从多个“配置来源”读取数据,并且仍然执行 Pydantic 的类型校验、类型转换、约束校验。
也就是说,Settings 不只是“定义字段”,而是一个带校验能力的运行时配置对象。
- BaseSettings 默认会综合以下来源,常见优先级从高到低大致是:
- 构造函数显式传参,例如 Settings(openai_model="xxx")
- 环境变量,例如 OPENAI_MODEL
- .env 文件
- 文件 secrets 目录,如果配置了
- 字段默认值,例如 openai_model: str = "gpt-4o-mini"
SettingsConfigDict := Pydantic v2 风格的配置字典
- 示例代码
from pydantic import Field, SecretStr
from pydantic_settings import BaseSettings, SettingsConfigDict
class MySettings(BaseSettings):
model_config = SettingsConfigDict(
env_file=".env", # 创建 MySettings() 实例时,会读取当前工作目录下的 .env 文件
env_file_encoding="utf-8", # 定读取 .env 文件时使用 UTF-8 编码
extra="ignore", # 果 `.env` 或环境变量里出现了 MySettings 类未定义的字段,就忽略它们,而不是报错
)
openai_api_key: SecretStr | None = None
openai_base_url: str = "https://api.openai.com/v1"
openai_model: str = "gpt-4o-mini"
...
...
它等价于声明“这个自定义的 MySettings 类如何加载和解析配置”。
env_file=".env": 需要注意的是
- 这里是相对当前工作目录,不一定是源码文件所在目录。
.env是在MySettings()被实例化时读取的,不是在类定义时读取。- 项目从不同目录启动时,
.env的查找位置可能不同。
如果希望它更稳定,可以写绝对路径或根据项目根目录计算。
env_file_encoding="utf-8": 指定读取 .env 文件时使用 UTF-8 编码。
- 这对中文环境、包含非 ASCII 字符的配置比较重要,可以避免不同操作系统默认编码不一致导致的问题。
extra="ignore": 如果.env或环境变量里出现了 MySettings 类未定义的字段,就忽略它们,而不是报错。例如:
OPENAI_MODEL=gpt-4o
UNKNOWN_SETTING=whatever
UNKNOWN_SETTING 不是 MySettings 的字段,设置 extra="ignore" 后不会抛出异常。
如果不设置,在某些配置下可能会因为额外字段而失败,取决于 Pydantic 的默认行为和版本。
SecretStr : Pydantic 提供的“敏感字符串”类型
SecretStr是 Pydantic 提供的“敏感字符串”类型。
常用于:
- API Key
- Token
- 密码
- 私钥
- 数据库连接串中的敏感片段
- 普通字符串的问题
- 如果使用:
openai_api_key: str | None = None,那么:一旦这个对象被打日志,API Key 可能会原样输出而泄露:print(settings)输出可能是:
openai_api_key='sk-xxxx',这在日志、异常堆栈、调试输出中很危险。
SecretStr的行为
- 如果使用:
openai_api_key: SecretStr | None = None,那么:打印或日志输出时会遮蔽真实值:openai_api_key=SecretStr('**********')你仍然可以在代码中显式取回真实值:
settings.openai_api_key.get_secret_value()
例如传给 OpenAI 客户端时:api_key = settings.openai_api_key.get_secret_value()
如果值为 None,则表示没有配置 API Key。
@field_validator 注解: Pydantic 给所属函数对应的指定字段加【自定义校验规则、转换逻辑】 (必读)
- 示例
from pydantic import BaseModel, Field, field_validator
class ChatRequest(BaseModel):
"""单轮聊天请求的校验模型。"""
session_id: str = Field(min_length=1)
message: str = Field(min_length=1)
@field_validator("message") # 消息不能为空
@classmethod //python 原生注解, 静态的类方法
def message_must_not_be_blank(cls, value: str) -> str:
"""规范化空白并拒绝空消息。"""
value = value.strip()
if not value:
raise ValueError("message must not be blank")
return value
@field_validator("session_id")
@classmethod
def session_id_must_not_be_blank(cls, value: str) -> str:
"""规范化会话标识两侧空白。"""
value = value.strip()
if not value:
raise ValueError("session_id must not be blank")
return value
...
- 怎么理解
Field(min_length=1)是 Pydantic 的内置字段约束,只检查“长度至少为 1”。- 但
" "这种全空格字符串长度也大于 1,所以还需要自定义校验规则。@field_validator("message")表示:Pydantic 在校验message字段时,额外调用所在的函数。- 注解绑定的函数有2件事:归一化(
strip())和业务校验(空白则拒绝)。
- 执行流程
req = ChatRequest(session_id="s", message=" hi ")
- Pydantic 大致会调用:
value = ChatRequest.message_must_not_be_blank(" hi ")
- 函数内部:
value = " hi ".strip() # -> "hi"
return value # 返回值会成为 req.message
所以结果是:
req.message == "hi"
- 如果传入:
ChatRequest(session_id="s", message=" ")
内置
min_length=1可能通过,但自定义校验器会得到:value = " ".strip() # 即: ""
然后抛出:ValueError("message must not be blank")
-
Pydantic会把它包装成ValidationError。 -
为什么还用了
@classmethod
- 普通方法的第一个参数是
self,表示“某个已经创建的实例”。- 但字段校验发生在【实例对象的创建之前】,此时还没有可靠的
self。- 所以 Pydantic 的 validator 通常写成【类方法】,第一个参数是
cls,表示当前模型类。
- 等价理解是:
ChatRequest.message_must_not_be_blank(value)
这里:
cls == ChatRequest
如果以后有子类:
class ChildChatRequest(ChatRequest):
...
校验时 Pydantic 会把对应的类传给
cls。
- 装饰器顺序
@field_validator("message")
@classmethod
def message_must_not_be_blank(cls, value: str) -> str:
...
- Python 装饰器是从下往上执行的:
- 先执行
@classmethod- 再执行
@field_validator("message")- 最终注册成
message字段的 Pydantic 校验器
- 总结
Field:声明字段的基础约束。@field_validator:给某个字段加【自定义校验、转换逻辑】。@classmethod:让这个校验函数挂在类上,通过cls调用,而不是依赖实例self。
- 如果只是想去掉首尾空白并拒绝空字符串,Pydantic v2 也可以直接写成:
message: str = Field(min_length=1, strip_whitespace=True)
这样就不需要手写这个 validator。
快速对比:为什么不用 Python 原生的 dataclass?
| 特性 | dataclasses |
Pydantic |
|---|---|---|
| 类型转换 | ❌ 无 | ✅ 自动 |
| 数据校验 | ❌ 无 | ✅ 内置 |
| JSON 序列化 | ❌ 需手动 | ✅ 内置 |
| 嵌套验证 | ❌ 无 | ✅ 递归验证 |
| 性能 | ✅ 更快 | 稍慢(但生产环境足够) |
结论:需要数据校验 → 用 Pydantic;纯数据结构 → dataclass 更轻量。
一个完整的实战例子(模拟 API 参数校验): BaseModel, Field, EmailStr
from pydantic import BaseModel, Field, EmailStr
from typing import Literal
from datetime import date
class StudentRegister(BaseModel):
"""学生注册接口的参数模型"""
name: str = Field(min_length=2, max_length=20)
student_id: str = Field(pattern=r'^\d{10}$') # 正则:10位数字
email: EmailStr # 自动验证邮箱格式
gender: Literal["男", "女", "其他"] # 只能是这三个值
birthday: date
gpa: float = Field(ge=0, le=4.0) # 0-4 分制
# 计算属性(不存储,动态生成)
@property
def is_adult(self) -> bool:
from datetime import datetime
age = (datetime.now().date() - self.birthday).days / 365
return age >= 18
# 测试
try:
student = StudentRegister(
name="张三",
student_id="2023100001",
email="zs@university.edu.cn",
gender="男",
birthday=date(2003, 5, 20),
gpa=3.8
)
print(f"{student.name} 已注册,成年状态:{student.is_adult}")
except Exception as e:
print(f"注册失败:{e}")
学习路径建议(30分钟 → 掌握核心)
| 阶段 | 内容 | 时间 |
|---|---|---|
| 1 | 安装 + 写第一个 BaseModel | 5分钟 |
| 2 | 尝试传错数据,看报错信息 | 5分钟 |
| 3 | 练习嵌套模型 + 列表 | 10分钟 |
| 4 | 用 Field 加约束条件 |
5分钟 |
| 5 | 结合 FastAPI 写一个接口(进阶) | 按需 |
总结
- Pydantic 的核心是
BaseModel,像class一样定义,自动获得校验能力 - 类型即契约,写
int它就不会让你传字符串(除非能安全转换) model_validate进,model_dump出,这是数据流转的标准姿势
如果后续学习 FastAPI 框架,会发现 Pydantic 是标配——请求参数、响应模型、数据库 Schema 全都用它,现在学的每一分钟都在给未来省时间。
X 参考文献
本文链接: https://www.cnblogs.com/johnnyzen
关于博文:评论和私信会在第一时间回复,或直接私信我。
版权声明:本博客所有文章除特别声明外,均采用 BY-NC-SA 许可协议。转载请注明出处!
日常交流:大数据与软件开发-QQ交流群: 774386015 【入群二维码】参见左下角。您的支持、鼓励是博主技术写作的重要动力!

浙公网安备 33010602011771号