Python Web框架：FastAPI依赖注入系统

理解 FastAPI 依赖注入与 Depends 工作机制

依赖注入（Dependency Injection, DI）的核心在于解耦组件创建与业务逻辑，避免在路由函数中硬编码数据库连接、认证校验等重复代码。FastAPI 通过 Depends 类将依赖声明为函数参数，框架在接收到 HTTP 请求时，会基于类型提示自动构建依赖图。当路由处理函数被调用前，FastAPI 会递归解析所有 Depends 标记的依赖函数，按拓扑顺序执行并收集返回值，最终将结果注入到路由函数的对应参数中。例如，定义 def get_db(): return Session() 后，在路由中声明 db: Session = Depends(get_db)，FastAPI 会在请求到达时自动调用 get_db 并将实例传入。整个过程由 Starlette 底层的事件循环与 Pydantic 类型校验协同完成，开发者无需手动实例化或传递上下文，大幅提升了代码的可测试性与可维护性。

定义可复用依赖：参数、认证与公共逻辑

编写可复用依赖函数时，应遵循单一职责原则，将认证、分页或参数校验等横切关注点抽离为独立函数。FastAPI 支持带参数的依赖声明，例如 def paginate(skip: int = Query(0), limit: int = Query(10)): return {"skip": skip, "limit": limit}，在路由中通过 Depends(paginate) 即可复用。对于认证逻辑，可结合 Header 或 Cookie 提取令牌，验证通过后返回用户信息对象，若失败则直接抛出 HTTPException 中断请求链。公共校验依赖同样适用此模式，如检查请求体中的业务状态码或权限标识。通过将这些逻辑封装为依赖，多个路由可共享同一套处理流程，不仅减少了样板代码，还使得单元测试能够针对依赖函数独立编写，无需启动完整 Web 服务。实际项目中，建议将依赖函数集中存放于 dependencies.py 模块，保持路由文件的清晰与专注。

组合嵌套依赖与管理数据库等资源

依赖系统支持嵌套声明，即一个依赖函数内部可再次使用 Depends 引用其他依赖，FastAPI 会按深度优先策略构建依赖树并确定执行顺序。例如，权限校验依赖可嵌套用户认证依赖，框架会先执行认证获取用户身份，再基于该身份进行权限判定。对于数据库会话、文件句柄等需要显式释放的资源，FastAPI 提供了基于 yield 的上下文管理器语法。定义 def get_db(): db = SessionLocal(); try: yield db; finally: db.close() 后，FastAPI 会在请求处理前执行 yield 之前的代码注入资源，在路由函数执行完毕或发生异常后，自动执行 finally 块完成清理。这种机制确保了资源生命周期与请求周期严格对齐，避免了连接泄漏。开发者需注意，yield 依赖必须同步或异步匹配，且不可在 yield 后执行耗时操作，以免阻塞事件循环。

验证依赖执行并排查常见问题

验证依赖注入的正确性可通过 FastAPI 内置的 TestClient 结合 dependency_overrides 实现。在测试环境中，将 app.dependency_overrides[real_dep] = mock_dep 替换为返回固定值的模拟函数，即可隔离外部服务并验证路由逻辑。FastAPI 默认对同一请求内的相同依赖进行缓存，避免重复执行，若需强制刷新可使用 use_cache=False。类型标注是依赖解析的关键，缺失或错误的类型提示会导致注入失败。异步依赖需使用 async def 声明，框架会自动适配事件循环。常见误区包括：将多个无关逻辑塞入单一依赖导致职责过重；在 yield 依赖中遗漏异常处理造成资源未释放；以及误用全局变量替代依赖注入破坏测试隔离。通过合理拆分依赖、严格遵循生命周期规范，可充分发挥 FastAPI 依赖系统的工程价值。