Python基础入门 Day56：FastAPI 中的异常处理与全局错误响应机制

33次阅读

共计 1683 个字符，预计需要花费 5 分钟才能阅读完成。

在 Web 开发中，合理的异常处理机制能显著提升接口的健壮性和用户体验。FastAPI 提供了多种方式来处理局部和全局异常。

一、内置异常处理：HTTPException
FastAPI 提供 fastapi.HTTPException 用于主动抛出错误

from fastapi import HTTPException

@app.get("/items/{item_id}")
async def read_item(item_id: int):
    if item_id == 0:
        raise HTTPException(status_code=404, detail="Item not found")
    return {"item_id": item_id}

二、自定义异常类
可以定义自己的异常类，并通过 @app.exception_handler 注册

class UnicornException(Exception):
    def __init__(self, name: str):
        self.name = name

@app.exception_handler(UnicornException)
async def unicorn_exception_handler(request: Request, exc: UnicornException):
    return JSONResponse(
        status_code=418,
        content={"message": f"Oops! {exc.name} did something wrong."},
    )

三、处理请求验证错误
FastAPI 默认在请求校验失败时会抛出 RequestValidationError
可通过自定义处理逻辑统一返回结构

from fastapi.exceptions import RequestValidationError
from fastapi.responses import JSONResponse
from fastapi import status

@app.exception_handler(RequestValidationError)
async def validation_exception_handler(request: Request, exc: RequestValidationError):
    return JSONResponse(
        status_code=status.HTTP_422_UNPROCESSABLE_ENTITY,
        content={"code": 422, "msg": " 请求参数错误 ", "errors": exc.errors()},
    )

四、捕获全局未处理异常

@app.exception_handler(Exception)
async def global_exception_handler(request: Request, exc: Exception):
    return JSONResponse(
        status_code=500,
        content={"code": 500, "msg": " 服务器内部错误 ", "detail": str(exc)},
    )

五、统一响应结构的做法
项目中通常需要统一所有接口的返回格式，包括成功与失败。例如：

{
  "code": 0,
  "msg": "success",
  "data": {...}
}

可通过中间件或响应模型封装成功响应，自定义异常处理器处理失败响应。

六、使用响应模型统一成功返回

from pydantic import BaseModel

class Result(BaseModel):
    code: int = 0
    msg: str = "success"
    data: dict = {}

@app.get("/user", response_model=Result)
async def get_user():
    return {"data": {"id": 1, "name": "Alice"}}

七、总结
FastAPI 的异常处理机制灵活强大，适合构建高可用、对外友好的 API 系统。通过合理组织中间件、异常处理器与响应模型，可以实现高质量的统一接口规范。

下一节将进入数据库部分，介绍如何使用 SQLModel 操作数据库。

正文完