FastAPI-Users 从 2.x 升级到 3.x 的注意事项
项目地址: https://gitcode.com/gh_mirrors/fa/fastapi-users 还在为 FastAPI-Users 版本升级而头疼？本文详细解析从 2.x 升级到 3.x 的关键变化和注意事项，帮你顺利完成迁移！
升级前必读：为什么需要关注版本升级？
FastAPI-Users 3.x 版本引入了一个重要的安全性和用户体验改进：邮箱地址不再区分大小写。这个看似简单的变化，实际上对现有系统的数据一致性和用户认证流程产生了深远影响。
核心变化：邮箱大小写敏感性
2.x 版本的行为
在 2.x 版本中，邮箱地址的本地部分（@符号前的部分）是区分大小写的：
# 2.x 版本中，这些被认为是不同的用户
user1 = "king.arthur@camelot.bt"
user2 = "King.Arthur@camelot.bt"
user3 = "KING.ARTHUR@camelot.bt"
3.x 版本的行为
在 3.x 版本中，邮箱地址查询变为不区分大小写：
# 3.x 版本中，这些邮箱都会匹配到同一个用户
await user_manager.get_by_email("king.arthur@camelot.bt")
await user_manager.get_by_email("King.Arthur@camelot.bt")
await user_manager.get_by_email("KING.ARTHUR@camelot.bt")
升级前的关键检查步骤
1. 检查重复邮箱账户
在升级之前，必须检查数据库中是否存在相同邮箱但不同大小写的重复账户：
-- PostgreSQL 示例查询
SELECT lower(email) as normalized_email,
count(*) as duplicate_count,
array_agg(email) as duplicate_emails
FROM users
GROUP BY lower(email)
HAVING count(*) > 1;
-- SQLite 示例查询
SELECT lower(email), count(*), group_concat(email)
FROM users
GROUP BY lower(email)
HAVING count(*) > 1;
2. 处理重复账户的策略
如果发现重复账户，需要制定合并或删除策略：
| 策略类型 | 适用场景 | 注意事项 |
|---|---|---|
| 账户合并 | 用户拥有多个账户但实际为同一人 | 需要迁移数据、保留最新活动记录 |
| 账户删除 | 明显的测试账户或废弃账户 | 确保不会误删重要数据 |
| 联系用户 | 无法确定账户归属时 | 提供账户选择或合并选项 |
3. 数据迁移脚本示例
import asyncpg
from collections import defaultdict
async def find_and_handle_duplicate_emails():
conn = await asyncpg.connect(DATABASE_URL)
# 查找重复邮箱
duplicates = await conn.fetch('''
SELECT lower(email) as norm_email,
array_agg(id) as user_ids,
array_agg(email) as emails
FROM users
GROUP BY lower(email)
HAVING count(*) > 1
''')
for dup in duplicates:
print(f"发现重复邮箱: {dup['norm_email']}")
print(f"关联用户ID: {dup['user_ids']}")
print(f"邮箱变体: {dup['emails']}")
# 这里添加你的处理逻辑
# 例如：保留最新账户，合并数据，删除旧账户等
await conn.close()
升级步骤详解
步骤 1: 更新依赖版本
# 更新 fastapi-users
pip install --upgrade fastapi-users
# 或者明确指定版本
pip install fastapi-users>=3.0.0,<4.0.0
步骤 2: 验证依赖兼容性
检查你的其他依赖是否与 3.x 版本兼容：
pip check
步骤 3: 测试认证流程
升级后，重点测试以下场景：
- 登录功能: 使用不同大小写的邮箱进行登录测试
- 注册功能: 尝试注册与现有账户邮箱相同但大小写不同的新账户
- 密码重置: 测试密码重置功能是否正常工作
- 邮箱验证: 验证邮箱验证流程
常见问题及解决方案
问题 1: 升级后用户无法登录
症状: 用户报告登录失败，但密码正确
原因: 可能是邮箱大小写不匹配导致的查询问题
解决方案:
# 在用户管理器中添加日志记录
async def get_by_email(self, user_email: str) -> models.UP:
logger.info(f"查询邮箱: {user_email}")
user = await self.user_db.get_by_email(user_email)
if user is None:
logger.warning(f"未找到邮箱对应的用户: {user_email}")
raise exceptions.UserNotExists()
return user
问题 2: 数据库性能下降
症状: 用户查询变慢
原因: 大小写不敏感查询可能没有有效利用索引
解决方案:
-- 为邮箱字段创建函数索引（PostgreSQL）
CREATE INDEX idx_users_email_lower ON users (lower(email));
-- 或者使用表达式索引
CREATE INDEX idx_users_lower_email ON users (lower(email));
升级检查清单
在完成升级后，使用以下清单进行验证：
- 重复邮箱账户已处理完毕
- 所有用户都能正常登录（使用各种大小写组合）
- 新用户注册功能正常
- 密码重置功能正常
- 邮箱验证功能正常
- OAuth 登录功能正常
- 数据库查询性能在可接受范围内
- 错误日志中没有出现认证相关的异常
最佳实践建议
1. 邮箱规范化存储
考虑在数据库中存储规范化的邮箱格式：
from email.utils import parseaddr
def normalize_email(email: str) -> str:
"""规范化邮箱地址"""
_, email_address = parseaddr(email)
return email_address.lower().strip()
2. 添加监控和告警
设置监控来检测认证失败率的异常变化：
# 使用 Prometheus 或类似工具监控认证指标
from prometheus_client import Counter
AUTH_FAILURES = Counter('auth_failures_total', 'Total authentication failures')
AUTH_SUCCESSES = Counter('auth_successes_total', 'Total authentication successes')
async def authenticate(self, credentials):
try:
user = await self.get_by_email(credentials.username)
# ... 认证逻辑
AUTH_SUCCESSES.inc()
return user
except exceptions.UserNotExists:
AUTH_FAILURES.inc()
return None
3. 文档和沟通
确保团队所有成员了解这一变化：
- 更新内部开发文档
- 通知运维团队监控需求变化
- 如有必要，通知用户系统升级信息
总结
FastAPI-Users 从 2.x 升级到 3.x 虽然主要变化是邮箱大小写敏感性的调整，但这个变化对系统的数据完整性和用户体验有重要影响。通过本文的指导，你可以：
- 系统性地检查现有数据中的重复账户
- 安全地执行升级操作
- 全面地测试所有认证相关功能
- 持续地监控系统运行状态
记住：在升级生产环境之前，一定要在测试环境中充分验证。祝你升级顺利！
如果遇到其他升级问题，建议查阅官方文档或社区讨论。升级过程中保持谨慎，做好数据备份，确保业务连续性。
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
