FastAPI如何实现统一返回结果格式并自定义状态码？

Question

在FastAPI项目中，如何实现统一的返回结果格式并自定义HTTP状态码？ 问题：当使用FastAPI开发RESTful API时，如何定义一个全局通用的响应模型，确保所有接口都返回一致的结果结构（如{"code": int, "message": str, "data": Any}），同时支持根据业务需求灵活设置不同的HTTP状态码？例如，业务逻辑中需要返回201 Created或400 Bad Request等特定状态码，而不仅仅是默认的200 OK。此外，在出现异常时，如何捕获并转换为标准化的错误响应格式？

Answer 1

1. 定义全局通用响应模型

在FastAPI中，可以通过定义一个Pydantic模型来实现统一的返回结果格式。这个模型可以包含`code`、`message`和`data`三个字段。以下是一个示例代码：

from pydantic import BaseModel
from typing import Any

class ResponseModel(BaseModel):
    code: int
    message: str
    data: Any = None
    

这个模型将作为所有接口的标准返回格式。通过继承`BaseModel`，我们可以确保数据类型的安全性和一致性。

1.1 使用ResponseModel封装返回值

在每个路由处理函数中，可以手动创建`ResponseModel`实例，并将其作为返回值。例如：

from fastapi import FastAPI

app = FastAPI()

@app.get("/example")
def example():
    return ResponseModel(code=200, message="Success", data={"key": "value"})
    

2. 自定义HTTP状态码

FastAPI允许为每个路由指定不同的HTTP状态码。这可以通过`status_code`参数在装饰器中设置。例如：

from fastapi import status

@app.post("/create-item", status_code=status.HTTP_201_CREATED)
def create_item():
    return ResponseModel(code=201, message="Item Created", data=None)
    

通过这种方式，可以根据业务需求灵活设置不同的HTTP状态码。

2.1 状态码与响应模型结合

当需要返回特定的状态码时，可以在返回值中直接使用`ResponseModel`，同时在装饰器中指定对应的状态码。这种组合方式能够满足大多数RESTful API的设计需求。

3. 异常捕获与标准化错误响应

在实际开发中，不可避免会遇到各种异常情况。为了保证接口的一致性，可以使用FastAPI内置的异常处理器来捕获并转换异常为标准化的错误响应格式。

3.1 定义自定义异常类

首先，定义一个自定义异常类，用于表示业务逻辑中的错误：

class CustomException(Exception):
    def __init__(self, code: int, message: str):
        self.code = code
        self.message = message
    

3.2 添加异常处理器

接下来，在应用中添加一个异常处理器来捕获`CustomException`并返回标准化的错误响应：

from fastapi import Request
from fastapi.responses import JSONResponse

@app.exception_handler(CustomException)
async def custom_exception_handler(request: Request, exc: CustomException):
    return JSONResponse(
        status_code=exc.code,
        content=ResponseModel(code=exc.code, message=exc.message, data=None).dict()
    )
    

4. 流程图展示整体逻辑

下面通过流程图展示如何在FastAPI项目中实现统一返回格式和自定义状态码：

            mermaid
            flowchart TD
                A[定义ResponseModel] --> B[创建路由并返回ResponseModel]
                B --> C[为路由指定状态码]
                C --> D[定义自定义异常类]
                D --> E[添加异常处理器]
                E --> F[运行应用]
        

5. 性能优化与扩展

在大规模项目中，可以进一步优化代码结构。例如，将`ResponseModel`和异常处理器封装到单独的模块中，以便复用。此外，还可以通过中间件对请求和响应进行全局监控和日志记录。

功能	实现方式
统一返回格式	定义Pydantic模型
自定义状态码	在装饰器中指定`status_code`
异常处理	定义自定义异常类和异常处理器