FastAPI 響應(yīng)模型：Pydantic 的數(shù)據(jù)驗(yàn)證與轉(zhuǎn)換，一篇吃透！
是否遇到過這些問題？
- 數(shù)據(jù)庫返回字段太多，前端只要幾個(gè)？
- 接口文檔不一致，測(cè)試?yán)鲜菆?bào)錯(cuò)？
- ORM 對(duì)象直接返回，總是類型錯(cuò)誤？
快用 FastAPI 的響應(yīng)模型（response_model）+ Pydantic，自動(dòng)校驗(yàn)、轉(zhuǎn)換、過濾、文檔全搞定！
1. 什么是響應(yīng)模型？
響應(yīng)模型用于定義接口的返回結(jié)構(gòu)。FastAPI 會(huì)根據(jù)響應(yīng)模型：
- 自動(dòng)校驗(yàn)字段類型
- 自動(dòng)過濾多余字段
- 自動(dòng)轉(zhuǎn)換格式
- 自動(dòng)生成文檔（OpenAPI）
2. 快速上手：定義響應(yīng)結(jié)構(gòu)
from pydantic import BaseModel
class UserOut(BaseModel):
id: int
name: str
email: str在接口中使用：
from fastapi import FastAPI
app = FastAPI()
@app.get("/users/{user_id}", response_model=UserOut)
def get_user(user_id: int):
return {
"id": user_id,
"name": "Alice",
"email": "alice@example.com",
"is_admin": True # 會(huì)自動(dòng)被過濾掉
}最終返回只包含指定字段：
{
"id": 1,
"name": "Alice",
"email": "alice@example.com"
}3. 支持嵌套模型和列表模型
class Address(BaseModel):
city: str
country: str
class UserOut(BaseModel):
id: int
name: str
address: Address列表結(jié)構(gòu)也支持：
@app.get("/users/", response_model=list[UserOut])
def get_users():
return [...]4. ORM 模式（必須開啟）：與數(shù)據(jù)庫模型打通
如果你使用 SQLAlchemy、Tortoise ORM 等，接口函數(shù)中返回的是 ORM 實(shí)例而不是字典，就必須開啟 “ORM 模式”。
為什么要開啟？
因?yàn)?ORM 對(duì)象不是標(biāo)準(zhǔn)字典，Pydantic 默認(rèn)不能識(shí)別對(duì)象的屬性，需要開啟專用模式：
(1) Pydantic v1 的寫法
class UserOut(BaseModel):
id: int
name: str
class Config:
orm_mode = TrueFastAPI 會(huì)自動(dòng)調(diào)用 obj.__dict__ 或?qū)傩苑椒ǎ崛∽侄巍?/p>
(2) Pydantic v2 的寫法（推薦）
class UserOut(BaseModel):
id: int
name: str
model_config = {
"from_attributes": True # 替代 orm_mode
}from_attributes=True 更加清晰地表明“這個(gè)模型的字段可以從屬性中提取”。
(3) 搭配 SQLAlchemy 使用示例
from sqlalchemy.orm import declarative_base
from sqlalchemy import Column, Integer, String
Base = declarative_base()
class User(Base):
__tablename__ = "users"
id = Column(Integer, primary_key=True)
name = Column(String)
# 響應(yīng)模型
class UserOut(BaseModel):
id: int
name: str
model_config = {
"from_attributes": True
}
@app.get("/users/{id}", response_model=UserOut)
def get_user(id: int, db: Session = Depends(get_db)):
return db.query(User).get(id)(4) 搭配 Tortoise ORM 使用示例
from tortoise.models import Model
from tortoise import fields
class User(Model):
id = fields.IntField(pk=True)
name = fields.CharField(max_length=50)
class UserOut(BaseModel):
id: int
name: str
model_config = {
"from_attributes": True
}
@app.get("/users/{id}", response_model=UserOut)
async def get_user(id: int):
user = await User.get(id=id)
return user5. 響應(yīng)字段別名與描述（自動(dòng)生成文檔）
from pydantic import Field
class UserOut(BaseModel):
id: int
name: str = Field(..., alias="username", description="用戶名")返回結(jié)構(gòu)變?yōu)椋?/p>
{
"id": 1,
"username": "Alice"
}在 Swagger 文檔中也能自動(dòng)顯示字段描述！
6. Pydantic v1 vs v2 對(duì)比
功能點(diǎn) | v1 | v2（推薦） |
底層實(shí)現(xiàn) | Python 實(shí)現(xiàn) | Rust 實(shí)現(xiàn)（pydantic-core） |
性能 | 一般 | ?? 提升 5~50 倍 |
默認(rèn)值聲明 | 可用 = | 推薦使用 Field() 顯式寫法 |
ORM 支持 | Config.orm_mode = True | model_config = {"from_attributes": True} |
JSON 解析 | Python 實(shí)現(xiàn) | 快速原生 JSON 序列化 |
聯(lián)合類型支持 | 較弱 | 強(qiáng)化了對(duì) Union, Annotated 的支持 |
7. 總結(jié)
response_model 是 FastAPI 最強(qiáng)大功能之一，搭配 Pydantic 使用，自動(dòng)：
- 校驗(yàn)字段
- 過濾無用字段
- 自動(dòng)格式轉(zhuǎn)換
- 自動(dòng)生成 Swagger 文檔
- 無縫對(duì)接 ORM 模型對(duì)象
ORM 模式配置（orm_mode 或 from_attributes）一定不能忘，否則可能會(huì)返回空數(shù)據(jù)、字段丟失等問題。
