FastAPI 的 BackgroundTasks 在异常情况下不会执行

一句话总结：FastAPI 的 BackgroundTasks 在抛出异常时会被静默丢弃，而官方文档对此几乎只字未提，这导致无数开发者在生产环境中踩坑。

核心问题：异常即丢失

当你的 FastAPI 应用抛出异常时，所有通过 BackgroundTasks 添加的后台任务会被直接丢弃，不会执行。这完全违背了开发者的直觉预期。

场景	BackgroundTasks 行为	开发者预期
✅ 正常响应	任务正常执行	✅ 符合预期
❌ 抛出 HTTPException	❌ 不执行	✅ 可能符合（业务异常）
❌ 未处理异常（500错误）	❌ 不执行	❓ 通常认为仍会执行
❌ 中间件捕获异常	❌ 不执行	❌ 完全不符合预期

🔍 为什么这是个“坑”？

1. 文档的误导性

参考文档 只是简单地说“Background tasks will be run after returning a response”，没有明确说明异常情况下的特殊行为。

2. 复现代码

import uvicorn
from fastapi import FastAPI, BackgroundTasks, Request
from starlette.middleware.base import BaseHTTPMiddleware
from elasticsearch.exceptions import RequestError
import asyncio

from starlette.responses import JSONResponse

app = FastAPI()


# 测试后台任务
async def test_background_task(name: str):
    print(f"BackgroundTask 执行: {name} - {asyncio.get_event_loop().time()}")


# 中间件
class ErrorHandlerMiddleware(BaseHTTPMiddleware):
    async def dispatch(self, request: Request, call_next):
        try:
            response = await call_next(request)
            return response
        except RequestError as e:
            print("中间件捕获到 RequestError")

            # 这里添加的 BackgroundTasks 不会执行！
            if hasattr(request, 'state') and hasattr(request.state, 'background_tasks'):
                request.state.background_tasks.add_task(test_background_task, "中间件任务")

            print("中间件返回响应")
            # 使用 repr(e) 替代 str(e)，避免 RequestError 字符串转换时的 AttributeError
            return JSONResponse(
                status_code=400,
                content={"message": "Middleware handled error", "v": repr(e)},
            )
        except Exception as e:
            print(f"其他异常: {e}")
            return JSONResponse(status_code=500, content={"message": "Internal error"})


app.add_middleware(ErrorHandlerMiddleware)


# 测试路由
@app.get("/test-middleware")
async def test_middleware(background_tasks: BackgroundTasks):
    print("开始执行路由")
    background_tasks.add_task(test_background_task, "路由任务")  # ❌ 不会执行
    raise RequestError(400, "test", "www")  # 抛出异常

if __name__ == "__main__":
    # 使用导入字符串格式运行 uvicorn，以支持 reload 功能
    uvicorn.run("bg:app", host="0.0.0.0", port=8001, reload=True)