SQLAlchemy Mapped注解循环引用报错：如何正确定义关联模型？

问题背景 #

使用SQLAlchemy 2.0新风格Mapped注解定义关联继承模型时，Company类中声明managers: Mapped[List[Manager]]时，Manager类尚未定义，触发错误：

sqlalchemy.exc.ArgumentError: Could not interpret annotation Mapped[List[Manager]].  Check that it uses names that are correctly imported at the module level. See chained stack trace for more hints.

解决方案 #

方法1：使用字符串类型引用（推荐） #

SQLAlchemy支持在Mapped注解中使用字符串类名代替直接引用，框架会在所有模型初始化完成后解析字符串对应的类，完美解决循环依赖问题。

修改models.py中的字段定义：

# Company类中
managers: Mapped[List["Manager"]] = relationship(back_populates="company")

# Manager类中（可选，统一风格）
company: Mapped["Company"] = relationship(back_populates="managers")

方法2：调整类定义顺序 #

将Manager类移到Company类之前定义，确保Company引用Manager时类已存在。调整后的类顺序为：
Employee → Manager → Company → Engineer

方法3：在relationship中指定字符串类名 #

如果不想修改Mapped注解，也可以在relationship的第一个参数中传入字符串类名：

managers: Mapped[List[Manager]] = relationship("Manager", back_populates="company")

修改后的完整models.py示例 #

from sqlalchemy import ForeignKey
from sqlalchemy.orm import Mapped, mapped_column, relationship
from typing import List
from database import Base

class Employee(Base):
    __tablename__ = "employee"
    id: Mapped[int] = mapped_column(primary_key=True)
    name: Mapped[str]
    type: Mapped[str]

    __mapper_args__ = {
        "polymorphic_identity": "employee",
        "polymorphic_on": "type",
    }

class Manager(Employee):
    __tablename__ = "manager"
    id: Mapped[int] = mapped_column(ForeignKey("employee.id"), primary_key=True)
    manager_name: Mapped[str]

    company_id: Mapped[int] = mapped_column(ForeignKey("company.id"))
    company: Mapped["Company"] = relationship(back_populates="managers")

    __mapper_args__ = {
        "polymorphic_identity": "manager",
    }

class Company(Base):
    __tablename__ = "company"
    id: Mapped[int] = mapped_column(primary_key=True)
    name: Mapped[str]
    managers: Mapped[List["Manager"]] = relationship(back_populates="company")

class Engineer(Employee):
    __tablename__ = "engineer"
    id: Mapped[int] = mapped_column(ForeignKey("employee.id"), primary_key=True)
    engineer_name: Mapped[str]
    
    __mapper_args__ = {
        "polymorphic_identity": "engineer",
    }

导入与建表注意事项 #

• database.py中的init_db函数已正确导入models模块，确保所有模型被注册到Base的元数据中，无需额外修改。
• 运行flask run前，确认数据库连接字符串正确，若使用了自定义schema（如示例中的metadata），需先在数据库中创建该schema。
• Base.metadata.create_all(bind=engine)会自动处理表的依赖顺序，无需手动调整建表顺序。

内容的提问来源于stack exchange，提问作者andilabs