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 "ColumnInteger" cannot be assigned to parameter of type "int"

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

2. IDE 智能感知

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

用法对比

1. 基本字段

旧写法 (Legacy):

from sqlalchemy import Column, Integer, String

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

新写法 (Modern - SQLAlchemy 2.0+):

from sqlalchemy.orm import Mapped, mapped_column
from sqlalchemy import String
from typing import Optional

class User(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=True
    email: Mapped[Optional[str]] = mapped_column(String(100))

2. 复杂类型 (UUID, DateTime)

旧写法:

import uuid
from sqlalchemy.dialects.postgresql import UUID
from sqlalchemy import Column, DateTime, func

class Document(Base):
    id = Column(UUID(as_uuid=True), primary_key=True, default=uuid.uuid4)
    created_at = Column(DateTime(timezone=True), server_default=func.now())

新写法:

import uuid
from datetime import datetime
from sqlalchemy.orm import Mapped, mapped_column
from sqlalchemy.dialects.postgresql import UUID
from sqlalchemy import DateTime, func

class Document(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. 外键与关系

旧写法:

from sqlalchemy import ForeignKey
from sqlalchemy.orm import relationship

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

新写法:

from sqlalchemy import ForeignKey
from sqlalchemy.orm import Mapped, mapped_column, relationship

class Post(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 等特殊类型，通常还是需要指定。

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