FastAPI-Users 从 2.x 升级到 3.x 的注意事项

FastAPI-Users 从 2.x 升级到 3.x 的注意事项

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

前言

FastAPI-Users 是一个优秀的 FastAPI 用户认证库，在 3.x 版本中引入了一些重要的变更。本文将重点介绍从 2.x 升级到 3.x 时需要注意的关键变化，特别是关于电子邮件地址处理方式的重大变更。

电子邮件地址大小写敏感性的变化

旧版本行为（2.x）

在 2.x 版本中，电子邮件地址的本地部分（@符号前的部分）是区分大小写的。这意味着：

• user@example.com 和 User@example.com 被视为两个不同的账户
• 这种处理方式与大多数网络服务的惯例不一致
• 可能导致用户困惑，特别是当他们使用不同大小写形式登录时

新版本行为（3.x）

3.x 版本对此进行了重大改进：

1. 查询时大小写不敏感：现在从数据库查询用户时，会进行大小写不敏感的搜索
2. 存储时保留原样：用户注册时使用的电子邮件地址会原样存储（保留大小写）
3. 登录更灵活：用户可以使用任何大小写组合登录，只要电子邮件地址的字符匹配

例如：

• 用户注册时使用 King.Arthur@camelot.bt
• 登录时可以使用 king.arthur@camelot.bt
• 但数据库中存储的仍然是 King.Arthur@camelot.bt

升级前的关键检查

在升级到 3.x 版本前，必须执行以下检查：

1. 重复账户检查：检查数据库中是否存在相同电子邮件地址但大小写不同的多个账户
2. 账户合并或删除：如果发现重复账户，必须决定：
   • 保留哪个账户（通常保留最早创建的或最活跃的）
   • 合并账户数据（如需要）
   • 删除多余的账户

检查脚本示例

建议编写一个检查脚本，查找可能存在的重复电子邮件账户。基本逻辑如下：

# 伪代码示例
users = get_all_users()
email_map = {}

for user in users:
    lower_email = user.email.lower()
    if lower_email in email_map:
        print(f"发现重复邮箱: {user.email} 和 {email_map[lower_email].email}")
    else:
        email_map[lower_email] = user

升级后的影响

1. 用户体验提升：用户不再需要记住注册时使用的大小写格式
2. 安全性考虑：确保账户合并过程不会导致权限或数据问题
3. 数据库索引：可能需要调整数据库索引以优化大小写不敏感的查询

最佳实践建议

1. 升级前备份数据：任何重大升级前都应完整备份数据库
2. 分阶段升级：先在测试环境验证升级过程
3. 通知用户：如果合并了账户，应通知相关用户
4. 监控日志：升级后密切监控认证相关的错误日志

结论

FastAPI-Users 3.x 对电子邮件处理的改进更符合行业标准，能提供更好的用户体验。但升级过程需要谨慎处理潜在的重复账户问题，确保数据一致性和系统安全性。按照本文指南操作，可以顺利完成从 2.x 到 3.x 的迁移。

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