FastAPI-Users 从 0.8.x 升级到 1.x.x 迁移指南-优快云博客

本文链接：https://blog.youkuaiyun.com/gitblog_00413/article/details/148506087

FastAPI-Users 从 0.8.x 升级到 1.x.x 迁移指南

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

前言

FastAPI-Users 1.0 版本带来了重大变更，本文将详细介绍如何从 0.8.x 版本平滑迁移到 1.x.x 版本。作为技术专家，我将从架构变更、数据类型调整和代码重构三个方面深入解析这次升级的关键点。

核心变更：UUID 类型的使用

变更背景

1.0 版本最显著的改变是将用户和 OAuth 账户的 ID 从字符串类型改为真正的 UUID 对象。这一变更是为了充分利用支持 UUID 的数据库系统（特别是 PostgreSQL 和 MongoDB）的高效存储和索引能力。

Python 代码调整

比较操作修改

在测试代码或其他地方，如果你之前直接比较用户 ID 和字符串，现在需要先将 UUID 转换为字符串：

# 旧版本
assert "d35d213e-f3d8-4f08-954a-7e0d1bea286f" == user.id

# 新版本
assert "d35d213e-f3d8-4f08-954a-7e0d1bea286f" == str(user.id)

Pydantic 模型调整

如果你的 Pydantic 模型中引用了用户 ID，字段类型需要从 str 改为 UUID4：

from pydantic import BaseModel, UUID4

# 旧版本
class Model(BaseModel):
    user_id: str

# 新版本
class Model(BaseModel):
    user_id: UUID4

数据库迁移指南

PostgreSQL 迁移

PostgreSQL 原生支持 UUID 类型。迁移步骤如下：

确保启用 uuid-ossp 扩展
创建新 UUID 列
转换现有数据
替换原主键列

CREATE EXTENSION IF NOT EXISTS "uuid-ossp";

ALTER TABLE "user" ADD uuid_id UUID;
UPDATE "user" SET uuid_id = uuid(id);
ALTER TABLE "user" DROP id;
ALTER TABLE "user" ADD PRIMARY KEY (uuid_id);
ALTER TABLE "user" RENAME COLUMN uuid_id TO id;

MySQL 迁移

MySQL 不支持原生 UUID 类型，建议使用 CHAR(36)：

ALTER TABLE "user" MODIFY id CHAR(36);

MongoDB 迁移

对于 MongoDB，建议在连接时设置 UUID 表示方式为 "standard"：

client = motor.motor_asyncio.AsyncIOMotorClient(
    DATABASE_URL, uuidRepresentation="standard"
)

数据迁移脚本示例：

async def migrate_uuid():
    client = motor.motor_asyncio.AsyncIOMotorClient(
        DATABASE_URL, uuidRepresentation="standard"
    )
    db = client["database_name"]
    users = db["users"]

    async for user in users.find({}):
        await users.update_one(
            {"_id": user["_id"]},
            {"$set": {"id": uuid.UUID(user["id"])}},
        )

路由架构重构

变更概述

1.0 版本将原先单一的路由器拆分为多个独立的路由器，开发者需要手动组合这些路由。这种设计提供了更大的灵活性，允许开发者按需选择功能模块。

迁移示例

旧版本代码结构

fastapi_users = FastAPIUsers(
    user_db, [jwt_authentication], User, UserCreate, UserUpdate, UserDB,
)
app.include_router(fastapi_users.router, prefix="/users", tags=["users"])

新版本代码结构

app = FastAPI()
fastapi_users = FastAPIUsers(
    user_db, [jwt_authentication], User, UserCreate, UserUpdate, UserDB,
)

# 认证路由
app.include_router(
    fastapi_users.get_auth_router(jwt_authentication), 
    prefix="/auth/jwt", 
    tags=["auth"]
)

# 注册路由
app.include_router(
    fastapi_users.get_register_router(on_after_register), 
    prefix="/auth", 
    tags=["auth"]
)

# 密码重置路由
app.include_router(
    fastapi_users.get_reset_password_router(
        SECRET, after_forgot_password=on_after_forgot_password
    ),
    prefix="/auth",
    tags=["auth"],
)

# 用户管理路由
app.include_router(
    fastapi_users.get_users_router(), 
    prefix="/users", 
    tags=["users"]
)