【学习心得】Python的Pydantic（简介）

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

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

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

一、基本用法

bash 复制代码

pip install pydantic

1、定义模型

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

python 复制代码

from pydantic import BaseModel

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

2、实例化与验证

python 复制代码

# 从字典创建实例
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 会抛出清晰的错误提示，而不是让程序在后续运行中崩溃。

python 复制代码

from pydantic import ValidationError

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

3、字段约束

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

python 复制代码

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、嵌套使用

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

python 复制代码

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 文件）。

bash 复制代码

pip install pydantic-settings

python 复制代码

from pydantic_settings import BaseSettings

class Settings(BaseSettings):
    db_url: str
    api_key: str

    class Config:
        env_file = ".env"

settings = Settings() # 自动从环境变量加载并校验