这是模块导入时序问题：A导入B时，B在顶层导入A中尚未定义的X，导致ImportError。解法包括延迟导入、字符串前向引用、TYPE_CHECKING保护、重构共用模块等。
为什么 ImportError: cannot import name 'X' from 'Y' 总在模块互相引用时出现？
这不是 Python 解释器抽风，而是导入时的执行顺序问题：当模块 A 导入模块 B，而 B 又在顶层（非函数/类内部）尝试导入 A 中尚未执行完的类时，X 还没被定义，就会报这个错。本质是模块加载过程中的“未完成态”被提前访问。
常见诱因包括：
• 两个模块各自在文件顶部 from X import Y 和 from Z import W，且彼此依赖
• 类型提示中写了未运行时可解析的前向引用（如 def foo() -> MyOtherClass:），但没加引号或未启用 from __future__ import annotations
- 优先检查所有
import语句是否都在模块顶层——把它们挪进函数或方法里能立刻绕过问题 - 类型提示中的类名必须用字符串字面量（如
def run(self) -> "SomeClass":），或统一启用from __future__ import annotations（Python 3.7+） - 避免在
__init__.py中做跨模块的类实例化或调用，它容易成为循环导入的放大器
如何用延迟导入（deferred import）安全拆解循环依赖？
把导入动作从模块加载阶段推迟到实际使用时，是最轻量、最可控的解法。关键不是“不导入”，而是“不急着导入”。
- 在函数/方法内部做
import，比如把from models import User从文件顶部移到某个def create_report()函数体内 - 如果必须在类定义中引用另一个模块的类（例如作为属性注解或默认值），改用字符串名称 +
typing.TYPE_CHECKING保护块：
from typing import TYPE_CHECKING <p>if TYPE_CHECKING: from models import User</p><p>class Report: def <strong>init</strong>(self, user: "User") -> None: # 字符串前向引用 self.user = user
注意：TYPE_CHECKING 块里的导入只在 mypy/pyright 等类型检查器中生效，运行时不执行，彻底避开导入时序问题。
华为云 Python SDK 查询工具。自动发现已安装 SDK 的服务包、Client类、API 方法、入参详情、类信息（__init__ 参数、属性、类型、描述），支持关键字搜索，快速定位目标 API 使用方法。
立即学习“Python免费学习笔记（深入）”；
什么时候该重构模块结构而不是硬扛循环导入？
当延迟导入开始蔓延——多个函数里重复写同样的 import，或 TYPE_CHECKING 块越来越多，说明模块职责已经模糊。这时候重构比打补丁更省时间。
- 把共用的数据模型、协议接口、基础异常类提到独立的
core.py或types.py模块，让原模块都依赖它，而非彼此依赖 - 检查是否存在“中介类”：比如
A和B都需要操作Config，就别让A导入B来读配置，而是让两者都导入config.py - 警惕
__init__.py里的聚合式导入（如from .a import X; from .b import Y），它会让外部模块一次导入触发整条链——改为显式导入具体子模块
为什么 importlib.import_module() 不是首选方案？
它确实能动态绕过静态导入检查，但代价明显：失去 IDE 跳转、类型推导和静态分析支持，调试时堆栈也更难读。仅在极少数场景适用，比如插件系统或真正需要运行时决定导入路径。
- 不要用它替代本该清晰的模块划分
- 若真要用，务必加
try/except ImportError并给出明确错误信息，否则失败时只会抛出模糊的ModuleNotFoundError - 永远优先考虑把逻辑下沉到函数内导入，而不是用
importlib包一层“看起来高级”的封装
最常被忽略的是类型检查与运行时的分离意识：mypy 看到的代码结构 ≠ CPython 执行的顺序。守住这个边界，90% 的循环导入问题其实不需要动架构，只需调整两行导入位置和三个引号。
