SQLAlchemy 2.0 类型注解指南之Mapped与mapped_column详解_MsSqlserver

简介

在 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):

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