FastAPI中SQLAlchemy模型循环导入问题的解决方法咨询

问题背景 #

你的项目结构如下：

• models.py：存放数据库模型及核心Python方法
• routes.py：定义路由（URL）
• schemas.py：定义路由所需的各类Schema

当前users/models.py中的Profile模型关联了WAMessage类，而另一个目录下的WAMessage/models.py又反向关联Profile类，导致循环导入错误，同时后续可能有更多表需要关联用户相关模型，希望找到类似Django中get_user_model的字符串引用模型的解决方案。

解决方案 #

1. 使用字符串形式指定关系中的模型名称 #

SQLAlchemy的relationship方法支持直接传入模型类名的字符串，而非导入的类本身，这是解决循环导入最直接的方式。同时，类型注解可以用引号包裹类名（Python支持字符串形式的类型注解），避免提前导入类。

修改users/models.py中的Profile模型：

from __future__ import annotations  # Python 3.7+ 可选，延迟类型解析
from sqlalchemy import Integer, String, DateTime, ForeignKey
from sqlalchemy.orm import Mapped, mapped_column, relationship
from datetime import datetime, timezone

class User(Base):
    __tablename__ = "users"

    id: Mapped[int | None] = mapped_column(Integer, primary_key=True, default=None)
    username: Mapped[str] = mapped_column(String(50), unique=True, nullable=False)
    email: Mapped[str] = mapped_column(String(120), unique=True, nullable=False)
    hashed_password: Mapped[str] = mapped_column(String(200), nullable=False)

    profile: Mapped[Profile] = relationship("Profile", back_populates="user", uselist=False)


class Profile(Base):
    __tablename__ = "profiles"

    id: Mapped[int | None] = mapped_column(Integer, primary_key=True, default=None)
    user: Mapped[User] = relationship("User", back_populates="profile")
    user_id: Mapped[int] = mapped_column(ForeignKey("users.id"), nullable=False, index=True)

    paied_until: Mapped[datetime] = mapped_column(
        DateTime(timezone=True), default=lambda: datetime.now(timezone.utc), nullable=False
    )
    from_phone: Mapped[str | None] = mapped_column(String(20), nullable=True, default=None)
    # 用字符串指定WAMessage类名，避免导入
    messages: Mapped[list["WAMessage"]] = relationship(
        "WAMessage", back_populates="profile", cascade="all, delete-orphan"
    )

修改WAMessage/models.py中的WAMessage模型：

from __future__ import annotations  # Python 3.7+ 可选
from sqlalchemy import String, Text, ForeignKey, Integer
from sqlalchemy.orm import Mapped, mapped_column, relationship

class WAMessage(Base):
    __tablename__ = 'wa_messages'

    status: Mapped[str] = mapped_column(String(9), nullable=False, default=WAMessageStatusChoices.waiting)
    attachment_file: Mapped[str | None] = mapped_column(String(200), nullable=True, default=None)
    content: Mapped[str] = mapped_column(Text, nullable=False)
    # 注意：profiles.id是int类型，这里修正为Mapped[int]
    user_id: Mapped[int] = mapped_column(ForeignKey("profiles.id"), nullable=False, index=True)
    # 用字符串指定Profile类名，避免导入
    profile: Mapped["Profile"] = relationship("Profile", back_populates="messages")

2. 启用延迟类型解析（Python 3.7+） #

在模型文件顶部添加from __future__ import annotations，Python会将类型注解视为字符串延迟解析，即使你写Mapped[WAMessage]也不会在导入时触发类的引用检查，配合字符串形式的relationship参数，能彻底避免循环导入。

3. 类似Django get_user_model的实现（可选） #

如果需要动态获取模型，可以基于SQLAlchemy的Base元数据实现：

# core/utils.py
from your_app.db import Base  # 假设你的Base定义在db.py中

def get_user_model():
    # 通过表名获取对应的模型类
    return Base.classes.get("users")

调用时直接使用get_user_model()即可获取User类，适合需要动态引用模型的场景。

额外提示 #

注意WAMessage中的user_id字段类型，原代码中是Mapped[str]，但profiles.id是int类型，会导致数据库类型不匹配，建议修正为Mapped[int]。

内容的提问来源于stack exchange，提问作者eng.ragy