在将 SQLAlchemy 模型拆分到多个文件时，relationship() 的字符串引用虽可绕过运行时导入依赖，但类型检查器（如 mypy）仍会因正向引用报错；通过 TYPE_CHECKING 条件导入可完美兼顾类型安全与模块解耦。
在将 sqlalchemy 模型拆分到多个文件时，`relationship()` 的字符串引用虽可绕过运行时导入依赖，但类型检查器（如 mypy）仍会因正向引用报错；通过 `type_checking` 条件导入可完美兼顾类型安全与模块解耦。
当项目规模增长，将 Parent 和 Child 模型分别放在 models/parent.py 和 models/child.py 中是常见且推荐的做法。但直接使用字符串形式的 relationship("Child") 会导致类型注解失效——例如 children: Mapped[list[Child]] 中的 Child 在当前模块未定义，mypy 会报 Name 'Child' is not defined。
正确解法：利用 typing.TYPE_CHECKING 进行仅类型检查时的导入
该方案不改变运行时行为（无真实导入开销），仅在静态类型检查阶段提供符号解析支持：
# models/parent.py
from __future__ import annotations
from typing import TYPE_CHECKING
from sqlalchemy.orm import Mapped, mapped_column, relationship
from sqlalchemy import String, ForeignKey
from database import Base
if TYPE_CHECKING:
from .child import Child # 仅类型检查时生效，运行时不执行
class Parent(Base):
__tablename__ = "parent"
id: Mapped[str] = mapped_column(String(32), primary_key=True)
# 其他字段...
children: Mapped[list[Child]] = relationship(
"Child", # 运行时仍用字符串引用，确保无循环导入
back_populates="parent",
cascade="all, delete-orphan"
)# models/child.py
from __future__ import annotations
from typing import TYPE_CHECKING
from sqlalchemy.orm import Mapped, mapped_column, relationship
from sqlalchemy import String, ForeignKey
from database import Base
if TYPE_CHECKING:
from .parent import Parent # 同理，仅用于类型推导
class Child(Base):
__tablename__ = "child"
id: Mapped[str] = mapped_column(String(32), primary_key=True)
parent_id: Mapped[str | None] = mapped_column(
String(32),
ForeignKey("parent.id", name="parent_id_fk", ondelete="CASCADE"),
nullable=True
)
parent: Mapped[Parent | None] = relationship(
"Parent",
back_populates="children"
)✅ 关键优势：
- 运行时零开销：TYPE_CHECKING 为 False，if 块被完全忽略；
- 类型检查完整：mypy、PyCharm 等工具能正确识别 Child 和 Parent 类型，支持跳转、补全与类型推导；
- 兼容 SQLAlchemy 2.0+ 推荐模式（Mapped[] + 字符串关系名）；
- 无需 from __future__ import annotations 外的额外配置（Python ≥ 3.7 已默认启用 postponed evaluation）。
⚠️ 注意事项：
- 切勿在 TYPE_CHECKING 块外进行模型类的直接导入（如 from .child import Child），否则将触发真实循环导入；
- 若使用 Pydantic v2 模型集成 SQLAlchemy，需额外注意 model_config = {"arbitrary_types_allowed": True} 等兼容配置；
- back_populates 的字段名必须严格匹配对方模型中定义的属性名（区分大小写），否则运行时关系无法双向同步。
通过这一模式，你既能享受模块化架构的可维护性，又能保留完整的类型安全和 IDE 支持，是现代 SQLAlchemy 项目工程化的标准实践。
