在 FastAPI 接口开发中，我们常常会遇到多个路由函数需要重复编写相同逻辑的场景——比如多个列表接口都需要分页参数校验、多个接口都需要用户权限校验、多个接口都需要创建和关闭数据库会话。如果在每个路由函数中重复编写这些通用逻辑，不仅会导致代码冗余、维护成本增加，还会出现逻辑不一致的问题，不利于后续迭代和测试。FastAPI 内置的依赖注入（Dependency Injection）系统，恰好能解决这一痛点，它通过抽取可复用的通用逻辑作为依赖项，实现“一次编写、多处调用”，同时实现业务逻辑与通用逻辑的解耦，让路由函数更专注于核心业务。本文将详细讲解依赖注入的核心概念、使用方法、实际应用场景，结合独立构思的可运行代码示例，让开发者快速掌握这一高效开发技巧。
一、依赖注入核心概念
要理解依赖注入，首先要明确两个核心术语：依赖项和注入。
依赖项：本质是可重用的组件，可以是异步函数、同步函数或类，负责提供某种通用功能或数据，比如分页参数校验、身份认证、数据库会话管理等。它是路由函数“依赖”的逻辑模块，无需在路由函数内部重复编写。
注入：FastAPI 会自动识别路由函数所依赖的组件，在路由函数执行前，自动调用依赖项并将其返回结果“注入”到路由函数中，开发者无需手动调用依赖项，只需声明依赖关系即可。
简单来说，依赖注入就像是“专人专岗”——将通用逻辑交给专门的依赖项处理，路由函数只需专注于自己的核心业务，无需关心通用逻辑的实现和调用细节。与中间件的“全局拦截、统一处理”不同，依赖注入更灵活，可按需为指定路由添加依赖，实现“按需控制”，这也是它与中间件的核心区别：中间件作用于所有请求，而依赖注入作用于声明了依赖的路由，真正实现“我说了算”。
二、依赖注入的核心优点
依赖注入系统之所以成为 FastAPI 开发的必备技巧，核心在于它能解决代码复用和耦合问题，带来三大显著优势：
- 代码复用：通用逻辑只需编写一次，可在多个路由函数中重复调用，减少代码冗余，提升开发效率；
- 逻辑解耦：通用逻辑（如参数校验、身份认证）与核心业务逻辑分离，后续修改通用逻辑时，无需改动所有关联的路由函数，降低维护成本；
- 易于测试：测试时可轻松用模拟依赖项替换真实依赖项，无需依赖真实的数据库、第三方服务等，让测试更简单、高效。
三、依赖注入的使用方法
FastAPI 中使用依赖注入非常简洁，只需遵循“创建依赖项 → 导入 Depends → 声明依赖项”三步即可，全程无需复杂配置，下面结合基础示例详细讲解每一步的操作。
第一步：导入核心模块
使用依赖注入需导入 FastAPI 提供的 Depends 类，它是连接路由函数和依赖项的关键，同时根据依赖项的功能，导入所需的其他模块（如 Query 用于参数校验）。
第二步：创建依赖项
依赖项通常是一个函数（异步或同步均可，FastAPI 会自动识别），负责实现通用逻辑并返回结果。比如分页参数校验，多个列表接口都需要 skip（跳过条数）和 limit（每页条数）两个参数，且需要校验参数的合法性，可将这一逻辑抽取为依赖项。
第三步：在路由函数中声明依赖项
在路由函数的参数中，通过 参数名 = Depends(依赖项函数) 的方式，声明该路由依赖于某个依赖项。FastAPI 会自动调用依赖项，将返回结果注入到该参数中，供路由函数使用。
基础示例：分页参数复用
from fastapi import FastAPI, Query, Depends
# 初始化FastAPI应用
app = FastAPI(debug=True)
# 1. 创建依赖项：分页参数校验与提取
# 该依赖项负责接收并校验skip和limit参数，返回处理后的参数字典
async def pagination_parameters(
skip: int = Query(0, ge=0, description="跳过的条数，默认0，不能为负数"),
limit: int = Query(10, ge=1, le=60, description="每页显示的条数，默认10，1-60之间")
):
# 可在这里添加额外的分页逻辑，比如参数修正（若limit超过60，自动设为60）
if limit > 60:
limit = 60
return {"skip": skip, "limit": limit}
# 2. 声明依赖项：新闻列表接口，依赖分页参数依赖项
@app.get("/news/list")
async def get_news_list(pagination=Depends(pagination_parameters)):
# 依赖项的返回结果已注入到pagination参数中，直接使用即可
skip = pagination["skip"]
limit = pagination["limit"]
# 核心业务逻辑：模拟根据分页参数查询新闻列表
news_list = [{"id": i, "title": f"新闻{i+1}"} for i in range(skip, skip+limit)]
return {
"code": 200,
"msg": "请求成功",
"data": {
"pagination": pagination,
"list": news_list
}
}
# 3. 声明依赖项：用户列表接口，复用同一个分页参数依赖项
@app.get("/users/list")
async def get_user_list(pagination=Depends(pagination_parameters)):
# 无需重复编写分页参数校验逻辑，直接使用依赖项注入的结果
skip = pagination["skip"]
limit = pagination["limit"]
# 核心业务逻辑：模拟根据分页参数查询用户列表
user_list = [{"id": i, "username": f"user{i+1}"} for i in range(skip, skip+limit)]
return {
"code": 200,
"msg": "请求成功",
"data": {
"pagination": pagination,
"list": user_list
}
}
# 4. 声明依赖项：商品列表接口，复用分页参数依赖项
@app.get("/goods/list")
async def get_goods_list(pagination=Depends(pagination_parameters)):
skip = pagination["skip"]
limit = pagination["limit"]
goods_list = [{"id": i, "name": f"商品{i+1}"} for i in range(skip, skip+limit)]
return {
"code": 200,
"msg": "请求成功",
"data": {
"pagination": pagination,
"list": goods_list
}
}
上述示例中，我们只编写了一次分页参数校验逻辑（依赖项 pagination_parameters），却在三个不同的列表接口中实现了复用。无论是修改分页参数的校验规则（如将 limit 的最大值改为 100），还是添加额外的分页逻辑，只需修改依赖项代码，所有关联的路由接口都会自动生效，无需逐个修改，极大地提升了维护效率。
四、依赖注入的实际应用场景
依赖注入的应用场景非常广泛，只要是多个路由需要共用的逻辑，都可以通过依赖项实现。以下结合实际开发中最常用的两个场景，提供独立构思的代码示例，进一步展示依赖注入的灵活性和实用性。
场景1：用户身份认证与权限校验
很多接口需要验证用户身份（如登录状态），部分接口还需要校验用户权限（如管理员才能访问）。将身份认证和权限校验逻辑抽取为依赖项，可实现指定接口的统一校验，无需在每个接口中重复编写校验代码。
from fastapi import FastAPI, Depends, HTTPException, Query
from fastapi.responses import JSONResponse
app = FastAPI()
# 模拟用户数据（实际开发中从数据库或Redis获取）
users = [
{"user_id": 1, "username": "admin", "token": "admin_token_123", "role": "admin"},
{"user_id": 2, "username": "test", "token": "test_token_456", "role": "normal"}
]
# 依赖项1：身份认证（校验Token有效性）
async def auth_dependency(token: str = Query(None, description="用户登录Token")):
if not token:
# Token未携带，返回401错误
raise HTTPException(status_code=401, detail="身份认证失败，请携带有效Token")
# 校验Token是否存在
user = next((u for u in users if u["token"] == token), None)
if not user:
raise HTTPException(status_code=401, detail="Token无效或已过期，请重新登录")
# 返回当前登录用户信息，供后续使用
return user
# 依赖项2：权限校验（仅管理员可访问）
async def admin_permission_dependency(user=Depends(auth_dependency)):
# 依赖项可以嵌套依赖，此处依赖auth_dependency获取用户信息
if user["role"] != "admin":
raise HTTPException(status_code=403, detail="权限不足，仅管理员可访问")
# 权限校验通过，返回用户信息
return user
# 公开接口：无需依赖（登录接口）
@app.get("/login")
async def login(username: str = Query(...), password: str = Query(...)):
# 模拟登录逻辑（省略密码校验）
user = next((u for u in users if u["username"] == username), None)
if not user:
return JSONResponse(status_code=400, content={"code": 400, "msg": "用户不存在"})
return {
"code": 200,
"msg": "登录成功",
"data": {"token": user["token"], "username": user["username"]}
}
# 需身份认证的接口（普通用户和管理员均可访问）
@app.get("/user/info")
async def get_user_info(current_user=Depends(auth_dependency)):
# 依赖项auth_dependency已注入当前登录用户信息
return {
"code": 200,
"msg": "请求成功",
"data": {
"user_id": current_user["user_id"],
"username": current_user["username"],
"role": current_user["role"]
}
}
# 需管理员权限的接口（仅管理员可访问）
@app.get("/admin/user/manage")
async def manage_user(current_admin=Depends(admin_permission_dependency)):
# 依赖项admin_permission_dependency嵌套了auth_dependency，自动完成身份和权限双重校验
return {
"code": 200,
"msg": "管理员权限验证通过",
"data": {"admin": current_admin["username"], "action": "用户管理"}
}
该示例中，我们创建了两个依赖项：auth_dependency 负责身份认证admin_permission_dependency 负责管理员权限校验，且后者嵌套了前者，实现“先认证、后授权”的逻辑。不同接口可根据需求选择不同的依赖项：普通接口只需身份认证，管理员接口需双重校验，无需重复编写校验逻辑，同时实现了认证、授权逻辑与业务逻辑的解耦。
场景2：数据库会话管理
后端接口通常需要与数据库交互，而数据库会话的创建、使用、关闭是通用逻辑。将数据库会话管理抽取为依赖项，可确保每个需要操作数据库的接口都能使用统一的会话，同时自动处理会话的创建和关闭，避免资源泄露。
from fastapi import FastAPI, Depends
from pydantic import BaseModel
from typing import Optional
app = FastAPI()
# 模拟数据库会话（实际开发中使用SQLAlchemy等ORM框架）
class DatabaseSession:
def __init__(self):
# 模拟创建数据库连接
self.connection = "模拟数据库连接"
print("数据库会话创建")
def query(self, sql: str):
# 模拟数据库查询操作
return f"执行查询：{sql}，连接：{self.connection}"
def close(self):
# 模拟关闭数据库连接
print("数据库会话关闭")
# 依赖项：数据库会话管理
async def db_session_dependency():
# 创建数据库会话
session = DatabaseSession()
try:
# 将会话注入到路由函数中
yield session
finally:
# 路由函数执行完成后，自动关闭会话（无论是否出现异常）
session.close()
# 数据模型（模拟请求体和响应体）
class User(BaseModel):
id: Optional[int] = None
username: str
age: int
# 接口1：查询用户（依赖数据库会话）
@app.get("/db/user/{user_id}")
async def query_user(user_id: int, db=Depends(db_session_dependency)):
# 依赖项注入数据库会话，直接使用会话执行查询
result = db.query(f"SELECT * FROM users WHERE id = {user_id}")
return {
"code": 200,
"msg": "查询成功",
"data": {"query_result": result}
}
# 接口2：新增用户（依赖数据库会话）
@app.post("/db/user")
async def add_user(user: User, db=Depends(db_session_dependency)):
result = db.query(f"INSERT INTO users (username, age) VALUES ('{user.username}', {user.age})")
return {
"code": 200,
"msg": "新增成功",
"data": {"query_result": result}
}
该示例中，依赖项 db_session_dependency 使用 yield 关键字，实现了“创建会话 → 注入会话 → 关闭会话”的自动流程。路由函数执行时，会获取依赖项返回的数据库会话；路由函数执行完成后（无论是否出现异常），finally 块中的代码会自动执行，关闭数据库会话，避免资源泄露。所有需要操作数据库的接口，只需声明依赖该依赖项，即可获得统一的会话管理，无需重复编写会话的创建和关闭逻辑。
五、依赖注入与中间件的核心区别
很多开发者会混淆依赖注入和中间件，两者都能实现通用逻辑的复用，但适用场景和作用范围有明显区别，核心差异如下：
- 作用范围不同：中间件作用于所有 HTTP 请求，无论路由是否需要，都会执行中间件逻辑；依赖注入作用于声明了依赖的路由，未声明依赖的路由不会执行依赖项逻辑，实现“按需使用”。
- 控制粒度不同：中间件是“全局控制”，无法针对单个路由灵活调整；依赖注入是“精细控制”，可根据路由需求，选择不同的依赖项，甚至嵌套依赖，灵活性更高。
- 使用场景不同：中间件适合全局统一处理的逻辑（如全局日志、跨域处理）；依赖注入适合多个路由共用、但非所有路由都需要的逻辑（如分页、身份认证、数据库会话）。
简单总结：中间件管“所有人”，依赖注入管“我指定的人”，两者结合使用，可实现更高效、更灵活的通用逻辑管理。
总结
FastAPI 的依赖注入系统，是实现代码复用、逻辑解耦的核心工具，其核心价值在于将通用逻辑抽取为可重用的依赖项，按需注入到路由函数中，减少代码冗余，提升开发和维护效率。结合本文的讲解和示例，我们可以明确以下核心要点：
- 核心流程：创建依赖项 → 导入 Depends → 路由函数声明依赖，FastAPI 自动完成注入；
- 核心优势：代码复用、逻辑解耦、易于测试，解决多路由通用逻辑重复编写的痛点；
- 实际应用：可用于分页参数校验、身份认证、权限校验、数据库会话管理等多种场景；
- 与中间件区别：依赖注入是“按需控制”，中间件是“全局控制”，两者结合可覆盖更多通用逻辑场景。
在实际开发中，合理使用依赖注入，能让路由函数更简洁、专注于核心业务，同时让通用逻辑的维护更高效，尤其在中大型项目中，能显著提升代码的可维护性和扩展性，是 FastAPI 开发中不可或缺的技巧。
