SQLAlchemy 2.0 中 Mapped 字段类型检查失败的解决方案-Python教程-PHP中文网

SQLAlchemy 2.0 中 Mapped 字段类型检查失败的解决方案

在 SQLAlchemy 2.0+ 中，仅声明 Mapped[int] 字段不足以让 mypy 正确推断运行时属性类型；需显式标注主键并设置 __tablename__，才能激活 ORM 模型的运行时属性注入机制，使 Mapped[T] 在类型检查中被正确“解包”为 T。

在 sqlalchemy 2.0+ 中，仅声明 `mapped[int]` 字段不足以让 `mypy` 正确推断运行时属性类型；需显式标注主键并设置 `__tablename__`，才能激活 orm 模型的运行时属性注入机制，使 `mapped[t]` 在类型检查中被正确“解包”为 `t`。

SQLAlchemy 的 Mapped[T] 是一个类型提示专用标记（type-only construct），它本身不参与运行时赋值——真正的属性（如 spam.id）是在模型类实例化或映射完成时，由 SQLAlchemy 运行时动态注入的 int 值。但 mypy 作为静态类型检查器，并不了解这一动态行为，它仅依赖类型注解和协议兼容性规则进行推导。

关键在于：只有当 SQLAlchemy 将模型类成功注册为映射类（即完成 declarative mapping）后，Mapped[T] 字段才会在类型层面被 mypy 插件（或内置支持）识别为可“投影”为 T 的属性。而这一映射触发的前提是——模型类必须满足最小映射契约：

显式定义 __tablename__（或继承自 DeclarativeBase 并启用自动表名推导，但显式更可靠）；
至少一个列被标记为 primary_key=True（这是 SQLAlchemy 判断实体完整性的关键信号）。

因此，原始代码中：

class SpamModel(Base):
    id: Mapped[int] = mapped_column(Integer())  # ❌ 缺少 primary_key 和 __tablename__

虽然语法合法且运行时能工作，但 mypy 无法确认该类已进入“完全映射状态”，故保守地将 id 视为 Mapped[int] 类型，而非协议 SpamProt 所需的 int，导致协变协议匹配失败。

✅ 正确写法如下（修复后完整示例）：

from typing import Protocol
from sqlalchemy import Integer
from sqlalchemy.orm import DeclarativeBase, Mapped, mapped_column


class SpamProt(Protocol):
    id: int


class Base(DeclarativeBase):
    pass


class SpamModel(Base):
    __tablename__ = "spam"  # ✅ 必须显式声明表名
    id: Mapped[int] = mapped_column(Integer(), primary_key=True)  # ✅ 主键标记激活映射


def do_with_spam(d: SpamProt) -> None:
    print(f"Processing spam with ID: {d.id}")  # ✅ mypy 现在接受 spam 作为 SpamProt


if __name__ == "__main__":
    spam = SpamModel(id=10)
    do_with_spam(spam)  # ✅ 通过 mypy 检查，运行正常

⚠️ 注意事项：

即使使用 mapped_column(..., init=False) 或 defer() 等高级配置，只要 primary_key=True 存在且 __tablename__ 已设，mypy（配合 SQLAlchemy 2.0.30+ 内置类型支持）就能正确推导运行时属性类型；

不推荐依赖 # type: ignore 绕过此检查——它掩盖了映射不完整的问题，可能引发后续反射、序列化或 IDE 补全异常；

若需支持无主键的视图或临时模型，应改用 @hybrid_property 或显式定义 @property + @property.setter，避免 Mapped 类型歧义。