FastAPI搭配Mongoengine运行报未定义默认连接错误如何解决

• 连接代码执行时机晚于模型加载/数据库操作：FastAPI启动时如果先导入了模型文件，再执行connect连接代码，模型初始化时找不到已经建立的default连接，就会抛出该错误。
• 多进程/多实例运行冲突：如果你的FastAPI用了uvicorn的多worker模式，或者开启了reload自动重载，连接会在进程fork时丢失，子进程没有继承父进程的MongoDB连接。
• 连接建立失败被静默忽略：如果MongoDB服务本身没有启动、端口映射错误、权限验证失败，connect方法虽然执行了但实际上没有成功建立连接，也会报未定义default连接的错误。
• 显式断开连接的代码被误执行：如果项目中某处调用了disconnect(alias='default')且后续没有重新连接，也会触发该错误。

• 调整代码执行顺序：把connect连接代码放到项目入口文件的最顶部，早于所有模型导入、接口定义的代码执行。比如FastAPI的main.py开头就先执行连接，再导入其他模块：

# main.py 开头第一部分代码
from mongoengine import connect
connect(db="mydb", host='localhost', port=27017, alias='default')

# 后续再导入模型、路由等
from models import Usuario, Grupo, Permissao
from routers import xxx

• 适配多worker/reload模式：不要在全局作用域直接执行connect，而是用FastAPI的生命周期事件钩子执行连接：

from fastapi import FastAPI
from mongoengine import connect, disconnect

app = FastAPI()

@app.on_event("startup")
def startup_db_client():
    connect(db="mydb", host='localhost', port=27017, alias='default')

@app.on_event("shutdown")
def shutdown_db_client():
    disconnect(alias='default')

• 排查MongoDB服务可用性：先在终端用mongosh命令连接本地27017端口，确认服务正常运行、mydb库可以正常访问，如果有鉴权需求要在connect参数中补充username、password、authentication_source参数。
• 排查异常断开逻辑：全局搜索项目中的disconnect调用，确认没有在请求处理逻辑中误调用default连接的断开方法，若有断开逻辑要配套重连逻辑。

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