Python的Pydantic概念及基本用法

2026-01-14 09:37:48 作者：小oo呆

Pydantic是一个Python库,用于数据验证和解析,它基于TypeHints,提供数据验证和解析功能,基本用法包括定义模型、实例化与验证、字段约束和嵌套使用,常见应用场景包括Web API、配置管理等,这篇文章介绍Python的Pydantic概念及基本用法,感兴趣的朋友跟随小编一起看看吧

Pydantic是Python生态中最流行的数据验证和解析库。绝大多数的Web框架（如FastAPI）和大模型框架LangChain都是基于它构建。简单说他是一个基于Type Hints的库。其核心功能有两个，分别是：

数据验证（Validation）：确保你拿到的数据，符合你定义的格式
数据解析（parsing）：把凌乱的输入，自动转换成正确的类型

只要模型实例化成功，你就可以百分之百信任这个对象里的数据类型是完全正确的。

一、基本用法

pip install pydantic

1、定义模型

使用 BaseModel 类来创建数据模型：

from pydantic import BaseModel
class User(BaseModel):
    name: str
    age: int  # 如果不匹配，Pydantic 会尝试强制转换
    is_active: bool = True  # 可以有默认值

2、实例化与验证

# 从字典创建实例
user = User(name="Alice", age="25")  # 注意：age 是字符串，但会被转为 int
print(user.name)      # Alice
print(user.age)       # 25 (int)
print(user.is_active) # True
# 访问原始数据
print(user.model_dump())  # {'name': 'Alice', 'age': 25, 'is_active': True}

如果数据不合规，Pydantic 会抛出清晰的错误提示，而不是让程序在后续运行中崩溃。

from pydantic import ValidationError
try:
    User(name="Bob", age="not_a_number")
except ValidationError as e:
    print(e.json()) # 会详细列出格式错误

3、字段约束

字段约束不仅能检查“类型”对不对，还能检查“内容”是否符合业务规则（比如：年龄不能是负数、密码不能太短）。使用 Field 来添加额外的验证规则：

from pydantic import BaseModel, Field
class Product(BaseModel):
    name: str = Field(min_length=2, max_length=50)
    price: float = Field(gt=0)  # 必须大于 0
    tags: list[str] = Field(default=[], min_items=1)
# 示例
Product(name="Laptop", price=999.99, tags=["electronics"])

约束缩写	全称	适用类型	说明
`gt`	greater than	`int`, `float`	大于
`ge`	greater than or equal	`int`, `float`	大于等于
`lt`	less than	`int`, `float`	小于
`le`	less than or equal	`int`, `float`	小于等于
`min_length`	-	`str`, `list`, `dict`	最小长度
`max_length`	-	`str`, `list`, `dict`	最大长度
`pattern`	-	`str`	正则表达式匹配
`allow_inf_nan`	-	`float`	是否允许无穷大或 NaN

4、嵌套使用

可以将不同的数据模型嵌套起来使用。

from typing import List, Optional
from pydantic import BaseModel, Field
# 1. 定义底层模型：商品
class Item(BaseModel):
    name: str
    price: float
    quantity: int = Field(gt=0, description="数量必须大于0")
# 2. 定义底层模型：收货地址
class Address(BaseModel):
    city: str
    street: str
    zip_code: Optional[str] = None
# 3. 定义顶层模型：订单（嵌套了 Item 和 Address）
class Order(BaseModel):
    order_id: int
    items: List[Item]  # 嵌套商品列表
    address: Address   # 嵌套地址对象
    remark: str = "无"
# --- 模拟原始数据（例如来自前端请求或数据库） ---
raw_data = {
    "order_id": 1001,
    "items": [
        {"name": "键盘", "price": 299.0, "quantity": 1},
        {"name": "鼠标", "price": 99.5, "quantity": 2}
    ],
    "address": {
        "city": "上海",
        "street": "南京东路 123 号"
    }
}
# 解析数据
order = Order(**raw_data)
# 访问嵌套数据
print(f"订单 ID: {order.order_id}")
print(f"第一件商品名称: {order.items[0].name}") # 自动补全非常爽
print(f"收货城市: {order.address.city}")

多级校验：当你实例化 Order 时，Pydantic 会递归校验。如果 items 列表里第二个商品的 price 格式不对，它会准确告诉你报错位置。
IDE 自动补全：在编写代码时，输入 order.address. 后，IDE 会自动提示 city 和 street。这避免了手动处理字典时经常出现的拼写错误。
自动转换：如果 items 里的 price 传的是字符串 "99.5"，Pydantic 会自动帮你转成 float。

二、常见应用场景

最常见的场景当然是web API。可以用它来定义 API 的请求体和响应体。FastAPI 会自动根据你的 Pydantic 模型生成文档，并自动校验前端传来的 JSON 数据。其次是进行配置管理，从环境变量或配置文件加载并验证配置。通过 pydantic-settings 扩展，可以轻松读取环境变量（.env 文件）。

pip install pydantic-settings

from pydantic_settings import BaseSettings
class Settings(BaseSettings):
    db_url: str
    api_key: str
    class Config:
        env_file = ".env"
settings = Settings() # 自动从环境变量加载并校验

到此这篇关于Python的Pydantic概念及基本用法的文章就介绍到这了,更多相关Python Pydantic内容请搜索脚本之家以前的文章或继续浏览下面的相关文章希望大家以后多多支持脚本之家！