fastapi的BackgroundTasks有哪些典型常用的用法？

在 FastAPI 中，BackgroundTasks 用于在返回响应后异步执行一些后台任务，避免阻塞用户等待耗时操作完成。以下是几个典型常用法和具体例子：

1. 发送通知（邮件/消息）

用户操作后需要发送通知通知，但不需要等待通知发送完成再返回结果。

python 复制代码

from fastapi import FastAPI, BackgroundTasks
import smtplib
from email.message import EmailMessage

app = FastAPI()

def send_notification_email(email: str, content: str):
    """发送邮件通知（实际项目中可替换为异步邮件库）"""
    msg = EmailMessage()
    msg.set_content(content)
    msg["Subject"] = "操作成功通知"
    msg["From"] = "system@example.com"
    msg["To"] = email
    
    # 模拟邮件发送（实际中使用SMTP服务器）
    with smtplib.SMTP("smtp.example.com", 587) as server:
        server.send_message(msg)

@app.post("/order")
async def create_order(
    user_email: str,
    background_tasks: BackgroundTasks
):
    # 核心业务：创建订单（快速完成）
    order_id = "ORD123456"
    
    # 添加后台任务：发送通知邮件
    background_tasks.add_task(
        send_notification_email,
        user_email,
        f"您的订单 {order_id} 已创建成功！"
    )
    
    return {"message": "订单创建成功", "order_id": order_id}

2. 日志记录与数据分析

用户行为日志不需要实时写入，可以后台异步处理，避免影响接口响应速度。

python 复制代码

from fastapi import FastAPI, BackgroundTasks
import json
from datetime import datetime

app = FastAPI()

def log_user_behavior(user_id: str, action: str, details: dict):
    """写入用户行为日志到文件或数据库"""
    log_data = {
        "user_id": user_id,
        "action": action,
        "details": details,
        "timestamp": datetime.now().isoformat()
    }
    with open("user_behavior.log", "a") as f:
        f.write(json.dumps(log_data) + "\n")

@app.post("/user/login")
async def user_login(
    user_id: str,
    background_tasks: BackgroundTasks
):
    # 核心业务：验证登录（快速完成）
    login_success = True  # 实际中为验证逻辑
    
    # 添加后台任务：记录登录日志
    background_tasks.add_task(
        log_user_behavior,
        user_id,
        "login",
        {"success": login_success, "device": "mobile"}
    )
    
    return {"message": "登录成功" if login_success else "登录失败"}

3. 异步生成大型文件/报表

用户请求生成大型报表时，先返回"处理中"的响应，后台异步生成文件后再通知用户。

python 复制代码

from fastapi import FastAPI, BackgroundTasks
import pandas as pd
import os

app = FastAPI()

def generate_monthly_report(month: str, email: str):
    """生成月度报表并保存（耗时操作）"""
    # 模拟生成大量数据
    data = pd.DataFrame({
        "date": [f"{month}-{i}" for i in range(1, 29)],
        "sales": [i * 1000 for i in range(1, 29)]
    })
    # 保存报表
    file_path = f"reports/{month}_sales_report.xlsx"
    data.to_excel(file_path, index=False)
    
    # 生成后可进一步添加"发送下载链接"的任务
    send_report_email(email, file_path)  # 假设已实现该函数

@app.post("/report/generate")
async def generate_report(
    month: str,
    user_email: str,
    background_tasks: BackgroundTasks
):
    # 核心业务：参数校验（快速完成）
    if not month.match(r"\d{4}-\d{2}"):
        return {"error": "日期格式错误，应为YYYY-MM"}
    
    # 添加后台任务：生成报表
    background_tasks.add_task(
        generate_monthly_report,
        month,
        user_email
    )
    
    return {"message": "报表生成中，完成后将发送通知至您的邮箱"}

4. 清理临时资源

接口处理中生成的临时文件、缓存等，可在返回响应后由后台任务清理。

python 复制代码

from fastapi import FastAPI, BackgroundTasks
import shutil
import tempfile

app = FastAPI()

def clean_temp_files(temp_dir: str):
    """删除临时目录及文件"""
    if os.path.exists(temp_dir):
        shutil.rmtree(temp_dir)

@app.post("/file/process")
async def process_file(
    file_content: str,
    background_tasks: BackgroundTasks
):
    # 创建临时目录并处理文件（核心业务）
    temp_dir = tempfile.mkdtemp()
    temp_file = os.path.join(temp_dir, "temp.txt")
    with open(temp_file, "w") as f:
        f.write(file_content)
    
    # 模拟文件处理（如格式转换、解析等）
    processed_result = f"处理结果：{len(file_content)} 字符"
    
    # 添加后台任务：清理临时文件
    background_tasks.add_task(clean_temp_files, temp_dir)
    
    return {"result": processed_result}

关键特点总结：

任务在返回响应后执行，不阻塞用户请求
适合处理非紧急、耗时但不影响主流程的操作
注意：如果服务器重启，未完成的后台任务会丢失（需结合任务队列如 Celery 处理更可靠的场景）