如何在FastAPI+SQLAlchemy中将关联的两个模型拆分到不同文件？

核心思路 #

拆分关联模型时，关键要解决循环导入和SQLAlchemy元数据加载两个问题，通过单独维护Base类、使用字符串类名引用关联关系、确保所有模型被加载这三个步骤即可实现。

具体实现步骤 #

1. 单独创建Base类文件

新建database.py，统一管理所有模型的基类，避免重复定义和循环导入问题：

from sqlalchemy.ext.declarative import declarative_base
from sqlalchemy import create_engine

# 根据你的数据库配置修改URL
DATABASE_URL = "sqlite:///./test.db"
engine = create_engine(DATABASE_URL, connect_args={"check_same_thread": False})

Base = declarative_base()

2. 拆分模型到独立文件

• models/persona.py：存放ToPersona模型

from sqlalchemy import Column, Integer, String
from sqlalchemy.orm import relationship
from database import Base

class ToPersona(Base):
    __tablename__ = 'to_persona'

    id_persona = Column(Integer, primary_key=True, index=True)
    fc_nombre = Column(String(50), nullable=False)
    # 反向关联ToUsuario，用字符串类名避免循环导入
    to_usuarios = relationship("ToUsuario", back_populates="to007_persona")

• models/usuario.py：存放ToUsuario模型

from sqlalchemy import Column, Integer, ForeignKey
from sqlalchemy.orm import relationship
from database import Base

class ToUsuario(Base):
    __tablename__ = 'to_usuario'

    id_usuario = Column(Integer, primary_key=True, index=True)
    fk_id_persona = Column(ForeignKey('to_persona.id_persona'))
    # 用字符串引用ToPersona类，无需直接导入
    to007_persona = relationship("ToPersona", back_populates="to_usuarios")

3. 初始化数据库时加载所有模型

在FastAPI的入口文件（比如main.py）中，导入所有模型并创建表，确保SQLAlchemy元数据中包含所有关联表的信息：

from fastapi import FastAPI
from database import Base, engine
# 必须导入所有模型，否则元数据中不会加载对应表
from models.persona import ToPersona
from models.usuario import ToUsuario

# 创建数据库表
Base.metadata.create_all(bind=engine)

app = FastAPI()

# 后续添加API路由...

常见问题排查 #

• 关联类找不到：检查是否在初始化时导入了所有模型，或者relationship中的字符串类名是否与实际类名完全一致（大小写敏感）。
• 循环导入报错：不要在persona.py和usuario.py中互相导入对方的模型类，完全依赖字符串类名引用关联关系即可避免。
• 外键约束错误：确认ForeignKey中的表名和字段名与目标模型的__tablename__和主键字段完全匹配。

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