FastAPI统一响应格式与全局异常处理实战技巧集

在使用 FastAPI 构建接口时，是否常遇到这些令人困扰的难题？

• 各接口返回格式五花八门，前端对接时难以理解？
• 抛出异常直接暴露刺眼的 500 页面，连开发者自己都难以定位错误根源？
• 希望统一处理日志、错误和响应结构，结果代码散乱如沙？

别着急，本文将手把手带你落地一套成熟的解决方案：统一响应结构 + 全局异常处理。让你的接口既规范又省心，后期维护时也能少掉几根头发。

为什么要统一响应格式？

统一返回格式的优势不言而喻：

• 前端开发人员再也不必对着千奇百怪的 JSON 结构反复猜测；
• 后期维护定位问题时，无需翻遍整个项目代码；
• 扩展能力强，轻松适配小程序、移动 App、Web 端等多种客户端场景。

推荐一套通用的标准格式，示例如下：

{
  "code": 0,
  "message": "OK",
  "data": {
    "id": 1,
    "name": "Alice"
  }
}

每个字段的含义清晰明确：code 代表业务状态码，message 为提示信息，data 才是真正的业务数据。前端拿到这个结构几乎无需思考即可解析。

响应模型封装

接下来，我们利用 Pydantic 泛型定义一个通用的响应模型。这样一来，无论 data 中存储的是用户信息、订单列表还是分页数据，都能通过同一套结构轻松搞定。

from pydantic.generics import GenericModel
from typing import Generic, TypeVar, Optional

T = TypeVar("T")

class Response(GenericModel, Generic[T]):
    code: int = 0
    message: str = "OK"
    data: Optional[T] = None

使用方法非常直观：只需在路由的 response_model 中声明 Response[UserOut]，返回时直接 Response(data=user) 即可。接口文档将自动展示完整的数据结构，前端也能获得稳定的类型提示。

@app.get("/user/{user_id}", response_model=Response[UserOut])
async def get_user(user_id: int):
    user = await User.get(id=user_id)
    return Response(data=user)

全局异常处理

FastAPI 默认的错误处理过于简单粗暴：异常直接抛 HTTP 500 和系统 Traceback，不适合直接暴露给客户端。我们需要自定义业务异常并注册全局处理器。

首先定义一个业务异常类：

class BusinessException(Exception):
    def __init__(self, code: int = 4001, message: str = "业务异常"):
        self.code = code
        self.message = message

然后注册两个异常处理器：一个专门用于处理业务异常，另一个兜底处理所有意料之外的系统异常。

from fastapi.responses import JSONResponse
from fastapi import Request, FastAPI

def register_exceptions(app: FastAPI):
    @app.exception_handler(BusinessException)
    async def business_exception_handler(request: Request, exc: BusinessException):
        return JSONResponse(
            status_code=200,
            content={
                "code": exc.code,
                "message": exc.message,
                "data": None
            }
        )

    @app.exception_handler(Exception)
    async def general_exception_handler(request: Request, exc: Exception):
        return JSONResponse(
            status_code=500,
            content={
                "code": 5000,
                "message": "系统异常",
                "data": None
            }
        )

请注意，业务异常我们依然返回 200 状态码，仅通过内部的 code 和 message 来区分具体错误——这样前端可用同一套逻辑处理正常响应和错误响应。而真正的系统异常则保留 500 状态码，便于运维监控。

在应用启动时调用一次 register_exceptions(app) 即可。

异常使用示例

借助这套机制，在业务代码中抛出异常变得非常优雅：

@app.get("/users/{user_id}", response_model=Response[UserOut])
async def get_user(user_id: int):
    user = await User.get_or_none(id=user_id)
    if not user:
        raise BusinessException(code=4040, message="用户不存在")
    return Response(data=user)

如果用户不存在，前端会收到一个结构清晰的 JSON：{"code": 4040, "message": "用户不存在", "data": null}，一目了然。

项目推荐结构

为了保持代码整洁且易于维护，建议按以下目录组织项目：

app/
├── main.py                # 启动入口
├── api/
│   └── user.py            # 路由模块
├── core/
│   ├── response.py        # 响应模型
│   ├── exception.py       # 异常类与注册器

下面给出核心文件的完整代码：

response.py

from pydantic.generics import GenericModel
from typing import Generic, TypeVar, Optional

T = TypeVar("T")

class Response(GenericModel, Generic[T]):
    code: int = 0
    message: str = "OK"
    data: Optional[T] = None

exception.py

from fastapi import Request, FastAPI
from fastapi.responses import JSONResponse

class BusinessException(Exception):
    def __init__(self, code: int = 4001, message: str = "业务异常"):
        self.code = code
        self.message = message

def register_exceptions(app: FastAPI):
    @app.exception_handler(BusinessException)
    async def business_handler(request: Request, exc: BusinessException):
        return JSONResponse(
            status_code=200,
            content={"code": exc.code, "message": exc.message, "data": None}
        )

    @app.exception_handler(Exception)
    async def global_handler(request: Request, exc: Exception):
        return JSONResponse(
            status_code=500,
            content={"code": 5000, "message": "系统错误", "data": None}
        )

main.py

from fastapi import FastAPI
from app.core.exception import register_exceptions
from app.api import user

app = FastAPI()
register_exceptions(app)
app.include_router(user.router)

总结

• 统一响应结构，让接口风格一致，前后端协作效率显著提升。
• 异常统一处理，既避免敏感信息泄露，又增强系统健壮性。
• 借助泛型封装响应模型，优雅实用，长期维护极其省心。