使用 FastAPI 的 response_model
参数
在构建 RESTful API 时,确保数据的一致性和正确性是非常重要的。FastAPI 提供了强大的工具来帮助开发者实现这一目标。其中一个关键特性是 response_model
参数,它允许开发者定义期望的响应格式,并自动处理数据的序列化、验证和文档生成。
什么是 response_model
?
response_model
是 FastAPI 中的一个参数,它用于声明 API 响应的数据模型。这不仅可以确保响应数据的类型正确,还可以自动验证数据,并在 API 文档中为响应添加 JSON Schema。这意味着,使用 response_model
,你可以减少手动编写和验证代码的工作量,同时提高 API 的可维护性和可读性。
response_model
的类型
response_model
可以接收多种类型的参数,包括:
- Pydantic 模型:这是最直接的用法,你可以定义一个 Pydantic 模型来描述响应的数据结构。
- Pydantic 模型列表:如果你的 API 需要返回一个对象列表,你可以使用
List[Model]
来声明。
response_model
的作用
使用 response_model
有以下几个好处:
- 数据转换:FastAPI 会自动将输出数据转换为声明的类型。
- 数据验证:在发送响应之前,FastAPI 会验证数据是否符合模型定义。
- JSON Schema:在 OpenAPI 的路径操作中,FastAPI 会为响应添加一个 JSON Schema,这有助于客户端理解响应结构。
- 文档生成:FastAPI 的自动文档系统会使用
response_model
来生成更准确的 API 文档。
简单的示例代码
简单的输出响应类
from fastapi import FastAPI
from pydantic import BaseModel
app = FastAPI()
class Item(BaseModel):
name: str
description: str = None
price: float
tax: float = None
@app.get("/items/{item_id}", response_model=Item)
async def read_item(item_id: int):
return {"name": "Item Name", "price": 10.5, "tax": 1.5}
在这个示例中,我们定义了一个 Item
模型,并在路由中使用 response_model=Item
来声明响应模型。这样,FastAPI 会自动处理响应数据的序列化和验证。
常见示例代码
将 ApiResponse 作为 response_model 并加入 token 验证的功能,一般用于登录和验证输出结果
from fastapi import FastAPI, Depends, HTTPException, Header
from pydantic import BaseModel
app = FastAPI()
# 定义用户模型
class User(BaseModel):
user_id: int
name: str
sex: int
# 定义响应模型,包含嵌套的用户模型
class ApiResponse(BaseModel):
status: str
code: int
data: User
# 创建一个依赖项,用于获取请求头中的 token
def get_token(token: str = Header(None)):
if token != "correct-token":
raise HTTPException(status_code=401, detail="Invalid or missing token")
return token
# 创建一个路由,使用 ApiResponse 作为响应模型,并获取 token
@app.get("/user", response_model=ApiResponse)
async def get_user(token: str = Depends(get_token)):
# 这里可以根据 token 进行一些逻辑处理,例如验证 token 并获取用户信息
# 为了示例,我们直接返回一个固定的用户信息
return ApiResponse(
status="success",
code=0,
data=User(user_id=100, name="sdw", sex=0)
)
# 运行应用
if __name__ == "__main__":
import uvicorn
uvicorn.run(app, host="0.0.0.0", port=8000)
在这个示例中,我们做了以下修改:
- 定义模型:定义了
User
和ApiResponse
模型。 - 创建依赖项:
get_token
函数用于从请求头中获取token
并进行验证。如果token
不正确,抛出HTTPException
。 - 使用
response_model
:在get_user
路由中,我们使用response_model=ApiResponse
来指定响应模型。 - 处理请求:在
get_user
路由中,我们注入get_token
依赖项,并返回一个ApiResponse
实例。
要测试这个路由,你可以使用工具如 curl
或 Postman 发送一个带有正确 token
的 GET 请求:
curl -H "Authorization: Bearer correct-token" http://localhost:8000/user
这将返回预期的 JSON 响应。如果 token
不正确,将返回一个 401 错误。注意,我们将 token
放在 Authorization
请求头中,这是一种常见的做法。