Pydantic 模型

Pydantic 模型 是一种基于 Python 的 数据验证和数据解析工具，它使用 Python 的类型注解（type hints）来定义数据结构，并自动进行校验、转换和序列化。

Pydantic 是一个使用 Python 类型注解进行数据验证和解析的库，能自动将输入的数据转换为目标类型并进行校验。

核心特点

基本用法

from pydantic import BaseModel

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

data = {
“id”: “123”,
“name”: “Alice”,
“email”: “alice@example.com”
}

user = User(**data)
print(user)
# id 会自动从字符串转为整数

输出：

id=123 name=’Alice’ email=’alice@example.com’ is_active=True

自动类型转换（类型强制）

Pydantic 会尝试自动将数据转成目标类型，比如：

class Data(BaseModel):
age: int

Data(age=”25″) # 字符串 “25” 会自动转成整数 25

验证失败时

from pydantic import ValidationError

try:
User(id=”abc”, name=”Bob”, email=”bob@example.com”)
except ValidationError as e:
print(e.json())

输出的是标准的 JSON 格式的错误信息。

嵌套模型

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

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

data = {
“name”: “Tom”,
“address”: {
“city”: “Shanghai”,
“zipcode”: “200000”
}
}

user = User(**data)
print(user.address.city) # 输出: Shanghai

与 FastAPI 结合

FastAPI 会自动将 HTTP 请求体映射成 Pydantic 模型：

from fastapi import FastAPI
from pydantic import BaseModel

app = FastAPI()

class Item(BaseModel):
name: str
price: float

@app.post(“/items/”)
async def create_item(item: Item):
return {“name”: item.name, “price”: item.price}

当你通过 POST 向 /items/ 发出如下 JSON 请求：

{
“name”: “iPhone 14”,
“price”: 799.99
}

BaseModel: Pydantic 的基础模型类，所有数据模型都需要继承它才能享受到数据验证、类型转换等特性。

FastAPI 会自动执行以下流程：

1、接收请求体（Request Body）中的 JSON。

2、尝试将 JSON 数据转换为 Item 类的实例：

item = Item(name=”iPhone 14″, price=799.99)

3、然后把这个对象作为参数传入 create_item(item) 中。

关键依赖：类型注解 + Pydantic

FastAPI 看到你用 item: Item 的类型注解，就知道：

• 请求体中应该包含 Item 的字段结构（name, price）

• 用 Pydantic 来验证并转换

但如果是：

{
“username”: “bob”,
“email”: “not-an-email”,
“age”: “未定义的格式”
}

或

{
“username”: “alice”,
“email”: “alice@example.com”,
“age”: 25,
“sex”: “男”
}

自动抛出错误（422 Unprocessable Entity）：

{
“detail”: [
{
“loc”: [“body”, “email”],
“msg”: “value is not a valid email address”,
“type”: “value_error.email”
},
{
“loc”: [“body”, “age”],
“msg”: “value is not a valid integer”,
“type”: “type_error.integer”
}
]
}

Pydantic 模型就是 FastAPI 中用于定义和校验数据结构的工具。

如何允许额外字段？

from pydantic import BaseModel, EmailStr, Extra

class User(BaseModel):
username: str
email: EmailStr
age: int

class Config:
extra = Extra.allow