后台任务

哪些工作可以稍后处理

例如用户提交一个小操作后，需要追加一条本地记录，但不必等记录完成才收到响应。BackgroundTasks 可以登记响应发送后的工作。官方后台任务说明

完整示例：响应后写学习记录

from fastapi import BackgroundTasks, FastAPI
from pydantic import BaseModel, Field

app = FastAPI()


class NoteInput(BaseModel):
    text: str = Field(min_length=1, max_length=500)


def record_note(text: str):
    with open("learning.log", "a", encoding="utf-8") as file:
        file.write(text + "\n")


@app.post("/notes", status_code=202)
def add_note(data: NoteInput, background_tasks: BackgroundTasks):
    background_tasks.add_task(record_note, data.text)
    return {"message": "记录请求已接收"}

这里传的是 record_note 函数本身和参数，而不是调用结果。客户端拿到 202 表示请求被接受，不表示后台工作已经完成。

它的边界在哪里

后台任务仍在应用进程中执行；进程异常退出可能导致工作未完成。它不会自动提供持久任务队列、跨服务器分发、失败重试或任务状态查询。

适合轻量附加工作。长时间计算、必须可靠完成的任务或大量任务，通常需要专门队列和工作进程，并设计任务编号、状态、重试和幂等处理。

后台函数不要依赖已经结束的请求资源。使用 Tortoise 时，在应用连接池有效的范围内查询；需要事务时由后台函数自己开启，不要传入已结束请求的事务连接。独立任务工作进程还需要初始化并关闭自己的 ORM 资源。

本章练习

在 /docs 中提交一条记录，检查工作目录中的 learning.log。再解释为何“返回成功后后台任务失败”无法通过修改已发送响应来补救。

过关标准：能区分异步接口、后台任务和独立任务队列。