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

前言

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

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

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

pip install fastapi uvicorn
1

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: int
    message: str
    data: Optional[T] = None
    class Config:
        # 允许使用泛型模型
        arbitrary_types_allowed = True
1
2
3
4
5
6
7
8
9
10
11
12
13

解释：

• 泛型类型变量 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: int
    name: str
    description: 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")
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24

解释：

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

4. 启动应用并访问 API

你可以使用以下命令运行 FastAPI 应用：

uvicorn main:app --reload
1

启动应用后，你可以通过以下 URL 访问 API 并查看响应结构：

• http://127.0.0.1:8000/items/ 获取所有项目信息。
• http://127.0.0.1:8000/items/1 获取特定项目的详细信息。

5. 结论

通过在 FastAPI 项目中实现通用返回结构，我们可以确保所有 API 响应都遵循一致的格式。这不仅有助于提升代码的可维护性，还可以让前端开发人员更轻松地处理数据。使用 Python 的注解类型和 pydantic，我们能够灵活地定义响应模型，并通过泛型支持多种数据类型。