FastAPI项目中selectinload触发PyCharm/mypy类型错误的解决咨询

开发FastAPI+SQLModel+SQLAlchemy项目时，PyCharm和mypy均报出类型错误：

PyCharm提示：

expected type 'Literal["*"] | QueryableAttribute', got 'list[Account] | None' instead

mypy提示：

error: Argument 1 to "selectinload" has incompatible type "list[Account] | None"; expected "Literal['*'] | QueryableAttribute[Any]" [arg-type]

错误由以下代码触发：

from sqlalchemy.orm import selectinload


class CRUDCounterPartyCommon(
    CRUDBase[CounterParty, CounterpartyCommonCreateUpdateSchema, CounterpartyCommonCreateUpdateSchema]
):
    async def get_by_uuid(self, db: AsyncSession, *, _uuid: uuid.UUID) -> Optional[CounterParty]:
        counterparty = select(CounterParty).where(CounterParty.id == _uuid).options(selectinload(CounterParty.accounts))

同时，基础CRUD类中使用selectinload时无异常：

class CRUDBase(Generic[ModelType, CreateSchemaType, UpdateSchemaType]):
    async def get_by_field_name(
        self,
        db: AsyncSession,
        field_name: str,
        field_value: str,
        _select: ModelType,
        selection_load_options: Optional[List[Tuple]] = None,
        conditions: Optional[List[Tuple]] = None,
        joins: Optional[List[Tuple]] = None,
    ) -> ModelType:
        query = select(_select)
        if joins:
            for table, condition in joins:
                query = query.join(table, condition)
        if selection_load_options:
            for options_tuple in selection_load_options:
                options_obj = None
                for option in options_tuple:
                    if options_obj is None:
                        options_obj = selectinload(option)
                    else:
                        options_obj = options_obj.options(selectinload(option))
                if options_obj:
                    query = query.options(options_obj)
        if conditions:
            for key, value, comparison in conditions:
                query = query.where(comparison(key, value))
        query = query.where(field_name == field_value)
        try:
            query = query.group_by(self.model.id)
        except Exception:
            pass

这个错误的核心是CounterParty.accounts被类型检查工具识别为实例属性（类型为list[Account]|None），但selectinload需要传入的是模型的ORM关系属性（QueryableAttribute类型）。可通过以下步骤修复：

1. 检查CounterParty模型的关系定义
   确保accounts使用SQLModel/SQLAlchemy的RelationshipAPI定义，而非直接注解为列表类型：

   from sqlmodel import SQLModel, Relationship, Field
   import uuid
   
   class CounterParty(SQLModel, table=True):
       id: uuid.UUID = Field(default_factory=uuid.uuid4, primary_key=True)
       # 正确标记ORM关系
       accounts: list["Account"] = Relationship(back_populates="counterparty")
   

   仅写accounts: list[Account]会被视为普通实例属性，必须用Relationship()明确这是ORM关联字段。

2. 显式修正类型注解
   若模型定义无误但类型检查仍报错，可通过类型转换明确字段类型：

   from sqlalchemy.orm import QueryableAttribute
   from typing import cast
   
   # 使用时显式转换类型
   selectinload(cast(QueryableAttribute[list[Account]], CounterParty.accounts))
   

3. 升级依赖版本
   旧版SQLAlchemy/SQLModel可能存在类型注解不完善的问题，升级到最新稳定版：

   pip install --upgrade sqlalchemy sqlmodel mypy
   

4. 调整PyCharm类型检查配置
   确保PyCharm启用mypy作为类型检查器，并安装SQLAlchemy/SQLModel相关的类型支持插件，避免自带检查器误判。

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