一、FastAPI依赖注入基础回顾
在FastAPI框架中，依赖注入（Dependency Injection）是一种强大的解耦机制。我们可以将复杂的业务逻辑拆分成多个可复用的依赖项，通过声明式的方式注入到路由处理函数中。这是实现安全认证体系的基础架构。

依赖注入的典型应用场景：

数据库连接池管理
用户身份认证
权限校验
请求参数预处理
服务层对象实例化
基础依赖声明示例：

from fastapi import Depends


async def pagination_params(
        page: int = 1,
        size: int = 20
) -> dict:
    return {"skip": (page - 1) * size, "limit": size}


@app.get("/items/")
async def list_items(params: dict = Depends(pagination_params)):
    return await ItemService.list_items(**params)

二、安全认证依赖设计原理
2.1 认证流程分解
典型的安全认证流程包含三个关键阶段：

凭证提取：从请求头、Cookie或请求体中获取令牌
令牌解析：验证令牌有效性并解码负载数据
权限校验：根据用户角色验证访问权限
2.2 分层依赖结构设计

# 第一层：提取Bearer Token
async def get_token_header(authorization: str = Header(...)) -> str:
    scheme, token = authorization.split()
    if scheme.lower() != "bearer":
        raise HTTPException(...)
    return token


# 第二层：解析JWT令牌
async def get_current_user(token: str = Depends(get_token_header)) -> User:
    payload = decode_jwt(token)
    return await UserService.get(payload["sub"])


# 第三层：校验管理员权限
async def require_admin(user: User = Depends(get_current_user)) -> User:
    if not user.is_admin:
        raise HTTPException(status_code=403)
    return user

三、组合依赖实践：管理员操作端点
3.1 完整实现示例

from fastapi import APIRouter, Depends, HTTPException, status
from pydantic import BaseModel
from jose import JWTError, jwt
from datetime import datetime, timedelta

router = APIRouter()


# 配置模型
class AuthConfig(BaseModel):
    secret_key: str = "your-secret-key"
    algorithm: str = "HS256"
    access_token_expire: int = 30  # 分钟


# JWT令牌创建函数
def create_access_token(data: dict, config: AuthConfig) -> str:
    expire = datetime.utcnow() + timedelta(minutes=config.access_token_expire)
    return jwt.encode(
        {**data, "exp": expire},
        config.secret_key,
        algorithm=config.algorithm
    )


# 用户模型
class User(BaseModel):
    username: str
    is_admin: bool = False


# 认证异常处理
credentials_exception = HTTPException(
    status_code=status.HTTP_401_UNAUTHORIZED,
    detail="无法验证凭据",
    headers={"WWW-Authenticate": "Bearer"},
)


# 组合依赖项
async def get_current_admin(
        token: str = Depends(get_token_header),
        config: AuthConfig = Depends(get_config)
) -> User:
    try:
        payload = jwt.decode(token, config.secret_key, algorithms=[config.algorithm])
        username: str = payload.get("sub")
        if username is None:
            raise credentials_exception
    except JWTError:
        raise credentials_exception

    user = await UserService.get(username)  # 假设已实现用户服务
    if not user.is_admin:
        raise HTTPException(status_code=403, detail="需要管理员权限")

    return user


# 管理员专属端点
@router.delete("/users/{username}")
async def delete_user(
        admin: User = Depends(get_current_admin),
        user_service: UserService = Depends(get_user_service)
):
    await user_service.delete_user(admin.username)
    return {"message": "用户删除成功"}

3.2 关键代码解析
令牌生成函数使用JWT标准库实现，包含过期时间处理
用户模型通过Pydantic进行数据验证
组合依赖项 get_current_admin 将认证与授权逻辑合并
路由处理函数仅关注业务逻辑，安全逻辑通过依赖注入实现
四、测试用例与验证

from fastapi.testclient import TestClient


def test_admin_operation():
    # 生成测试令牌
    admin_token = create_access_token({"sub": "admin"}, AuthConfig())
    user_token = create_access_token({"sub": "user"}, AuthConfig())

    with TestClient(app) as client:
        # 测试管理员访问
        response = client.delete(
            "/users/testuser",
            headers={"Authorization": f"Bearer {admin_token}"}
        )
        assert response.status_code == 200

        # 测试普通用户访问
        response = client.delete(
            "/users/testuser",
            headers={"Authorization": f"Bearer {user_token}"}
        )
        assert response.status_code == 403

        # 测试无效令牌
        response = client.delete(
            "/users/testuser",
            headers={"Authorization": "Bearer invalid"}
        )
        assert response.status_code == 401

课后Quiz
问题1：当需要同时验证API密钥和JWT令牌时，应该如何组织依赖项？
A) 在同一个依赖函数中处理所有验证逻辑
B) 创建两个独立依赖项并顺序注入
C) 使用类依赖项合并多个验证方法
D) 在路由装饰器中添加多个安全参数

答案：B
解析：FastAPI的依赖注入系统支持多个独立的依赖项组合使用。最佳实践是保持每个依赖项职责单一，通过Depends()顺序注入。例如：

async def route_handler(
        api_key: str = Depends(verify_api_key),
        user: User = Depends(get_current_user)
):
    ...

问题2：当某个端点需要支持多种认证方式（如JWT和OAuth2）时，如何实现？
A) 使用Union类型组合多个依赖项
B) 创建统一的认证适配器
C) 在依赖项内部处理多种认证逻辑
D) 为每个认证方式创建单独的路由

答案：B
解析：推荐创建统一的认证处理类，在内部根据请求特征选择具体的认证方式。例如：

 class AuthHandler:
     async def __call__(self, request: Request):
         if "Bearer" in request.headers.get("Authorization", ""):
             return await self._jwt_auth(request)
         elif request.cookies.get("session"):
             return await self._cookie_auth(request)
         raise HTTPException(401)

常见报错解决方案
错误1：401 Unauthorized
现象：请求头中缺少或包含无效的Authorization字段
解决方案：

检查请求头格式：Authorization: Bearer
验证令牌是否过期
确认密钥配置与签发时一致
检查令牌解码算法是否匹配
错误2：403 Forbidden
现象：认证成功但权限不足
排查步骤：

检查用户角色字段是否正确赋值
验证权限校验逻辑的条件判断
确认数据库中的用户权限状态
检查依赖项的注入顺序是否导致短路
错误3：422 Validation Error
触发场景：依赖项返回的数据类型与路由处理函数声明的参数类型不匹配
预防措施：

使用Pydantic模型严格定义返回类型
在依赖项中添加返回类型注解
保持依赖项与处理函数的参数名称一致
对复杂对象使用类型提示
通过本文的深度实践，读者可以掌握FastAPI安全认证体系的设计精髓。依赖注入机制使得安全逻辑与业务逻辑解耦，通过组合多个职责单一的依赖项，能够构建出灵活且易于维护的认证授权系统。

来源：https://www.cnblogs.com/Amd794/p/18821650