Python中 Pydantic数据验证库

张

张建站

2026/5/22 9:04:45

10分钟阅读

Pydantic 是 Python 中最流行的数据验证的第三方库它提供了一种声明式的方式来定义数据模型基于类型注解工作具有高性能核心验证逻辑用 Rust 编写和优秀的 IDE 集成。一、类型注解与验证Pydantic 的核心是声明式数据建模。通过继承BaseModel并定义带类型注解的类属性来声明数据模型。Pydantic 会自动进行数据验证确保数据符合声明的类型。数据转换Coercion在可能的情况下自动将输入数据转换为声明的类型。序列化将模型实例导出为字典或 JSON。二、快速上手基础使用1. 安装与导入pip install pydanticfrom datetime import datetime from pydantic import BaseModel from typing import Optional, Dict, List2. 定义第一个模型一个User模型演示了不同类型的字段。class User(BaseModel): id: int # 必填字段会尝试将 1 转为 1 name: str Jane Doe # 有默认值成为可选字段 signup_ts: Optional[datetime] None # 可为空的 datetime tastes: Dict[str, int] {} # 字典类型值为正整数3. 数据验证与实例化实例化时传入数据Pydantic 会自动进行类型转换和验证。# 这是外部数据比如来自 API 或配置文件 external_data { id: 123, # 注意这是字符串 signup_ts: 2024-10-01 12:00, # 字符串日期 tastes: { wine: 5, cheese: 3, }, } # 实例化模型验证并转换数据 user User(**external_data) # 访问属性已转换为正确的类型 print(user.id) # 输出: 123 (int) print(user.signup_ts) # 输出: 2024-10-01 12:00:00 (datetime) print(user.model_dump()) # 输出字典: {id: 123, name: Jane Doe, ...}4. 处理验证错误当数据不符合规范时Pydantic 会抛出ValidationError并提供清晰的错误信息。from pydantic import ValidationError invalid_data { id: not_a_number, # 无法转为 int signup_ts: invalid_date, # 无法转为 datetime } try: user User(**invalid_data) except ValidationError as e: print(e.json()) # 打印结构化的错误报告三、进阶功能增强模型能力1. 使用Field添加约束和描述Field函数可以给字段添加额外的验证规则如长度、数值范围和元数据。from pydantic import BaseModel, Field class Product(BaseModel): name: str Field(min_length1, max_length50, description产品名称) price: float Field(ge0, le9999.99, description产品价格) stock: int Field(default0, ge0, description库存) product Product(nameLaptop, price999.99) print(product.model_dump()) # 输出: {name: Laptop, price: 999.99, stock: 0}备注这是Pydantic 库的语法BaseModel在底层自动生成了__init__方法所以不需要手动写。Field是用于添加字段描述的不影响类型本身。Field常用参数参数说明示例description字段描述用于文档Field(description用户姓名)default默认值Field(default未知)min_length字符串最小长度Field(min_length1)max_length字符串最大长度Field(max_length100)ge数值 ≥Field(ge0)le数值 ≤Field(le100)example示例值用于文档Field(example张三)2. 嵌套模型与复杂类型Pydantic 模型可以无缝嵌套轻松处理复杂的 JSON 数据。from typing import List class Address(BaseModel): city: str street: str class Student(BaseModel): name: str age: int addresses: List[Address] # 嵌套模型列表 data { name: Alice, age: 20, addresses: [{city: Beijing, street: Changan Ave}] } student Student(**data) print(student.addresses[0].city) # 输出: Beijing3. 自定义验证器使用field_validator或model_validator装饰器实现复杂的业务逻辑验证。from pydantic import BaseModel, field_validator class Order(BaseModel): quantity: int price: float field_validator(quantity) classmethod def quantity_must_be_positive(cls, v: int) - int: if v 0: raise ValueError(quantity must be greater than 0) return v field_validator(price) classmethod def price_must_be_positive(cls, v: float) - float: if v 0: raise ValueError(price must be greater than 0) return v4. 严格模式默认情况下 Pydantic 是“宽松”的lax mode会尝试转换类型。可以通过model_config启用严格模式来禁止类型转换。from pydantic import BaseModel, ConfigDict class StrictUser(BaseModel): model_config ConfigDict(strictTrue) id: int # StrictUser(id123) # 这会直接报错因为输入的是字符串而 strictTrue四、总结特性说明使用场景数据验证通过类型注解和Field自动完成。验证API请求、配置文件、环境变量。类型转换智能将1转为12024-10-01转为datetime。处理来自HTTP查询参数或字符串配置的数据。序列化.model_dump()和.model_dump_json()方法。将模型数据输出到数据库或响应API。嵌套模型模型可作为字段类型完美对应复杂JSON。处理具有层级结构的复杂数据。错误处理ValidationError提供详细且可编程的错误报告。向客户端返回结构化的错误信息。备注:拥抱类型注解用类型注解定义清晰的接口充分利用 IDE 的自动补全和检查功能。模型与业务分离将 Pydantic 模型看作系统的“边界”入口和出口数据定义而非内部业务逻辑对象。善用model_dump()在存储或传输数据时应使用此方法显式导出数据而不是直接访问__dict__。更多用法可以参考中文官网介绍https://pydantic.com.cn/