FastAPI中Depends()的作用解析：为何需用它而非直接调用函数

问题背景 #

在学习FastAPI依赖注入时，针对以下示例代码和错误写法，存在三个核心疑问：

• Depends()的作用是什么？
• 为何必须使用Depends()？
• 直接调用common_parameters()为何无法实现相同功能？

正确示例代码 #

from typing import Annotated

from fastapi import Depends, FastAPI

app = FastAPI()


async def common_parameters(q: str | None = None, skip: int = 0, limit: int = 100):
    return {"q": q, "skip": skip, "limit": limit}


@app.get("/items/")
async def read_items(commons: Annotated[dict, Depends(common_parameters)]):
    return commons

错误写法示例 #

@app.get("/items/")
async def read_items(commons: Annotated[dict, common_parameters()]):
    return commons

解答 #

1. Depends()的作用是什么？ #

Depends()是FastAPI依赖注入系统的核心工具，核心作用包括：

• 向FastAPI声明：当前路由参数的值需要通过调用指定的依赖函数（如common_parameters）来获取
• 触发FastAPI的依赖处理逻辑：自动解析依赖函数的参数（比如示例里的q、skip、limit这类查询参数），执行函数并将结果注入到路由函数的参数中
• 支持依赖链、请求级缓存、异步/同步兼容等高级特性，比如多个路由复用同一依赖，或者依赖本身嵌套其他依赖

2. 为何必须使用Depends()？ #

FastAPI的依赖注入是声明式设计，Depends()是给FastAPI的关键信号：

• 没有它，FastAPI只会把common_parameters当成普通类型提示，不会执行该函数，更不会自动解析它内部绑定的请求参数（如查询参数）
• Depends()还封装了异步/同步函数兼容、请求上下文传递（比如在依赖中使用Request对象）、请求级依赖缓存（同一请求中多次调用同一依赖仅执行一次）等细节，这些都是手动调用函数无法实现的

3. 为何直接调用common_parameters()无法实现相同功能？ #

错误写法里的common_parameters()是在服务启动时直接执行，而非请求到来时动态执行：

• 启动时调用会使用默认参数生成固定字典，后续所有请求都会返回这个固定值，完全不会读取请求中的实际查询参数
• 直接调用函数时，FastAPI无法解析函数内部绑定的请求参数（如q是查询参数），因为没有经过依赖注入流程，这些参数无法和请求上下文绑定
• 如果依赖函数是异步的，直接调用会返回协程对象而非实际结果，导致路由函数报错

内容的提问来源于stack exchange，提问作者Sam Archer