这是典型的循环导入崩溃信号，源于模块顶层代码中相互引用未完成初始化的符号，可通过延迟导入、TYPE_CHECKING类型注解或拆分公共模块解决。
为什么import一执行就报ImportError: cannot import name 'X' from partially initialized module
这是典型的循环导入崩溃信号——不是语法错，而是模块加载中途被截断。Python解释器在解析A.py时遇到from B import Y，转头去加载B.py，结果B.py里又写了from A import Z，此时A还没初始化完，名字Z自然不存在。
关键点在于：循环导入本身不必然崩溃，只有在模块顶层代码（非函数/类内部）直接访问对方未完成初始化的符号时才触发。
- 把相互依赖的
import挪进函数或方法体内，延迟到实际调用时才解析 - 用字符串形式的
from typing import TYPE_CHECKING+if TYPE_CHECKING:块做类型提示，避免运行时导入 - 检查
__init__.py是否无意中触发了提前加载链（比如在里面写了from .a import X和from .b import Y）
用TYPE_CHECKING做类型注解而不触发运行时导入
PyCharm或mypy能识别TYPE_CHECKING常量，但解释器在运行时不执行其内部代码。这是解耦类型提示与运行逻辑最轻量的方式。
# a.py from typing import TYPE_CHECKING <p>if TYPE_CHECKING: from b import BClass # 这行不会在运行时执行</p><p>class AClass: def method(self, obj: 'BClass') -> None: # 字符串注解绕过运行时解析 pass
注意：必须用字符串'BClass'，不能写BClass，否则仍会尝试解析。
立即学习“Python免费学习笔记（深入）”；
- 所有跨模块类型注解都应走这条路，尤其DTO、Schema、Model类之间互相引用时
-
TYPE_CHECKING块里禁止出现任何运行时逻辑（如赋值、函数调用） - 如果用了
from __future__ import annotations（Python 3.7+），连字符串都可以省略，但需确保所有依赖模块已安装且可被静态分析器发现
把import放进函数里是最直接的修复手段
只要不发生在模块顶层，Python就不会在导入阶段尝试解析。适用于工具函数、回调、工厂方法等场景。
# b.py
def create_a_instance():
from a import AClass # 延迟到函数调用时才导入
return AClass()
<p>def process_data(data):
from a import helper_func # 每次调用都重新导入？不，CPython会缓存，实际只加载一次
return helper_func(data)
这种写法看似“不优雅”，但在快速修复线上崩溃时最可靠。
- 不要在类的
__init__或@property里无条件导入，可能引发不可预知的初始化顺序问题 - 若函数被高频调用，导入开销可忽略——模块对象存在
sys.modules缓存中 - 避免在循环体或递归函数里重复导入，虽然安全但冗余
重构为三层结构：抽离公共依赖到独立模块
当A和B都依赖同一组数据结构、配置或基础函数时，硬绑在一起不如拆出core或shared模块。
例如原本：
# a.py → imports b.py # b.py → imports a.py
改为：
# shared.py
class DataModel:
pass
<h1>a.py</h1><p>from shared import DataModel</p><h1>b.py</h1><p>from shared import DataModel
这不是“银弹”，但凡两个模块共享状态、共用配置、或共同操作同一类对象，就该怀疑它们本就不该是平级关系。
- 优先移动
class、Enum、TypedDict这类纯声明；函数若无副作用也可移 - 别为了拆而拆——如果
A只用B的一个工具函数，直接把它复制进A比加一层间接更干净 - 警惕
shared变成垃圾场：它不该包含业务逻辑，也不该有环境相关代码（如os.getenv）
真正卡住人的往往不是技术方案，而是分不清“这里需要类型提示”和“这里真要运行时拿到对象”。改完之后跑一遍单元测试，再重点看日志里有没有新的ImportError或AttributeError——有时候修复一个循环，会暴露下一个隐藏更深的初始化顺序bug。
