当前位置：首页 > news >正文

在 FastAPI 项目中使用 Python 注解类型实现通用返回结构

news 来源：原创 2024/9/20 0:14:54

前言

在开发 API 时，确保一致的响应结构是一个良好的实践。无论是前端开发人员还是后端开发人员，都希望能够依赖一个统一的返回格式，这样可以简化调试和处理逻辑。在这篇文章中，我们将探讨如何在 FastAPI 项目中使用 Python 的注解类型和 pydantic 模块来实现一个通用的返回结构。

1. 快速入门：安装 FastAPI 和 Uvicorn

如果你还没有安装 FastAPI 和 Uvicorn，可以通过以下命令进行安装：

pip install fastapi uvicorn

FastAPI 是一个现代的、快速的（高性能的）Web框架，用于构建基于标准 Python 类型提示的 API，Uvicorn 是一个用于运行 ASGI 应用的轻量级和快速的 ASGI 服务器。

2. 定义通用返回结构

为了实现一个统一的响应结构，我们首先需要定义一个通用的响应模型。在 Python 中，我们可以使用 pydantic 的 BaseModel 来实现这个结构。

from fastapi import FastAPI
from pydantic import BaseModel
from typing import Generic, TypeVar, Optional
# 定义一个泛型类型变量
T = TypeVar('T')
# 定义通用响应模型
class ResponseModel(Generic[T], BaseModel):code: intmessage: strdata: Optional[T] = Noneclass Config:# 允许使用泛型模型arbitrary_types_allowed = True

解释：

泛型类型变量 T：通过使用泛型，ResponseModel 可以接收任意类型的数据（例如列表、字典、字符串等），并将其包装在一个统一的响应结构中。
code: int 和 message: str：这两个字段表示 API 的响应状态码和消息，方便前端判断和展示。
data: Optional[T]：表示实际的数据内容，该字段是可选的，可以为任何类型的数据。

3. 创建 FastAPI 应用并使用通用响应模型

接下来，我们将创建一个简单的 FastAPI 应用，演示如何使用上面定义的通用响应模型。

from fastapi import FastAPI, HTTPException
from typing import List
app = FastAPI()
# 定义一个数据模型
class Item(BaseModel):id: intname: strdescription: Optional[str] = None
# 定义一个返回包含多个Item的响应模型
ItemListResponse = ResponseModel[List[Item]]
@app.get("/items/", response_model=ItemListResponse)
async def get_items():items = [Item(id=1, name="Item 1", description="This is item 1"),Item(id=2, name="Item 2", description="This is item 2"),]return ItemListResponse(code=200, message="Success", data=items)
@app.get("/items/{item_id}", response_model=ResponseModel[Item])
async def get_item(item_id: int):if item_id == 1:item = Item(id=1, name="Item 1", description="This is item 1")return ResponseModel(code=200, message="Success", data=item)else:raise HTTPException(status_code=404, detail="Item not found")

解释：

Item 数据模型：Item 类表示我们 API 中的一个项目，每个项目有 id、name 和可选的 description 字段。
ItemListResponse：我们使用 ResponseModel[List[Item]] 定义了一个返回多个 Item 的响应结构。
get_items 和 get_item：这两个路由函数演示了如何使用通用响应模型来返回数据。如果请求成功，返回的数据将包含在 data 字段中，并且 code 和 message 字段将传递额外的状态信息。