使用Beanie ODM遇循环引用问题，启动应用报NameError

错误原因 #

1. 循环导入冲突：Entity引用Folder，而Folder又导入并继承Entity，导致运行时类型提示解析时找不到Folder的定义。
2. 引用类型错误：直接使用List[Folder]会被Beanie当作嵌入子文档处理，而非你需要的MongoDB文档交叉引用，同时也加剧了类型解析的问题。

修正后的代码 #

entity.py #

from __future__ import annotations  # Python3.7+可用，让类型提示自动转为字符串
from beanie import Document, Link
from typing import List, TYPE_CHECKING

# 仅在类型检查时导入Folder，避免运行时循环导入
if TYPE_CHECKING:
    from folder import Folder

class Entity(Document):
    # 使用Link类型定义对Folder文档的交叉引用列表
    path: List[Link[Folder]] = []

folder.py #

from entity import Entity

class Folder(Entity):
    pass

init_beanie.py #

import beanie
from motor.motor_asyncio import AsyncIOMotorClient
from entity import Entity
from folder import Folder

models = [Entity, Folder]

async def init_beanie():
    client = AsyncIOMotorClient("mongo-uri")

    # 为两个模型更新forward refs，解决类型解析问题
    Entity.update_forward_refs(Folder=Folder)
    Folder.update_forward_refs(Entity=Entity)

    await beanie.init_beanie(database=client["mongo-db-name"], document_models=models)

关键说明 #

• Link类型：Beanie的Link专门用于定义MongoDB文档之间的交叉引用，会自动存储目标文档的ObjectId，而非整个嵌入对象。
• TYPE_CHECKING条件导入：仅在代码静态检查时导入Folder，避免运行时触发循环导入。
• update_forward_refs：显式为两个模型更新类型引用，确保Python能正确解析循环依赖中的类型提示。

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