starlette 的 backgroundtasks 允许你在 http 响应返回给客户端后,在服务器端异步执行额外的逻辑。具体做法是在路由函数中实例化 backgroundtasks 对象,通过其 .add_task() 方法注册需要后台运行的协程或函数,并将该对象作为依赖注入(dependency injection)传递给视图函数。这样 starlette 会在发送完响应体之后自动调度这些任务,而不会阻塞主请求流程。

如何定义并注册后台任务
要使用后台任务,你需要从 starlette.background 模块导入 BackgroundTasks 类。在 FastAPI 或纯 Starlette 应用中,通常将其声明为路由函数的参数,框架会自动处理其实例化和生命周期管理。你可以通过调用 tasks.add_task(func, *args, **kwargs) 来添加任务,其中 func 是目标函数,后面的参数将传递给该函数。如果添加的任务抛出异常,默认情况下会被静默忽略,除非配置了错误回调。

from starlette.applications import Starlette
from starlette.responses import JSONResponse
from starlette.routing import Route
from starlette.background import BackgroundTasks
import asyncio
async def send_email(to: str):
# 模拟耗时操作
await asyncio.sleep(1)
print(f"Email sent to {to}")
async def process_data(request):
tasks = BackgroundTasks()
tasks.add_task(send_email, "user@example.com")
return JSONResponse(
content={"status": "processing"},
background=tasks
)
app = Starlette(routes=[Route("/process", process_data)])
后台任务的执行时机与并发控制
后台任务并非在请求处理的中间阶段执行,而是在响应完全发送给客户端之后才触发。这意味着它们不能用于修改正在发送的响应内容,也不能直接访问请求上下文中的某些临时资源。此外,多个后台任务是按添加顺序依次执行的,但每个任务内部如果是协程,则可以在任务内实现并发。如果需要并行执行多个独立任务,可以在单个任务中使用 asyncio.gather 进行编排,或者确保每个被添加的任务本身具备并发处理能力。
Starlette 1.5.1 是轻量级 Python ASGI 框架与工具集,提供路由、请求响应、中间件、WebSocket 和后台任务等组件,适合构建异步 Web 服务。本下载为官方 PyPI 通用 wheel 包,可使用 pip 安装,并由包管理器处理依赖;运行应用时还需配置 ASGI 服务器。

from starlette.applications import Starlette
from starlette.responses import JSONResponse
from starlette.routing import Route
from starlette.background import BackgroundTasks
import asyncio
async def task_a():
await asyncio.sleep(0.5)
print("Task A done")
async def task_b():
await asyncio.sleep(0.5)
print("Task B done")
async def handle_request(request):
tasks = BackgroundTasks()
tasks.add_task(task_a)
tasks.add_task(task_b)
return JSONResponse(
content={"message": "Requests received"},
background=tasks
)
app = Starlette(routes=[Route("/multi", handle_request)])
当后台任务抛出未捕获异常时会发生什么
如果在后台任务中发生了未被 try-except 块捕获的异常,Starlette 默认会记录该异常日志,但不会向客户端返回任何错误信息,也不会中断当前请求的正常完成流程。这是因为后台任务的设计初衷就是“尽力而为”(fire-and-forget),不应影响主业务逻辑的成功与否。开发者应确保所有后台任务都包含适当的错误处理机制,例如打印堆栈跟踪、发送告警通知或将错误写入数据库,以便后续排查问题。










