Pydantic 基础教程

以下是一份最系统、最实用、最现代的《Python Pydantic 全面指南》，覆盖 Pydantic v1 与 v2（最新版），从入门到进阶、到 FastAPI 实战的最核心内容。

内容重点：

概念 + 基础 + 验证
Pydantic Model + Field
解析 / 序列化
自定义验证器
FastAPI 场景
项目最佳实践

🚀 1. 什么是 Pydantic？

Pydantic 是 Python 的数据模型与数据验证库，主要功能：

自动类型转换（type coercion）
自动校验数据格式
优雅的错误信息
JSON 友好
超快（Rust 加速，自 v2）

特别适合：

接口输入/输出（FastAPI 默认用它）
配置文件加载（env / json / yaml）
DTO（业务传输对象）
数据清洗与转换

📌 2. 最基础示例（Pydantic v2 风格）

from pydantic import BaseModel, Field

class User(BaseModel):
    id: int
    name: str
    active: bool = True

u = User(id="1", name="Tom")  # 自动把 "1" 转成 int
print(u)

输出：

id=1 name='Tom' active=True

📌 3. 字段定义与 Field

class User(BaseModel):
    id: int = Field(..., gt=0, description="用户ID")
    name: str = Field(min_length=1, max_length=50)
    age: int | None = Field(default=None, ge=0, le=120)

常用参数：

参数	作用
default / 默认值	字段的默认值
gt / ge / lt / le	数值范围
min_length / max_length	字符串长度
regex	正则匹配
description	文档描述（FastAPI 自动生成）

📌 4. 自动类型转换（Pydantic 强项）

User(id="123", name=456)

自动输出：

id=123 name='456'

📌 5. 数据解析（parse）

User.model_validate({"id": "1", "name": "Tom"})

从 JSON 字符串：

User.model_validate_json('{"id": 1, "name": "Tom"}')

📌 6. 模型序列化（dict / JSON）

u.model_dump()
u.model_dump_json()

可选：

u.model_dump(exclude={"active"})

📌 7. 嵌套模型

class Address(BaseModel):
    city: str
    zip: str

class User(BaseModel):
    name: str
    address: Address

使用：

User(name="Tom", address={"city": "Beijing", "zip": "100000"})

Pydantic 会自动把 dict 转为 Address 对象。

📌 8. 列表 / 字典 / 复杂结构

class Group(BaseModel):
    name: str
    members: list[User]

📌 9. Optional（可选字段）

两种写法等价：

email: str | None = None
# or
from typing import Optional
email: Optional[str] = None

📌 10. 枚举 + Pydantic

from enum import Enum

class Status(str, Enum):
    ACTIVE = "active"
    DISABLED = "disabled"

class User(BaseModel):
    name: str
    status: Status

📌 11. 自定义校验器（v2 新风格）

from pydantic import field_validator

class User(BaseModel):
    name: str

    @field_validator("name")
    @classmethod
    def validate_name(cls, v):
        if not v[0].isupper():
            raise ValueError("name must start with uppercase")
        return v

📌 12. Model-level 校验（整体校验）

from pydantic import model_validator

class Rectangle(BaseModel):
    width: int
    height: int

    @model_validator(mode="after")
    def check_area(self):
        if self.width * self.height > 10000:
            raise ValueError("Too large")
        return self

📌 13. Pydantic 的不可变模型（frozen）

class Config(BaseModel, frozen=True):
    host: str
    port: int

cfg = Config(host="localhost", port=3306)
# cfg.host = "127.0.0.1"   # ❌ 错误

📌 14. 模型继承

class User(BaseModel):
    id: int
    name: str

class Admin(User):
    role: str

📌 15. 配置文件解析（Settings）

非常适合读取 .env：

from pydantic_settings import BaseSettings

class Settings(BaseSettings):
    app_name: str = "MyApp"
    debug: bool = False

    class Config:
        env_file = ".env"

settings = Settings()

.env 内容自动加载。

📌 16. Pydantic + FastAPI（核心）

from pydantic import BaseModel
from fastapi import FastAPI

app = FastAPI()

class User(BaseModel):
    name: str
    age: int

@app.post("/user/")
def create_user(user: User):
    return user

FastAPI 自动：

接收 JSON -> 校验 -> 转换 -> 注入 User 对象
自动生成 OpenAPI 文档
错误自动返回 422

📌 17. Pydantic 的 JSON Schema（用于前端）

User.model_json_schema()

可以生成前端表单 / 类型系统使用的数据结构。

📌 18. Pydantic v1 与 v2 的区别（你必须知道）

功能	v1	v2
验证	Python 实现	Rust 超高速
语法	@validator	@field_validator
方法	.dict() .json()	model_dump() model_dump_json()
自定义校验	已废弃	更统一、更强
性能	较慢	8~30 倍提升

建议全面使用 v2。

📌 19. Pydantic 的常见用途（实战总结）

API 输入输出模型（最常见）
SQLAlchemy ORM <-> DTO 映射
Redis / MQ 消息结构
配置文件（Settings）
表单校验
Excel / CSV 数据清洗
大型项目的数据规范化

📌 20. 最推荐的 Pydantic 项目模板

你可以在项目中创建：

utils/
 ├── models/
 │     ├── user.py
 │     ├── news.py
 │     ├── common.py

例如：

class PageParams(BaseModel):
    pageIndex: int = Field(ge=1)
    pageSize: int = Field(ge=1, le=200)

非常适合分页、DTO 封装。

最终总结

Pydantic 是 Python 的核心数据工具，它：

让数据结构类型化
让数据验证自动化
让项目更安全可靠
在 FastAPI 中体验最佳