FastAPI 统一响应封装（ApiResponse）最佳实践

在使用 FastAPI 开发接口时，如果每个接口返回格式不统一，会导致前后端对接非常混乱。

因此我们通常会封装一个统一响应类 ApiResponse，用于规范所有接口返回结构。

一、统一响应的意义

在没有统一封装时，接口返回可能是这样的：

{"msg": "成功"}
{"message": "ok", "data": []}
{"code": 200, "result": {}}

问题：

• 前端解析麻烦
• 字段不统一
• 后期维护成本高

二、统一响应结构设计

我们定义统一格式：

三、ApiResponse 封装代码

基于 Pydantic 实现：

from typing import Any
from pydantic import BaseModel


class ApiResponse(BaseModel):
    """统一响应结果"""

    code: int
    message: str
    data: Any = None

    @classmethod
    def success(cls, data: Any = None, message: str = "操作成功"):
        """
        成功返回
        """
        return cls(
            code=200,
            message=message,
            data=data
        )

    @classmethod
    def error(cls, message: str = "操作失败", code: int = 500):
        """
        失败返回
        """
        return cls(
            code=code,
            message=message,
            data=None
        )

四、在 FastAPI 中使用

1. 成功返回示例

from fastapi import APIRouter

router = APIRouter()

@router.get("/test")
def test():
   return ApiResponse.success(data={"name": "张三"})

返回：

{
 "code": 200,
 "message": "操作成功",
 "data": {
   "name": "张三"
 }
}

2. 失败返回示例

@router.get("/error")
def error():
   return ApiResponse.error(message="请求失败")

返回：

{
 "code": 500,
 "message": "请求失败",
 "data": null
}