使用泛型编写抽象ObjectRepository类的类型警告问题排查

编辑补充：正如@PanagiotisKanavos在评论中指出，该数据库交互方式存在冗余，但因核心问题是泛型的使用，故保留提问。

我尝试为多个不同SQLModel模型编写泛型仓储类，已将_ModelType这个TypeVar绑定到SQLModel，但返回SQLModel类型的方法仍收到类型警告（预期返回_ModelType），约束为SQLModel也没用。功能正常，但想搞懂警告原因和解决方法，同时有几个疑问：是否误用泛型？是不是反模式/过度设计？能不能直接用_ModelType替代构造函数传入的model_class？

抽象仓储类代码 #

from sqlmodel import SQLModel, Session, select
import typing
from sqlalchemy.engine.result import ScalarResult
from sqlalchemy.sql.expression import _ColumnExpressionArgument


_ModelType = typing.TypeVar(
    "_ModelType",
    bound=SQLModel,
)


class BaseRepository(typing.Generic[_ModelType]):

    def __init__(self, session: Session, model_class: typing.Type[SQLModel]):
        self.session = session
        self.__model_class = model_class

    # Static hinting works as expected
    def save(self, obj: _ModelType) -> _ModelType:
        """
        Generic method to save an object to the database.
        """
        self.session.add(obj)
        return obj
    
    def get_one(self, obj_id: typing.Any) -> typing.Optional[_ModelType]:
        obj = self.session.get(self.__model_class, obj_id) #SQLModel | None
        return obj 
        # Warning: Type "SQLModel" is not assignable to type "_ModelType@BaseRepository"

    def query(self, 
              *conditions: typing.Union[_ColumnExpressionArgument[bool], bool]
              ) -> ScalarResult[_ModelType]:

        stmt = select(self.__model_class)
        for c in conditions:
            stmt = stmt.where(c)

        return self.session.exec(stmt).all() 
            #Similar warning along with: Type parameter "_T_co@Sequence" is covariant,
            #but "SQLModel" is not a subtype of "_ModelType@BaseRepository"

使用示例代码 #

from utils.db_new import engine
from order_management.repository_new import BaseRepository
from order_management.models import Order, Customer
from sqlmodel import Session
import logging

logging.basicConfig(level=logging.INFO)

order_repo = BaseRepository[Order](Session(engine), Order)

all_orders = order_repo.query(
    Order.pickup_type == "pickup",
    Customer.name == "Diaa Malek",
)
[print(o.id) for o in all_orders]

order = order_repo.get_one(1088)
if order:
    print(order.items)

问题解答 #

警告原因 #

当前代码中，__model_class的类型被标注为typing.Type[SQLModel]，但泛型参数_ModelType是SQLModel的子类。类型检查器无法确定__model_class就是当前泛型实例对应的_ModelType类——它只知道这是某个SQLModel子类，但无法关联到具体的泛型参数类型。因此从session.get或查询返回的SQLModel对象，类型检查器认为无法赋值给_ModelType，从而抛出警告。

解决方法 #

方法1：修正model_class的类型注解（推荐）

把model_class的类型从typing.Type[SQLModel]改成typing.Type[_ModelType]，让类型检查器明确__model_class就是当前泛型对应的具体模型类：

def __init__(self, session: Session, model_class: typing.Type[_ModelType]):
    self.session = session
    self.__model_class = model_class

修改后，session.get的返回类型会被自动推断为Optional[_ModelType]，查询结果也会正确关联到_ModelType，警告将完全消失。

方法2：用typing.cast强制类型转换（不推荐）

如果不想修改构造函数注解，可以在返回时用cast告知类型检查器实际类型：

from typing import cast

def get_one(self, obj_id: typing.Any) -> typing.Optional[_ModelType]:
    obj = self.session.get(self.__model_class, obj_id)
    return cast(typing.Optional[_ModelType], obj)

这种方法属于强制绕过类型检查，不如第一种方法严谨，仅作为临时替代方案。

关于泛型使用的疑问 #

是否误用泛型？

没有误用。泛型在这里的作用是为不同SQLModel模型提供统一的仓储接口，同时保留精确的类型提示，这是泛型的典型合理应用场景。

是否是反模式或过度设计？

取决于项目规模和需求：

• 如果项目模型数量少、操作逻辑简单，手动编写每个模型的仓储类可能更高效；
• 如果模型多、重复操作多，泛型仓储能大幅减少重复代码、提升维护性，此时不属于过度设计。但要注意避免过度封装——若某些模型有特殊查询逻辑，可通过继承BaseRepository扩展，而非强行塞进泛类。

能否直接用_ModelType替代构造函数传入的model_class？

不行。Python的泛型是运行时擦除的，运行时无法直接获取_ModelType的具体类型。必须通过构造函数传入model_class，才能在运行时确定要操作的模型。虽然可以通过元类、类装饰器等技巧简化，但会增加复杂度，不如直接传入模型类直观。

内容的提问来源于stack exchange，提问作者Diaa Eldin Malek