循环导入报错本质是模块职责不清，应通过拆分共享模块、延迟导入、字符串化类型引用及精简__init__.py来解决，而非调整import顺序。
循环导入报错时，先别急着改 import 顺序
Python 的循环导入（ImportError 或 ModuleNotFoundError）往往不是 import 写错了，而是模块职责没理清。比如 A.py 导入 B.py，而 B.py 又在模块顶层直接导入 A.py 中的函数——这时解释器卡在加载中途，必然失败。
常见错误现象：ImportError: cannot import name 'X' from partially initialized module 'A'。这不是路径问题，也不是 Python 版本问题，是执行流被卡住了。
- 优先检查报错堆栈里最上面那个
import行，看它是否在模块顶层（非函数/类内部）触发了反向依赖 - 把被依赖方（比如
A.py中被B.py需要的函数）抽到一个新模块shared.py，让双方都只导入它 - 如果只是某个函数要用，把
import移到函数体内（延迟导入），例如在B.py的某个函数里写from A import some_util，而不是放在文件开头 - 避免在
__init__.py里做跨模块的顶层导入，这里最容易埋雷
用 from ... import ... 时特别容易触发循环依赖
from A import func_a 比 import A 更危险：前者要求 A 必须完全加载完毕才能取到 func_a，而后者只要模块对象存在就能继续（哪怕里面的内容还没初始化完）。
使用场景：当你在 B.py 里写 from A import helper，同时 A.py 里又有 from B import config，就几乎必现循环。
立即学习“Python免费学习笔记（深入）”；
- 把
from X import Y全部替换成import X，然后用X.Y访问，能绕过大部分顶层加载冲突 - 如果必须用
from形式（比如为了类型提示或 IDE 补全），确保被导入项不依赖当前模块的任何运行时状态 - 注意
from . import xxx这种相对导入，在包结构变化时可能悄无声息地变成循环
Pydantic / Django / FastAPI 项目里，模型层循环依赖高发
这类框架常把数据模型分散在多个文件（models/user.py、models/order.py），又互相引用字段或验证逻辑，很容易在启动时崩掉。
性能影响：循环依赖本身不拖慢运行时，但会让热重载失败、测试启动变慢、mypy 类型检查卡住。
- 用字符串形式的模型引用替代实际导入，例如 Pydantic 中写
user_id: Optional["User"] = None，配合from __future__ import annotations - Django 里外键字段用
"app_name.ModelName"字符串写法，而不是直接导入类 - FastAPI 的
response_model参数也支持字符串，如response_model="schemas.UserOut"（需配合from fastapi import routing等机制） - 别在
__post_init__或model_validator里调用另一个尚未加载完成的模型方法
CI 和本地行为不一致？检查 __init__.py 里的隐式导入
有些项目在 models/__init__.py 里一口气把所有子模块 import 进来，方便外部写 from models import User。但这会强制提前加载全部模型，把潜在的循环依赖提前暴露出来——而你本地可能因为 import 顺序巧合没触发，CI 却稳稳报错。
兼容性影响：不同 Python 版本对模块加载顺序的细微差异，会让这种“侥幸通过”的代码在升级后突然失效。
- 删掉
__init__.py里那些“图方便”的批量导入，只留真正需要对外暴露的符号 - 用
__all__ = ["User", "Order"]显式控制导出，避免无意中拉起一整条依赖链 - 在 CI 的 Python 启动参数里加
-v（verbose），看模块加载顺序，快速定位哪个__init__.py是罪魁祸首
真正麻烦的从来不是怎么绕过循环依赖，而是某个看似无害的 from utils import log 被悄悄塞进了三个不同包的 __init__.py 里，最后在上线前五分钟才爆出来。
