One post tagged with "Pydantic"

Python 的 Rust 化时刻：用 Pydantic 重构你的编程思维

如果你也是一名曾在 Rust 的强类型和所有权机制中找到安全感的开发者，或者是习惯了 Data Class + Function 这种数据与行为分离模式的后端工程师，当你回到 Python 的动态世界时，可能会有一种“裸奔”的不安感。

字典（Dict）满天飞，类型提示（Type Hint）形同虚设，运行时的 KeyError 像一颗颗地雷。

在我的技术栈中，Pydantic 早就不再仅仅是一个简单的“数据验证库”。它是 Python 通往“强类型”和“结构化思维”的唯一桥梁，是它让 Python 拥有了类似 Rust Struct 的严谨。

要把 Pydantic 用好，核心是将它视为 系统边界的守门人。以下是如何在项目中“重度”且“优雅”地使用 Pydantic 的 5 个层级。

层级 1：消灭字典传参 (The Death of Dict)

在传统的 Python 代码中，字典是数据传递的通用货币。这其实是维护的噩梦：你永远不知道 data['user_id'] 到底是 str 还是 int，甚至不知道这个 Key 是否存在。这被称为“Stringly Typed”编程。

做法：强制规定，系统边界以内，严禁裸奔的字典。

所有进入函数的复杂数据，必须在入口处转换为 Pydantic Model。

❌ 修改前 (裸奔的字典)

def process_data(data: dict):
    # 没有任何 IDE 提示，如果不看代码实现，不知道 data 里有什么
    # 容易因为拼写错误导致运行时崩溃
    if data.get('status') == 'active':
        return data['items']

✅ 修改后 (Rust 风格的 Struct)

from pydantic import BaseModel, Field
from typing import List, Literal

# 定义数据形状 (Data Shape)
class Item(BaseModel):
    name: str
    price: float

class Payload(BaseModel):
    # 使用 Literal 做枚举约束，类似 Rust 的 enum
    status: Literal['active', 'inactive'] 
    items: List[Item] = Field(default_factory=list)

# 函数签名即文档，IDE 甚至能补全 .status
def process_data(payload: Payload) -> List[Item]:
    if payload.status == 'active':
        return payload.items
    return []

收益：你获得了类似静态语言的编译期（IDE 静态检查）安全感。你的函数签名不再撒谎。

层级 2：配置管理 (Rust Config 风格)

做后端和 AI 开发，经常需要读取 API Keys, DB Host, Model Names。许多人习惯用 os.getenv() 甚至硬编码，导致配置分散且不安全。

做法：使用 pydantic-settings。

这非常像 Rust 的 Config crate，它将环境变量一次性加载为类型安全的对象。如果配置缺失或类型错误，程序启动即崩溃（Fail Fast），而不是在半夜运行到那行代码时才报错。

from pydantic_settings import BaseSettings

class AppConfig(BaseSettings):
    openai_api_key: str
    db_host: str = "localhost"
    db_port: int = 5432
    debug_mode: bool = False

    class Config:
        env_file = ".env" # 自动读取 .env 文件

# 初始化一次，全局使用单例
config = AppConfig()

# 使用时，完全类型安全
print(config.db_port + 1) # IDE 知道这是 int，完全放心的数学运算

收益：将配置加载从“运行时风险”变成了“启动时检查”。

层级 3：清洗即解析 (Parse, don't validate)

这是一个非常 Functional Programming (FP) 的理念：不要把验证看作是“检查”，而要看作是“数据变换”。

传统的验证是：给我数据 -> 我看看对不对 -> 抛出错误。解析的思维是：给我数据 -> 我把它变成我要的格式 -> 给我干净的对象。

Pydantic 的 field_validator 允许你在数据实例化的瞬间清洗数据。

场景：AI 训练数据清洗

输入可能是 " 123 ", "123", 或 123，或者是逗号分隔的字符串，但你的领域对象需要统一的 List[str]。

from pydantic import BaseModel, field_validator

class UserInput(BaseModel):
    tag_list: list[str]

    @field_validator('tag_list', mode='before')
    @classmethod
    def split_string_tags(cls, v):
        # 脏活累活在这里处理
        # 如果输入是 "a,b,c"，自动切分为 ['a', 'b', 'c']
        if isinstance(v, str):
            return [x.strip() for x in v.split(',')]
        return v

# 即使上游传了脏数据，这里也能自动清洗
data = UserInput(tag_list=" ai, python, rust ")
print(data.tag_list) 
# Output: ['ai', 'python', 'rust']

收益：你的核心业务逻辑（Function）永远只处理干净、标准的数据。

层级 4：AI 结构化输出 (Structured Output)

这是目前 Pydantic 最前沿 的用法。作为 AI 开发者，你一定遇到过 LLM 输出 JSON 格式不稳定的问题（比如多了一个逗号，或者 key 拼错）。

做法：将 Pydantic 作为 Schema 协议，强制 LLM 输出符合你定义的数据结构。

这在 OpenAI 的 Function Calling 或 instructor 库中是核心模式。

import instructor
from openai import OpenAI
from pydantic import BaseModel

# 1. 定义你想要的结果结构
class UserInfo(BaseModel):
    name: str
    age: int
    interests: list[str]

# 2. Patch 你的 OpenAI 客户端
client = instructor.from_openai(OpenAI())

# 3. 直接请求 Pydantic 对象，而不是文本
user_info = client.chat.completions.create(
    model="gpt-4o",
    response_model=UserInfo, # 关键：告诉 LLM 我只要这个结构
    messages=[
        {"role": "user", "content": "张三今年25岁，喜欢Rust和AI"}
    ],
)

# 4. 拿到的是真正的 Python 对象，不是 dict，也不是 json string
print(user_info.interests) # ['Rust', 'AI']

收益：将非结构化的自然语言（LLM Output）直接固化为代码可用的结构体。这是构建 AI Agent 的基石。

层级 5：作为数据库 Schema (SQLModel)

既然你用 FastAPI，你可能听说过 SQLModel。它是由 FastAPI 作者 Tiangolo 开发的，本质上就是 Pydantic + SQLAlchemy 的合体。

这意味着同一个 Class，既是：

API 验证层 (Pydantic)
数据库表定义 (SQLAlchemy Table)
业务数据容器 (Data Class)

from sqlmodel import SQLModel, Field

# 一个类，打通前后端和数据库
class Hero(SQLModel, table=True):
    id: int | None = Field(default=None, primary_key=True)
    name: str
    secret_name: str
    age: int | None = None

收益：消除了 DTO (Data Transfer Object) 和 DAO (Data Access Object) 之间的重复定义。极其适合不喜欢写重复样板代码（Boilerplate）的开发者。

总结：你的“Pydantic 进化论”

从脚本小子到架构师，Pydantic 的使用深度折射了你的编程思维变化：

维度	以前的做法 (Pythonic / Scripting)	你的新做法 (Rust-like / Engineering)
核心思维	只要代码能跑就行	结构化思维，类型安全
函数传参	`def f(d: dict)`	`def f(d: MyModel)`
配置管理	`os.environ.get()` 拼凑	`class Settings(BaseSettings)`
错误处理	运行时随缘报错	Fail Fast (启动即检查)
数据清洗	函数内手写 `if/else`	`@field_validator` (Parse, don't validate)
AI 交互	Prompt 工程 + 正则提取	`response_model=MyModel`
整体架构	逻辑与数据耦合	Data Class (Pydantic) + Function (Logic)

一句话建议

在你的下一个 Python 项目中，尝试禁止在函数参数和返回值中使用 dict。

强迫自己定义 Pydantic Model 来承载一切数据流动。你会发现，虽然写代码时的按键次数变多了（定义类），但调试代码的时间和运行时崩溃的概率会呈指数级下降。这就是结构化的力量。

层级 1：消灭字典传参 (The Death of Dict)​

❌ 修改前 (裸奔的字典)​

✅ 修改后 (Rust 风格的 Struct)​

层级 2：配置管理 (Rust Config 风格)​

层级 3：清洗即解析 (Parse, don't validate)​

场景：AI 训练数据清洗​

层级 4：AI 结构化输出 (Structured Output)​

层级 5：作为数据库 Schema (SQLModel)​

总结：你的“Pydantic 进化论”​

一句话建议​