在 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类型歧义。
总结：Mapped[T] 不是运行时类型容器，而是映射契约的类型占位符。要让它在协议/鸭子类型场景中“透明”，就必须满足 SQLAlchemy 的最小映射约定——__tablename__ + primary_key。这是设计使然，而非缺陷。
