FastAPI自学教程（25） - 错误处理机制

1. 使用HTTPException基础

from fastapi import FastAPI, HTTPException

app = FastAPI()

@app.get("/items/{item_id}")
async def read_item(item_id: int):
    if item_id > 100:
        raise HTTPException(
            status_code=404,
            detail="Item not found",
            headers={"X-Error": "Custom header"}
        )
    return {"item_id": item_id}

• 核心异常类：HTTPException继承自Exception，可携带HTTP状态码、错误详情和自定义响应头
• 触发机制：直接抛出异常即可中断请求处理流程
• 响应特点：自动生成JSON格式错误响应，包含detail字段和自定义头信息

2. 自定义异常处理器

from fastapi.responses import JSONResponse
from fastapi import Request

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"}
    )

@app.get("/unicorns/{name}")
async def read_unicorn(name: str):
    if name == "error":
        raise UnicornException(name=name)

• 注册方式：使用@app.exception_handler装饰器绑定异常类型与处理函数
• 参数结构：处理函数接收Request对象和异常实例
• 响应控制：可自定义状态码、JSON响应体结构和日志记录逻辑

3. 覆盖默认验证错误

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

@app.exception_handler(RequestValidationError)
async def validation_exception_handler(request, exc):
    return JSONResponse(
        status_code=400,
        content={"custom_error": exc.errors(), "body": exc.body},
    )

• 默认行为：请求验证失败返回422状态码和复杂错误结构
• 改造要点：
  • 合并错误类型到400状态码
  • 简化错误信息结构（如提取关键字段）
  • 保留原始请求体用于调试

4. 依赖项异常处理

from fastapi import Depends

async def verify_token(token: str):
    if token != "secret":
        raise HTTPException(status_code=401, detail="Invalid token")

@app.get("/secure")
async def secure_endpoint(token: str = Depends(verify_token)):
    return {"status": "authorized"}

• 中断机制：依赖项抛出异常会直接终止请求处理
• 统一管理：可在全局异常处理器中统一处理依赖项抛出的错误
• 安全实践：身份验证失败推荐使用401状态码

5. 中间件扩展处理

from starlette.middleware.exceptions import ExceptionMiddleware

app.add_middleware(ExceptionMiddleware, handlers=app.exception_handlers)

• 适用场景：需要跨多个异常类型实现统一处理逻辑
• 扩展能力：
  • 记录详细的错误堆栈信息
  • 实现错误报警通知机制
  • 处理非FastAPI原生异常（如第三方库错误）

---

最佳实践总结：

1. 生产环境应配置全局异常处理器捕获所有未处理异常，避免泄露敏感信息
2. 使用Pydantic模型定义错误响应结构，保持API响应格式统一
3. 重要异常应记录请求ID、时间戳等调试信息
4. 自定义错误码体系时需兼容HTTP状态码语义