动态注入SQLAlchemy ORM基类时如何保留静态类型检查？

这个问题我之前折腾SQLAlchemy模块化架构时也碰到过——动态生成模型的方式确实灵活，但静态类型检查器（比如Pylance）根本认不出函数里返回的类，各种类型报错让人头疼。不过不用重复写模型定义，有几个实用的方案能解决这个矛盾：

方案一：用typing.TYPE_CHECKING实现静态类型占位 #

这是最常用的折中方案，利用TYPE_CHECKING常量在运行时为False、类型检查时为True的特性，给检查器提供静态的模型骨架，同时运行时用动态生成的真实模型。

修改你的schema.py：

from typing import TYPE_CHECKING, Mapped
from sqlalchemy import String
from sqlalchemy.orm import mapped_column, declarative_base

# 类型检查阶段创建一个假的Base，运行时不会生效
if TYPE_CHECKING:
    FakeBase = declarative_base()
else:
    FakeBase = object

# 静态定义模型结构，专门给类型检查器看
class File(FakeBase):
    __tablename__ = "files"
    id: Mapped[str] = mapped_column(String(36))

def schema(Base):
    # 动态生成继承真实Base的模型
    class _File(Base):
        __tablename__ = "files"
        id: Mapped[str] = mapped_column(String(36))
    
    # 让动态模型复用静态模型的注解，保证类型一致
    _File.__annotations__ = File.__annotations__
    return (_File,)

然后在Files.py里直接用静态定义的File做类型注解：

from typing import List
from .schema import File, schema

class Files:
    files: List[File] = []  # Pylance现在能正常识别这个类型了

    def __init__(self, Base):
        (self.File,) = schema(Base)
        some_files: List[File] = []  # 这里也不会再报"变量不允许在类型表达式中"的错误

这个方案完全保留了你动态注入Base的设计，同时字段定义只写一次，符合DRY原则。

方案二：用Protocol定义模型接口 #

如果不想搞假Base的套路，可以用typing.Protocol定义模型必须实现的属性接口，让类型检查器把动态生成的模型和这个接口关联起来。

修改schema.py：

from typing import Protocol, Mapped
from sqlalchemy import String
from sqlalchemy.orm import mapped_column

# 定义模型的属性协议
class FileProtocol(Protocol):
    id: Mapped[str]

def schema(Base):
    class File(Base):
        __tablename__ = "files"
        id: Mapped[str] = mapped_column(String(36))
    
    return (File,)

在使用的地方用FileProtocol做类型注解：

from typing import List
from .schema import schema, FileProtocol

class Files:
    files: List[FileProtocol] = []

    def __init__(self, Base):
        (File,) = schema(Base)
        self.File = File
        some_files: List[FileProtocol] = []

这个方法更偏向接口契约，适合只关心模型属性的场景，缺点是没法直接用模型类本身做类型（比如Type[FileProtocol]），但大部分业务场景下完全够用。

方案三：调整Base的导入方式（折中架构） #

你提到不想反向导入Base觉得数据流不对，但其实可以把Base放在一个独立的核心模块（比如core/db.py），让schema模块依赖这个核心模块——这其实是正常的分层架构（基础模块提供工具，业务模块依赖基础），而且能让模型静态定义，彻底解决类型检查问题。

比如：

# core/db.py
from sqlalchemy.orm import declarative_base

# 单例模式创建Base，确保全局唯一
def get_base():
    if not hasattr(get_base, "_base"):
        get_base._base = declarative_base()
    return get_base._base

然后在schema模块里直接静态定义模型：

from core.db import get_base
from sqlalchemy import String
from sqlalchemy.orm import mapped_column, Mapped

class File(get_base()):
    __tablename__ = "files"
    id: Mapped[str] = mapped_column(String(36))

如果需要动态控制加载哪些schema，用importlib动态导入模块即可：

# main.py
from core.db import get_base
import importlib
from dotenv import load_dotenv
import os

load_dotenv()
# 根据环境变量获取要加载的schema列表
schemas_to_load = os.getenv("ENABLED_SCHEMAS", "").split(",")

for schema_path in schemas_to_load:
    if schema_path.strip():
        importlib.import_module(schema_path.strip())

# 生成数据库表
Base = get_base()
Base.metadata.create_all(engine)

这个方案彻底避免了动态生成类的麻烦，类型检查完全正常，架构也更清晰。

备注：内容来源于stack exchange，提问作者Matt Fletcher