FastAPI中Pydantic的用法

一、Pydantic 的 BaseModel 核心价值

Pydantic 的 BaseModel 是 Python 类型注解驱动的数据验证和序列化工具，核心解决以下问题：

---

1. 数据验证自动化

• 传统痛点：手动编写 if-else 校验逻辑，代码冗余且易出错

• BaseModel 方案：通过类型注解自动验证字段类型、格式和约束

from pydantic import BaseModel, EmailStr, conint

class User(BaseModel):
    name: str                    # 必须为字符串类型
    email: EmailStr              # 自动验证邮箱格式
    age: conint(gt=0, lt=150)    # 必须为 1-149 的整数

---

2. 类型强制转换

• 传统痛点：HTTP 请求参数（如字符串 "42"）需手动转换为 int

• BaseModel 方案：自动执行类型转换

class Item(BaseModel):
    id: int
    price: float

# 输入 {"id": "123", "price": "99.9"} 会被自动转换为：
# Item(id=123, price=99.9)

---

3. 序列化与反序列化

• 传统痛点：ORM 对象无法直接转为 JSON，需手动处理

• BaseModel 方案：通过 .dict() 或 .json() 方法快速序列化

user = User(name="Alice", email="[email protected]", age=30)
print(user.dict())  # 输出: {'name': 'Alice', 'email': '[email protected]', 'age': 30}

---

4. API 文档自动生成

• 传统痛点：需手动维护 Swagger 文档，容易与实际代码不一致

• BaseModel 方案：FastAPI 自动提取模型结构生成交互式文档

from fastapi import FastAPI

app = FastAPI()

@app.post("/users")
def create_user(user: User):  # 自动生成 Swagger 文档中的 Request Body Schema
    return user

---

二、关键用法示例

1. 基础模型定义

from pydantic import BaseModel

class Book(BaseModel):
    title: str
    author: str
    year: int
    is_published: bool = False  # 带默认值的可选字段

---

2. 复杂数据校验

from pydantic import BaseModel, field_validator

class Product(BaseModel):
    sku: str
    price: float

    @field_validator("sku")
    def sku_must_be_uppercase(cls, v):
        if not v.isupper():
            raise ValueError("SKU 必须全大写")
        return v

    @field_validator("price")
    def price_must_be_positive(cls, v):
        if v <= 0:
            raise ValueError("价格必须大于 0")
        return v

---

3. 嵌套模型

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

class Company(BaseModel):
    name: str
    address: Address  # 嵌套模型

# 使用示例
data = {
    "name": "Tech Corp",
    "address": {
        "street": "Main St",
        "city": "New York"
    }
}
company = Company(**data)

---

4. 与 ORM 对象互转（需配置 orm_mode）

class UserBase(BaseModel):
    class Config:
        from_attributes = True  # 旧版本用 orm_mode = True

class UserCreate(UserBase):
    email: str
    password: str

# 从 SQLAlchemy 模型转换
db_user = UserORM(email="[email protected]", password_hash="...")
user = UserCreate.model_validate(db_user)  # 自动提取匹配字段

---

三、对比传统方案的优势

场景	传统方法	Pydantic BaseModel
数据验证	手动编写校验函数	声明式类型注解自动验证
错误处理	分散的 try-except 块	集中抛出 ValidationError 包含所有错误详情
文档维护	手动编写接口文档	自动生成 OpenAPI/Swagger 文档
类型转换	显式调用 int()/str() 转换	根据注解自动转换
嵌套数据结构	多层字典手动解析	通过嵌套模型自动验证和结构化

---

四、最佳实践建议

1. 分层定义模型

   • 区分 Request Schema (输入) 和 Response Schema (输出)

   class UserCreate(BaseModel):  # 输入模型（包含密码）
       email: str
       password: str
   
   class UserResponse(BaseModel):  # 输出模型（排除敏感字段）
       id: int
       email: str
   

2. 复用模型配置

   class ConfigMixin:
       from_attributes = True  # 启用 ORM 兼容模式
   
   class UserResponse(BaseModel):
       id: int
       email: str
       class Config(ConfigMixin):
           pass
   

3. 组合复杂校验

   from pydantic import Field
   
   class Task(BaseModel):
       title: str = Field(..., min_length=3, max_length=100)
       priority: int = Field(gt=0, le=3, description="1-低, 2-中, 3-高")
   

---

通过 Pydantic 的 BaseModel，开发者可以大幅减少样板代码，同时获得类型安全、自动验证和清晰的文档化接口，是构建健壮 API 的核心工具。