如何解决强关联类导致的循环导入与Pydantic报错问题？

问题场景 #

在FastAPI模块化架构里，users/schemas.py的User模型和posts/schemas.py的Post模型互相引用，触发循环导入错误。简化后的项目结构：

src/
  users/
    schemas.py
  posts/
    schemas.py
  main.py

尝试过字符串注解、TypeVar、ForwardRef等方法后，要么循环导入问题依旧，要么触发pydantic.errors.PydanticUndefinedAnnotation: name 'Post' is not defined报错。

可行解决方案 #

方案1：字符串注解 + 手动重建模型（适配Pydantic 2.x） #

Pydantic 2.x支持字符串形式的类型注解，但必须在模型定义完成后手动调用model_rebuild()解析引用，同时调整导入顺序避免模块加载时的循环依赖。

修改users/schemas.py：

from pydantic import BaseModel
from typing import List

class User(BaseModel):
    # 用字符串形式引用尚未定义的Post模型
    posts: List["Post"]

# 延迟导入，放在模型定义之后
from ..posts.schemas import Post
# 手动解析前向引用
User.model_rebuild()

修改posts/schemas.py：

from pydantic import BaseModel
from typing import List

class Post(BaseModel):
    # 用字符串形式引用尚未定义的User模型
    users: List["User"]

# 延迟导入，放在模型定义之后
from ..users.schemas import User
# 手动解析前向引用
Post.model_rebuild()

关键点：

• Pydantic 2.x用model_rebuild()替代了旧版的update_forward_refs()，专门用来处理未解析的前向引用
• 把交叉导入放在模型定义之后，避免模块初始化阶段的循环依赖

方案2：抽离公共模型（架构层面解决） #

如果两个模型关联紧密，直接把它们移到同一个公共模块，从根源消除循环导入。

创建src/common/schemas.py：

from pydantic import BaseModel
from typing import List

# 先定义空模型占位
class User(BaseModel):
    posts: List["Post"]

class Post(BaseModel):
    users: List["User"]

# 互相解析引用
User.model_rebuild()
Post.model_rebuild()

如果需要扩展模型，在各自模块继承公共模型即可：

# users/schemas.py
from ..common.schemas import User

class ExtendedUser(User):
    email: str

# posts/schemas.py
from ..common.schemas import Post

class ExtendedPost(Post):
    content: str

优势：从架构层面解决循环依赖，代码结构更清晰，适合关联紧密的模型场景。

为什么之前的尝试失败？ #

• TypeVar是用来定义泛型类型的，不是解决前向引用的工具，无法解析模型依赖
• 单独使用ForwardRef时，没有调用model_rebuild()完成引用解析，导致Pydantic无法识别模型名称

验证运行 #

main.py无需改动，直接启动Uvicorn即可：

uvicorn src.main:app --reload

内容的提问来源于stack exchange，提问作者Abel Rodríguez