在FastAPI后端开发里依赖注入是最主要、也最容易被低估的能力之一。很多开发者习惯在每个路由函数里重复写鉴权、打日志、开数据库连接、解密参数。导致接口越来越胖，改动一处需要遍历多处，单元测试几乎无从下手。怎么说呢，FastAPI的Depends机制正是为了解决这些横切关注点。把它们从业务逻辑里剥离出来。

一、依赖注入基础：从函数依赖开始

什么是依赖注入

先看一种常见的写法：每个接口都自己从request里抠分页参数、自己校验Token，业务代码被挤到函数末尾。

@app.get
async def list_users:
page = int)
page_size = int)
token = request.headers.get.replace
if token not in VALID_TOKENS:
raise HTTPException
# 业务逻辑从这里才开始…，

问题在于的观点是。分页和鉴权与列出使用者毫无关系，却在每个路由里复制粘贴。依赖注入的改法是把解析分页和当前使用者各自写成独立函数，路由参数里用Depends声明需求即可。

@app.get
async def list_users(
pagination: Pagination = Depends,user: UserInfo = Depends,):
# pagination 和 user 已经就绪。直接写业务
...

FastAPI看到Depends时会先调用get_pagination并把返回值赋给pagination再进入路由函数体。路由函数不再碰Request的原始字段，签名本身也变成了文档：一眼能看出该接口需要分页信息和登录使用者。不过，

至于基础函数依赖。分页与请求ID

任何可调用对象都可以当依赖，最常用的是普通函数。下面这个get_pagination把分页规则集中在一处：page默认1且不小于1，page_size默认10、范围1～100，并顺带算出SQL常用的offset.

def get_pagination(
至于page。int = Query,page_size: int = Query,) -> Pagination:
return Pagination(
page=page,page_size=page_size,offset= * page_size,)

痛点嵌入： 如果没有依赖注入，这段分页校验必须在每个路由里手动写；一旦业务要求改动，所有地方都要同步修改，极易漏掉。

注意： 依赖函数参数上的Query不是路由函数的参数，却会被FastAPI一样解析。说白了谁声明Depends,谁就自动拥有 ?page=&page_size= 两个查询参数，而且 Swagger 会展示来无需额外配置。

路由侧只需一行声明：

@app.get
async def demo_basic_dep(
pagination: Pagination = Depends,request_id: str = Depends,):
return {"pagination": pagination.model_dump。"request_id": request_id}

Pain point: 在没有统一 X-Request-ID 处理时每次排查故障只能靠日志时间戳，对齐困难；使用下面的依赖后即使前端不传，也会自动生成 UUID，实现全链路追踪。

P.S. get_request_id 示例实现略去，仅展示其作用。

二、类依赖与子依赖

说到类依赖，可配置的限流策略

有时依赖本身需要构造参数——比如 A 接口 30 秒内最多 3 次B 接口 60 秒内最多 100 次。 把限流写成一个类，实现 __call__。实例即可当作依赖使用：

class RateLimiter:
def __init__:
self.max_calls = max_calls
self.window_seconds = window_seconds
self._calls: list =
def __call__ -> None:
now = time.time
# 清掉滑动窗口外的旧记录
self._calls = if="" len="">= self.max_calls:
raise HTTPException
self._calls.append

Pain point： 如果用装饰器实现限流，需要在每个视图上显式写装饰器且管理全局状态；类依赖让限流策略可以像普通对象一样配置并复用。

Create two configured instances：

rate_limit_strict = RateLimiter
rate_limit_loose = RateLimiter

The router simply mounts dependency:

@app.get
async def demo_class_dep):
return {"message": "限流通过"}

The underscore placeholder signals that we only care about side‑effect。not return value.

再看子依赖，鉴权链如何层层拼装

A typical auntication flow is built as a chain of dependencies. FastAPI will resolve m top‑down and cache results within a single request.

bearer_scheme = HTTPBearer
def get_token(
credentials: HTTPAuthorizationCredentials | None = Depends,) -> str:
if credentials is None or credentials.scheme.lower!= "bearer":
raise HTTPException
return credentials.credentials
def verify_token) -> int:
user_id = _TOKENS.get
if user_id is None:
raise HTTPException
return user_id
def get_current_user) -> UserInfo:
row = _DB.get
if row is None:
raise HTTPException
return UserInfo
def require_admin) -> UserInfo:
if user.role!= "admin":
raise HTTPException
return user

Pain point： 在 Flask 中往往把所有检查塞进同一个装饰器或全局变量。一旦需求变化，必须修改所有视图；而子依赖让每一步职责单一，可独立替换或复用。

A route that only needs a normal logged‑in user：

@app.get
async def demo_sub_dep):
return user

三、全局依赖与方法局部依赖

The granularity of dependency registration determines its scope:

• 全局依赖：a list passed to Main FastAPI;applies to every endpoint.
• a router’s dependencies= ;affects only routes inside that router.
• a route’s dependencies= ;only this endpoint.
• If you need result inside handler,declare it as a parameter ) instead of using side‑effect form.

全局计时副作用示例：

async def global_request_timer -> None:
request.state.start_time = time.perf_counter
app = FastAPI])

Router‑level 日志 + 鉴权示例：

secure_router = APIRouter(
prefix="/secure",dependencies=,)
@secure_router.get
async def secure_profile):
return user
@secure_router.get
async def admin_stats):
return {"admin": admin.username,"user_count": len}
app.include_router

四、依赖缓存与异步依赖

同一请求内只算一次

If a dependency is declared multiple times within one request,FastAPI executes it **once** and reuses result.

_call_counter={"expensive_sync":0}
def expensive_sync_service -> dict:
_call_counter += 1
return {"engine":"sync","calls_in_request":_call_counter}
@app.get
async def demo_cache(
a: dict = Depends,b: dict = Depends,c: dict = Depends,):
return {"cached_twice":a,"cached_again":b,"no_cache":c}

The first two parameters share same cached result . The third forces re‑execution . This behavior eliminates redundant DB lookups or token checks.

异步依赖 & 带清理的 yield

• An async function works out‑of‑‑box:

async def expensive_async_service -> dict:
await asyncio.sleep
return {"engine":"async"}

• A database session often uses yield

@contextmanager
def get_db_session:
session={"data":_DB}
从try来看。yield session
finally:
session.clear
@asynccontextmanager
async def get_async_db_session:
session={"data":_DB}
try的观点是，await asyncio.sleep # 模拟获取连接池连接
yield session
finally:
session.clear

五、实战：四个高频场景组合演示

接口鉴权

The chain from previous “子依赖” section becomes canonical auntication solution. Normal endpoints use user:UserInfo=Depends,admin endpoints use admin:UserInfo=Depends. Swagger automatically adds an “Authorization” header field for all routes that depend on se functions.

请求日志

async def log_request(
request: Request,request_id: str = Depends,) -> None:
_REQUEST_LOGS.append({
"request_id": request_id,"method": request.method,"path": request.url.path,"client": request.client.host if request.client else "unknown","at": datetime.now.isoformat,})

This dependency can be attached globally or per‑router. Because it lives in a dependency tree rar than inline code,developers never forget to add logging statements when y create new routes – a common source of operational blind spots in Flask projects.

统一请求体解密

If front‑end encrypts sensitive fields,each view would orwise need its own decryption logic. Wrap it into a dependency:

def _decode_encrypted_note->str|None:
if value is None:return None
try的观点是，return base64.b64decode).decode
except Exception as exc:
raise HTTPException from exc
def decrypt_order_body -> DecryptedOrderCreate:
return DecryptedOrderCreate(
product=body.product,amount=body.amount,note=_decode_encrypted_note,)
@app.post
async def demo_decrypt_order):
return order

• Pain point avoided: 忘记对某条敏感字段解密导致数据泄露或存储错误。
• The route receives a clean model without ever seeing encrypted field name.

数据库会话 + 仓储子依赖

def get_user_repo):
# 假设 session 是一个简易字典型仓库
return session
@app.get
async def demo_db_session(
repo=Depends,pagination: Pagination = Depends,):
users=list)
start,p_end=pagination.offset,pagination.offset+pagination.page_size
return {"total":len。"items":users}

This three‑layer design guarantees that connection lifetimes are managed by dependencies alone—no risk of forgetting session.close as often happens with manual Flask patterns.

六、对比 Flask 装饰器：为什么 FastAPI 更优雅

在 Flask 中通常这样实现登录检查：

" language -python ">
def loginrequired:
@wraps
def decorated:
token=request.headers .get
if not verify:
ret urn jsonify,401
g .currentuser=get_user
ret urn f
ret urn decorated 

@app.route @login_required def profile: ret urn jsonify

li>Pain points: ul> li>User info hidden in global `g` – IDE/typing cannot see it. li>Decorator order matters;说起来，stacking `@login_required` & `@admin_required` often leads to subtle bugs. li>Parameters like pagination/header never appear in function signature → OpenAPI missing. li>Testing requires full app context & real tokens. ul> li> FastAPI 的等价写法： python @app .get async de f profile(user :UserInfo = Dep ends) : ret urn us er
li>优势: ul> li>Signature itself declares type & required dependency → auto docs & static checks. li>Dependency tree replaces fragile decorator stack. li>`app.dependency_overrides` enables effortless unit testing without real tokens. li>Same-request caching avoids duplicate DB/Token lookups. ul> The comparison JSON endpoint summarizes se differences for quick reference. json { "Flask":"decorator + g + manual doc"。"FastAPI":"Depends + type hints + auto doc" }

七、

li>

主要理念 : 把「拿到对象」这件事抽成独立可复用的 **dependency**，而把「业务规则」留给路由函数本身。这样可以做到的观点是，ul> li>函数级别 : 分页、Header解析等无状态工具直接写成普通函数。li>类级别 : 带构造参数的策略封装为可实例化对象。li>子依赖链 : Token 校验 → 使用者加载 → 权限判断。各环节职责单一，可自由组合。li>全局/Router 级挂载 : 横切关注点一次声明，全站生效或按模块划分。li>默认缓存 : 同一次请求内部不会重复执行昂贵操作。li>异步 & yield : 完美支持异步 IO 与资源释放。ul> Li>

Pain point 回顾 : 当你仍然在每个视图里手动抄代码时你会面对： ul> Li>

• 重复代码导致维护成本指数级增长
• 难以保证所有入口都有统一日志或鉴权
• OpenAPI 文档不完整 → 前端调试困难
• 单元测试需要构造完整 Request 上下文

FastAPI 的 Depends 正好解决了以上全部痛点，让代码更干净、更安全、更易测。

Li>

---

---