FastAPI模块化导入报错：TypeError: issubclass() arg 1 must be a class

问题原因 #

使用TYPE_CHECKING条件导入模型时，运行阶段"Item"仅作为字符串字面量存在，FastAPI依赖的Pydantic在生成OpenAPI Schema时，无法将该字符串解析为实际的模型类，进而在执行issubclass()校验时传入非类对象，触发TypeError: issubclass() arg 1 must be a class错误。

解决方案 #

以下两种方案可解决该问题：

方案1：添加运行时延迟导入 #

在user.py中补充运行时的延迟导入逻辑，确保Pydantic生成Schema时能找到对应的Item类：

from typing import List, TYPE_CHECKING, Optional
from sqlmodel import SQLModel, Field

if TYPE_CHECKING:
    from item import Item

# 运行时延迟导入，解决字符串引用解析问题
def __getattr__(name):
    if name == "Item":
        from item import Item
        return Item
    raise AttributeError(f"module {__name__} has no attribute {name}")

class User(SQLModel):
    id: int = Field(default=None, primary_key=True)
    age: Optional[int]
    bought_items: List["Item"] = []

方案2：使用SQLModel关系字段（数据库关联场景） #

如果bought_items是数据库表间的关联字段，应使用Relationship定义，SQLModel会自动处理模块化的类引用：
修改user.py：

from typing import List, TYPE_CHECKING, Optional
from sqlmodel import SQLModel, Field, Relationship

if TYPE_CHECKING:
    from item import Item

class User(SQLModel, table=True):
    id: int = Field(default=None, primary_key=True)
    age: Optional[int]
    bought_items: List["Item"] = Relationship(back_populates="owner")

同时修改item.py补充反向关联（按需调整）：

from typing import TYPE_CHECKING, Optional
from sqlmodel import SQLModel, Field, Relationship

if TYPE_CHECKING:
    from user import User

class Item(SQLModel, table=True):
    id: int = Field(default=None, primary_key=True)
    price: float
    name: str
    owner_id: Optional[int] = Field(default=None, foreign_key="user.id")
    owner: Optional["User"] = Relationship(back_populates="bought_items")

额外注意 #

• 方案1适用于纯API请求/响应模型（非数据库表模型），方案2是数据库关联场景的标准实现
• 两种方案均能避免循环导入问题，适配复杂模块化结构

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