SQLAlchemy 2.0 類型注解指南之Mapped與mapped_column詳解

更新時間：2025年12月30日 10:12:25 作者：nvd11

SQLAlchemy 1.4和2.0引入了新的聲明式映射系統(tǒng),核心組件是Mapped類型注解和mapped_column構造函數,旨在提供更好的Python類型提示支持,本文介紹SQLAlchemy 2.0 類型注解指南之Mapped與mapped_column,感興趣的朋友跟隨小編一起看看吧

簡介

在 SQLAlchemy 1.4 和 2.0 中，ORM（對象關系映射）引入了一種新的聲明式映射系統(tǒng)，核心組件是 Mapped 類型注解和 mapped_column 構造函數。這種新風格旨在提供更好的 Python 類型提示（Type Hinting）支持，解決舊版 Column 寫法在靜態(tài)代碼分析（如 Pyright, MyPy）和 IDE 自動補全方面的問題。

解決的問題

1. 靜態(tài)類型檢查報錯

這是最常見的問題。在舊版寫法中，模型屬性被定義為 Column 對象，例如：

id = Column(Integer, primary_key=True)

對于靜態(tài)分析工具（如 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 解決了這個問題。它明確告訴類型檢查器，雖然我們在類定義中使用了描述符，但在實例中該屬性表現(xiàn)為指定的 Python 類型。

2. IDE 智能感知

由于類型明確，現(xiàn)代 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()

關鍵點總結

導入: 使用 from sqlalchemy.orm import Mapped, mapped_column。
類型注解: 必須為每個列添加 Python 類型注解（如 : Mapped[int]）。
Nullable:
- Mapped[str] 隱含 nullable=False。
- Mapped[Optional[str]] 或 Mapped[str | None] 隱含 nullable=True。
SQL 類型: 在 mapped_column() 中通過第一個參數指定 SQL 類型（如 String(50)），如果類型可以從 Python 類型推斷（如 int -> Integer），則可以省略。但對于 String（需要長度）或 UUID 等特殊類型，通常還是需要指定。