使用SQLModel时出现PydanticUndefinedAnnotation错误：name 'BlogPublicGeneric' is not defined

我来帮你分析下这个问题的核心原因，以及对应的解决办法：

首先，这个报错的根源在于运行时Pydantic解析字符串注解时找不到BlogPublicGeneric类：

• 你在category.py里用了TYPE_CHECKING条件导入，这个常量只在类型检查工具（比如mypy）运行时为True，Python实际运行时是False——也就是说，BlogPublicGeneric只在类型检查阶段被导入，运行时你的category.py命名空间里根本没有这个类的定义。
• 当你用字符串注解"BlogPublicGeneric"时，Pydantic在运行时需要找到这个名称对应的类，但因为它不在当前模块的命名空间，也没有指定完整的模块路径，所以就抛出了PydanticUndefinedAnnotation错误。
• 至于BlogPublic能正常工作，大概率是因为在运行时的某个环节（比如其他模块的导入传递），BlogPublic被意外加载到了category.py的命名空间里，刚好满足了Pydantic的解析需求。

下面给你两个靠谱的解决办法：

办法1：使用完整模块路径作为字符串注解 #

直接把category.py里的blogs字段注解改成完整的模块路径，让Pydantic能精准定位到类：

class CategoryPublic(TimestampModel, CategoryBase, UUIDModel):
    items: list["ItemPublicGeneric"] = []
    # 替换为完整模块路径的字符串注解
    blogs: list["app.api.database.models.blog.BlogPublicGeneric"] = []

这种方式完全不需要在category.py里导入BlogPublicGeneric，既能避开循环导入问题，又能保证运行时和类型检查阶段都能正确识别类型，是最稳妥的方案。

办法2：在运行时延迟导入类 #

如果不想写长路径，可以在category.py的最底部添加运行时的导入（避开循环导入的初始化冲突）：

# 放在category.py文件的最底部
if not TYPE_CHECKING:
    from app.api.database.models.blog import BlogPublicGeneric

这样Python运行时会把BlogPublicGeneric加载到当前模块的命名空间里，Pydantic解析"BlogPublicGeneric"字符串时就能找到对应的类了。不过要注意，这种方式依赖你已经启用的from __future__ import annotations延迟解析特性，好在你已经配置了这个特性，所以不会触发循环导入的问题。

小建议 #

对于这种存在循环引用的响应模型（比如博客和分类的公共展示模型），优先使用完整模块路径的字符串注解，既能减少导入的麻烦，也能避免潜在的循环导入坑。

备注：内容来源于stack exchange，提问作者Semih Vicir