循环导入是 Python 模块化编程中一个经典且隐蔽的坑。简单理解就是：两个或多个模块互相 import 对方，导致导入过程中某个模块拿到的是一个尚未完全初始化的对象，从而引发难以排查的错误。
产生原因
Python 的 import 流程大致是：解释器先在 sys.modules 里查该模块是否已经加载过，如果没有，就创建一个空模块对象放到 sys.modules 里，然后逐行执行模块代码。
当模块 A 中 import B，而模块 B 又 import A（或间接地 A → B → C → A），就形成了循环引用。此时：
- A 开始加载，解释器创建一个半成品的
module A放入sys.modules。 - 执行到
import B时，转去加载 B。 - B 中又遇到
import A，解释器发现sys.modules中已有 A（虽然还没执行完），便直接把那个未完全初始化的 A 返回给 B 使用。 - B 继续执行，它尝试访问 A 中的某个变量或函数，但此时 A 的代码可能还没执行到那一步，于是抛出
AttributeError: partially initialized module之类的错误。
实例化问题
# a.py
import b
def func_a():
print("a")
X = "x in a"
# b.py
import a
def func_b():
a.func_a()
print(a.X) # 可能报错：module 'a' has no attribute 'X'运行 python a.py 时，b.py 中 print(a.X) 会失败，因为 import b 触发 b 的加载，b 转而 import a，拿到了当时还未执行到 X = "x in a" 的半成品 a。
运行结果
- 立即报错：在循环导入的模块顶级代码中直接访问对方属性时，通常抛出
AttributeError。 - 延迟暴露：如果循环导入只在函数内部引用（函数定义时可以存在，调用时才执行），程序可能正常启动，但实际调用时才会出错，问题更隐蔽。
- 部分成功：有时循环导入只涉及不被立即使用的符号，程序能正常运行，但这属于危险的不健壮行为。
解决方案
- 打破循环依赖（最佳方案）
- 将两个模块共同依赖的代码提取到第三个模块（如
common.py），让 A 和 B 分别导入它，不再互相引用。 - 检查设计是否合理：循环导入常常是职责划分不清晰的信号。A 需要 B，B 又需要 A，说明它们可能耦合过紧，可以合并或重构。
- 延迟导入
把 import 语句移到函数内部，只在真正需要时再执行：
# a.py
def func_a():
import b # 延迟到函数调用时才导入
b.something()
这样模块顶层代码执行时不会触发循环导入，缺点是可读性下降，且每次调用都会判断是否已导入（性能影响极小）。
- 导入模块而非从模块导入名字
如果确实无法拆分，可以改用 import a 而非 from a import X，在模块内部通过 a.X 的方式访问。因为 import a 只是拿到模块对象，访问属性是运行时行为，能在模块完全初始化后正确获取。
# b.py
import a # 而不是 from a import X
def func():
print(a.X) # 此时a一般已完整初始化
注意这种方式仍要确保访问时机在模块完成初始化之后。
- 使用
init.py控制包级导出
对于包内的循环引用，可以在 init.py 中统一导入，确保初始化顺序可控。
实践建议
- 保持模块依赖关系清晰，尽量形成单向依赖树。
- 如果发现两个模块互相需要对方的功能，考虑是否应该合并或提取共享逻辑。
- 代码评审时警惕任何“A 导入 B 且 B 导入 A”的迹象，即使现在没出错，未来也可能变成定时炸弹。
循环导入的本质是 Python 导入机制的非原子性：模块被导入时是“先占位，再填充”。理解这一点后，就能有意识地避免这种半成品引用带来的陷阱。