FastAPI-Users 从 8.x 到 9.x 版本迁移指南：认证架构的重大革新

FastAPI-Users 从 8.x 到 9.x 版本迁移指南：认证架构的重大革新

fastapi-users Ready-to-use and customizable users management for FastAPI 项目地址: https://gitcode.com/gh_mirrors/fa/fastapi-users

前言

FastAPI-Users 作为 FastAPI 生态中优秀的用户认证管理库，在 9.x 版本中对认证后端进行了重大架构调整。本文将深入解析这一变化的技术背景，并提供详细的迁移指导，帮助开发者顺利完成版本升级。

架构变革的核心思想

在 9.x 版本中，认证后端被拆分为两个独立但协作的组件：

1. 传输层 (Transport)：负责令牌在请求中的传递方式
2. 策略层 (Strategy)：负责令牌的生成和安全机制

这种解耦设计带来了显著的架构优势：

• 提高了代码复用性，相同传输方式可搭配不同策略
• 便于扩展新的认证策略（如数据库会话令牌）
• 各组件职责更加单一，符合单一职责原则

认证后端的迁移实践

JWT 认证迁移示例

旧版实现 (8.x)

from fastapi_users.authentication import JWTAuthentication

jwt_authentication = JWTAuthentication(
    secret=SECRET, 
    lifetime_seconds=3600, 
    tokenUrl="auth/jwt/login"
)

新版实现 (9.x)

from fastapi_users.authentication import AuthenticationBackend, BearerTransport, JWTStrategy

bearer_transport = BearerTransport(tokenUrl="auth/jwt/login")

def get_jwt_strategy() -> JWTStrategy:
    return JWTStrategy(secret=SECRET, lifetime_seconds=3600)

auth_backend = AuthenticationBackend(
    name="jwt",  # 必须显式命名
    transport=bearer_transport,
    get_strategy=get_jwt_strategy,
)

关键变化说明：

1. 分离了 Bearer 传输方式和 JWT 策略
2. 策略通过工厂函数动态获取
3. 必须为每个后端指定唯一名称

Cookie 认证迁移示例

旧版实现 (8.x)

from fastapi_users.authentication import CookieAuthentication

cookie_authentication = CookieAuthentication(
    secret=SECRET, 
    lifetime_seconds=3600
)

新版实现 (9.x)

from fastapi_users.authentication import AuthenticationBackend, CookieTransport, JWTStrategy

cookie_transport = CookieTransport(cookie_max_age=3600)

def get_jwt_strategy() -> JWTStrategy:
    return JWTStrategy(secret=SECRET, lifetime_seconds=3600)

auth_backend = AuthenticationBackend(
    name="cookie",
    transport=cookie_transport,
    get_strategy=get_jwt_strategy,
)

技术提示：注意到两种认证方式可以使用相同的 JWT 策略，这正是新架构灵活性的体现。

OAuth 路由的调整

新版要求为每个认证后端创建独立的路由器。

旧版配置

app.include_router(
    fastapi_users.get_oauth_router(google_oauth_client, "SECRET"),
    prefix="/auth/google",
    tags=["auth"],
)

新版配置

app.include_router(
    fastapi_users.get_oauth_router(
        google_oauth_client, 
        auth_backend,  # 指定关联的认证后端
        "SECRET"
    ),
    prefix="/auth/google",
    tags=["auth"],
)

API 调用变化：

• 移除了 /authorize 端点对 authentication_backend 参数的依赖
• 后端关联关系现在通过路由配置确定

迁移注意事项

1. 命名必要性：所有认证后端必须显式指定名称
2. 策略复用：相同策略可跨不同传输方式复用
3. 测试重点：迁移后应重点测试：
   • 令牌生成和验证流程
   • 传输方式的正确性
   • OAuth 流程完整性

结语

FastAPI-Users 9.x 的认证架构革新为系统带来了更好的扩展性和灵活性。虽然迁移过程需要一定的适配工作，但新的设计模式将使未来的功能扩展更加轻松。建议开发者在完成迁移后，充分测试各认证流程，确保系统安全稳定。

fastapi-users Ready-to-use and customizable users management for FastAPI 项目地址: https://gitcode.com/gh_mirrors/fa/fastapi-users