FastAPI集成Tortoise-ORM提前初始化模型失败及关联字段缺失问题

核心问题分析 #

你遇到的问题主要来自三个方面：模块路径配置错误、Tortoise.init_models调用参数错误，以及关联字段未正确加载。以下是针对性的解决方案：

1. 修正模型模块导入配置 #

你的目录结构是src/下有main.py和models/子目录，要让Tortoise正确识别模型，有两种可行方式：

方式一：通过models/__init__.py批量导入模型 #

在src/models/__init__.py中导入所有模型类，让Tortoise可以通过包名直接识别所有模型：

# src/models/__init__.py
from .user import User
from .task import Task
from .client import Client

之后在register_tortoise的modules参数中直接写包名即可：

modules={
    'models': ["models"]
},

方式二：直接指定单个模型文件路径 #

如果不想写__init__.py，可以在modules中明确列出每个模型文件的模块路径（路径相对于main.py）：

modules={
    'models': ["models.user", "models.task", "models.client"]
},

2. 移除错误的Tortoise.init_models调用 #

register_tortoise内部已经完成了模型初始化工作，不需要手动调用Tortoise.init_models。你之前调用时还犯了参数错误：第二个参数是数据库连接别名（比如default），不是模块名。重复调用反而会导致初始化冲突。

3. 确保查询时加载关联字段 #

即使模型配置正确，Tortoise默认不会自动加载关联字段，需要在查询时显式调用select_related（用于外键/一对一关联）或prefetch_related（用于多对多/反向关联）：

# 示例：查询用户并加载关联的客户端
@app.get("/users")
async def get_users():
    # 多对多/反向关联用prefetch_related，正向外键用select_related
    users = await User.all().prefetch_related("client")
    return users

修正后的完整数据库配置代码 #

import sys
from pathlib import Path
from fastapi import FastAPI
from tortoise.contrib.fastapi import register_tortoise

# 确保src目录被Python识别（如果运行时工作目录不是src，这一步很重要）
sys.path.append(str(Path(__file__).parent))

# 数据库URI生成函数
def get_mysql_db_uri(*, user, host, db_name):
    return f'mysql://{user}@{host}:3306/{db_name}'

def get_sqlite_db_uri(db_name_with_extension):
    return f'sqlite://{db_name_with_extension}'

def setup_database(app: FastAPI):
    register_tortoise(
        app,
        db_url="sqlite://testtort.db",
        modules={
            'models': ["models"]  # 对应方式一的配置，若用方式二则替换为具体模型路径
        },
        default_connection="default",
        generate_schemas=True,
        add_exception_handlers=True,
    )

额外注意事项 #

• 确保运行FastAPI时的工作目录是src/，或者通过sys.path将src加入Python的模块搜索路径，避免出现ModuleNotFoundError
• 检查模型中的关联字段定义是否正确，比如ForeignKeyField的related_name是否设置合理，是否指定了on_delete参数

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