FastAPI版本升级后BackgroundTasks绑定Query报错求助

问题重现 #

旧代码在FastAPI 0.82.0可正常运行，但升级到0.109.1时触发断言错误：

AssertionError: Cannot specify FastAPI annotation for type <class 'fastapi.background.BackgroundTasks'>

旧代码片段：

# main.py
from fastapi import FastAPI
from fastapi import Query, BackgroundTasks

app = FastAPI()

@app.get("/")
def read_root(background_tasks : BackgroundTasks = Query(default=None, include_in_schema=False)):
    return {"message": "Hello, World!"}

原因分析 #

FastAPI新版本对特殊内置依赖类型（如BackgroundTasks、Request、Response等）的校验逻辑做了严格升级：

• 这些类型是框架自动注入的内置对象，不需要从查询参数、路径参数等外部来源获取
• 旧版本未严格限制这种错误绑定，新版本通过断言阻止了将Query/Path等参数装饰器应用到内置依赖类型的行为

解决方案 #

根据原代码的实际需求，选择以下两种修复方式：

1. 分离查询参数与BackgroundTasks（若原需求是通过查询参数控制后台任务） #

如果原代码的意图是通过隐藏查询参数触发后台任务，需将查询参数和BackgroundTasks参数分开声明：

from fastapi import FastAPI, Query, BackgroundTasks

app = FastAPI()

def sample_background_task():
    # 后台任务逻辑示例
    pass

@app.get("/")
def read_root(
    # 单独声明查询参数，不受内置依赖限制
    trigger_bg_task: bool = Query(default=False, include_in_schema=False),
    # 正确声明BackgroundTasks参数，框架自动注入
    background_tasks: BackgroundTasks = None
):
    if trigger_bg_task:
        background_tasks.add_task(sample_background_task)
    return {"message": "Hello, World!"}

2. 仅保留BackgroundTasks注入（若原Query参数是误用） #

如果原代码中的Query是错误写法，实际只需要注入BackgroundTasks，直接使用标准声明方式即可：

from fastapi import FastAPI, BackgroundTasks

app = FastAPI()

@app.get("/")
def read_root(background_tasks : BackgroundTasks = None):
    return {"message": "Hello, World!"}

验证说明 #

• 第一种修复方式中，trigger_bg_task是普通查询参数，可正常用Query配置属性
• 第二种修复方式符合FastAPI新版本对内置依赖的声明规范，框架会自动处理对象注入

内容的提问来源于stack exchange，提问作者Mahdee Mushfique Kamal