封装统一格式返回工具

当开发后端接口时，一个重要的任务是定义和封装统一的返回格式。在这方面，FastAPI 是一个强大而灵活的框架，可以帮助我们快速构建高性能的 Web 应用程序。

在后端开发中，封装统一的返回格式有以下几个好处：

规范性：统一的返回格式使得接口返回的数据具有一致的结构，便于前端或其他服务端进行解析和处理。这样可以提高开发团队成员之间的协作和沟通效率，降低开发和维护的难度。
统一错误处理：通过封装统一的返回格式，可以统一处理和包装异常信息。无论是系统级错误还是业务逻辑错误，都可以通过统一的返回格式进行标识和传递，使得错误处理更加方便和一致。
安全性：通过统一的返回格式，可以屏蔽敏感数据，例如密码、私密信息等，避免将敏感数据直接返回给客户端或其他服务端，提高系统的安全性。
可扩展性：通过封装统一的返回格式，可以方便地进行扩展和调整，例如在返回格式中添加额外的元数据、错误码、状态信息等，以满足不同的业务需求或协议要求。
用户体验：统一的返回格式可以提供一致的用户体验，无论是成功响应还是异常情况，用户都可以更好地理解和处理返回的数据。

定义统一响应类

涉及文件 app/common/response.py

python

from enum import Enum  
from typing import Optional, Any  
  
from fastapi.responses import JSONResponse  
  
from pydantic import BaseModel  
  
  
class APIResponse(BaseModel):  
    """ API 响应模型 """   
    code: int  
    msg: str  
    data: Optional[Any]  
  
class APICode(Enum):  
    """ API 响应状态码  """
    RUNTIME_ERROR = {'code': 500, 'msg': 'Runtime Error'}  
    SUCCESS = {'code': 200, 'msg': 'Success'}  
    INVALID_PARAMS = {'code': 400, 'msg': 'Invalid Params'}  
    USER_NOT_FOUND = {'code': 404, 'msg': 'User Not Found'}  
    USERNAME_EXISTED = {'code': 200, 'msg': 'Username Existed'}  
  
    @property  
    def code(self) -> int:  
        return self.value.get('code')  
  
    @property  
    def msg(self) -> str:  
        return self.value.get('msg')

APIResponse 继承于 pydantic.BaseModel，里面定义了 3 个字段，分别如下

code：状态码，200、400、500等；
msg：返回信息
data：如果需要返回数据，则包含此字段

APICode 是一个枚举类，可以定义一些返回的 code、msg，在所有需要返回 APIResponse 的地方全部从此类中选取 code、msg，方便后期统一管理。

使用场景

python

@staticmethod  
@router.get('/users/id/{user_id}', response_model=APIResponse)  
async def get_user(user_id: int, user_service: UserService = Depends(get_user_service)):  
    user = await user_service.query_user(user_id)  
    return APIResponse(code=APICode.SUCCESS.code, msg=APICode.SUCCESS.msg, data=user)

在 controller 层可以直接返回 APIResponse 对象，code、msg 从事先定义好的 APICode 中获取。

封装统一格式返回工具 #

定义统一响应类 #

使用场景 #

封装统一格式返回工具

定义统一响应类

使用场景