FastAPI 依赖注入的三种用法
FastAPI 依赖注入的三种用法
FastAPI 的依赖注入(Dependency Injection)把重复逻辑从路由函数里抽出来:参数校验、身份校验、数据库连接的获取与释放,都可以写成一个"依赖项",由框架在调用路由前自动执行并注入结果。核心只有一个函数 Depends。下面按由浅入深给出三种常见用法,示例基于 FastAPI 0.100+ 与 Python 3.10+,后文沿用前文定义的函数。
安装:
pip install fastapi uvicorn
一、函数依赖项:抽取公共参数与校验
最常见的用法,是把一组查询参数或请求头校验放进普通函数,路由通过 Depends 声明需要它。
from fastapi import FastAPI, Depends, Header, HTTPException
app = FastAPI()
def verify_token(x_token: str = Header(...)):
if x_token != "expected-token":
raise HTTPException(status_code=400, detail="X-Token header invalid")
def common_params(q: str | None = None, skip: int = 0, limit: int = 100):
return {"q": q, "skip": skip, "limit": limit}
@app.get("/items/")
def read_items(params: dict = Depends(common_params),
_=Depends(verify_token)):
return params
Depends(common_params) 会先调用 common_params,再把返回值赋给 params。Header(...) 中的省略号表示必填,请求头缺失时框架自动返回 422。校验失败则抛出 HTTPException,直接中断请求。这样路由只关心业务,不再重复解析参数。
二、类作为依赖项:状态与参数聚在一起
当一组参数逻辑上属于同一个对象时,用类来写更清晰。FastAPI 会像调用函数一样"调用"这个类。
class Pagination:
def __init__(self, skip: int = 0, limit: int = 100):
if limit > 100:
raise HTTPException(status_code=400, detail="limit too large")
self.skip = skip
self.limit = limit
@app.get("/users/")
def read_users(page: Pagination = Depends(Pagination)):
return {"skip": page.skip, "limit": page.limit}
这里要写 Depends(Pagination) 而不是 Depends(),编辑器才能正确推断 page 的类型并给出补全。类里同样可以抛异常,校验集中在构造阶段完成。
三、子依赖与全局依赖:把校验挂到路由之外
依赖项本身还能依赖别的依赖项,形成嵌套。更实用的是把通用校验一次性挂到应用或路由组上,不必在每个路由参数里重复声明。
from fastapi import APIRouter
def get_db():
db = {"connected": True}
try:
yield db
finally:
db["connected"] = False
def get_count(db: dict = Depends(get_db)):
return len(db)
app = FastAPI(dependencies=[Depends(verify_token)])
router = APIRouter(prefix="/v1", dependencies=[Depends(verify_token)])
@router.get("/count")
def count(n: int = Depends(get_count)):
return {"n": n}
app.include_router(router)
get_count 依赖 get_db,框架会自底向上依次解析。带 yield 的依赖项会在响应构造完成后执行 finally 块,适合释放连接等收尾工作。全局依赖和路由组依赖的返回值默认不注入路由函数,只承担校验或准备职责。
同一请求内,相同的依赖项默认只执行一次(use_cache=True),重复声明不会重复计算;若确实需要多次执行,可传 Depends(fn, use_cache=False)。
小结
三种用法对应三种粒度:函数依赖抽取公共参数,类依赖聚合一组相关参数,子依赖加全局依赖把校验统一挂到路由之外。它们共用同一个 Depends,学会一种,其余只是组织方式不同。把重复逻辑收进依赖项,路由函数会更短,校验规则只留一处,改动时也不容易漏。

浙公网安备 33010602011771号