SQLAlchemy 2.0 类型注解指南：`Mapped` 与 `mapped_column`

简介

在 SQLAlchemy 1.4 和 2.0 中，ORM（对象关系映射）引入了一种新的声明式映射系统，核心组件是Mapped类型注解和mapped_column构造函数。这种新风格旨在提供更好的 Python 类型提示（Type Hinting）支持，解决旧版Column写法在静态代码分析（如 Pyright, MyPy）和 IDE 自动补全方面的问题。

解决的问题

1. 静态类型检查报错

这是最常见的问题。在旧版写法中，模型属性被定义为Column对象，例如：

id=Column(Integer,primary_key=True)

对于静态分析工具（如 Pyright），id的类型是Column[Integer]。然而，当你实例化模型对象访问user.id时，其实际值是int类型。

当你尝试将user.id传递给一个期望int的函数时，Pyright 会报错：

Argument of type “Column[Integer]” cannot be assigned to parameter of type “int”

Mapped解决了这个问题。它明确告诉类型检查器，虽然我们在类定义中使用了描述符，但在实例中该属性表现为指定的 Python 类型。

2. IDE 智能感知

由于类型明确，现代 IDE（如 VS Code, PyCharm）能更准确地提供代码补全和错误提示。例如，定义为Mapped[str | None]的字段，IDE 会提示你该字段可能为 None。

用法对比

1. 基本字段

旧写法 (Legacy):

fromsqlalchemyimportColumn,Integer,StringclassUser(Base):__tablename__="user"id=Column(Integer,primary_key=True)name=Column(String(50),nullable=False)email=Column(String(100))

新写法 (Modern - SQLAlchemy 2.0+):

fromsqlalchemy.ormimportMapped,mapped_columnfromsqlalchemyimportStringfromtypingimportOptionalclassUser(Base):__tablename__="user"# Mapped[int] 告诉类型检查器：实例中的 id 是 int 类型# mapped_column(...) 定义了数据库列的属性id:Mapped[int]=mapped_column(primary_key=True)# nullable=False 是默认的，对应 Mapped[str]name:Mapped[str]=mapped_column(String(50))# Optional[str] 或 str | None 对应 nullable=Trueemail:Mapped[Optional[str]]=mapped_column(String(100))

2. 复杂类型 (UUID, DateTime)

旧写法:

importuuidfromsqlalchemy.dialects.postgresqlimportUUIDfromsqlalchemyimportColumn,DateTime,funcclassDocument(Base):id=Column(UUID(as_uuid=True),primary_key=True,default=uuid.uuid4)created_at=Column(DateTime(timezone=True),server_default=func.now())

新写法:

importuuidfromdatetimeimportdatetimefromsqlalchemy.ormimportMapped,mapped_columnfromsqlalchemy.dialects.postgresqlimportUUIDfromsqlalchemyimportDateTime,funcclassDocument(Base):# 明确指定 id 是 uuid.UUID 类型id:Mapped[uuid.UUID]=mapped_column(UUID(as_uuid=True),primary_key=True,default=uuid.uuid4)# 明确指定 created_at 是 datetime 类型created_at:Mapped[datetime]=mapped_column(DateTime(timezone=True),server_default=func.now())

3. 外键与关系

旧写法:

fromsqlalchemyimportForeignKeyfromsqlalchemy.ormimportrelationshipclassPost(Base):user_id=Column(Integer,ForeignKey("user.id"))user=relationship("User")

新写法:

fromsqlalchemyimportForeignKeyfromsqlalchemy.ormimportMapped,mapped_column,relationshipclassPost(Base):user_id:Mapped[int]=mapped_column(ForeignKey("user.id"))# 这里的 relationship 也支持 Mapped 类型user:Mapped["User"]=relationship()

关键点总结

1. 导入: 使用from sqlalchemy.orm import Mapped, mapped_column。
2. 类型注解: 必须为每个列添加 Python 类型注解（如: Mapped[int]）。
3. Nullable:
   • Mapped[str]隐含nullable=False。
   • Mapped[Optional[str]]或Mapped[str | None]隐含nullable=True。
4. SQL 类型: 在mapped_column()中通过第一个参数指定 SQL 类型（如String(50)），如果类型可以从 Python 类型推断（如int->Integer），则可以省略。但对于String（需要长度）或UUID等特殊类型，通常还是需要指定。

通过采用这种新写法，你的代码将更加健壮，更易于维护，并且能通过严格的静态类型检查。