Python 循环导入是什么？为什么会出现 partially initialized module？

简化版

循环导入是两个或多个模块在导入阶段互相依赖，导致其中一个模块还没初始化完就被另一个模块访问。典型报错是 partially initialized module，本质是模块对象已经放进 sys.modules，但里面的类、函数或变量还没执行到定义位置。

Python 第一次导入模块时，会创建模块对象、放入 sys.modules，再执行模块顶层代码。如果 a.py 顶层导入 b.py，b.py 顶层又导入 a.py，第二次拿到的可能是尚未执行完的 a 模块。此时访问 a.User 之类名字，就可能发现它还不存在。

解决方式不是简单把所有 import 移到函数里，而是先判断依赖关系是否合理。常见做法包括：抽出公共模块、延迟导入、只在类型检查时导入、把副作用从模块顶层移到函数里、用依赖注入或接口层降低双向依赖。

面试回答要讲清三点：循环导入发生在模块初始化阶段；sys.modules 缓存让半初始化模块可见；根治要调整模块依赖方向，而不是到处局部 import。

Python 的 import 有缓存机制，同一个模块通常不会被重复执行很多次。循环导入的问题不在重复，而在“模块第一次执行还没完成时，被别人提前拿来用”。这会让某些名字还没绑定，访问时就报错。

a.py 开始执行
  -> import b
       b.py 开始执行
         -> import a
              拿到半初始化的 a
         -> 访问 a.User，失败

如果 a.User 的定义在 import b 之后，那么 b 看到的 a 里确实还没有 User。这就是 partially initialized module 的核心。

导入模块可以简化成四步：查找模块、创建模块对象、放入 sys.modules、执行模块顶层代码。第三步发生在顶层代码执行完成之前，是为了避免递归导入无限创建模块对象。

find spec
  |
create module object
  |
sys.modules["a"] = module
  |
execute a.py top-level code

这个设计本身合理，但它意味着别人可能从 sys.modules 取到正在初始化的模块。假设 a.py 有 100 行，第 10 行导入 b，第 80 行才定义 User，那么 b 在导入期间访问 a.User 就会失败。

# models.py
from services import create_default_profile

class User:
    pass

# services.py
from models import User

def create_default_profile(user: User):
    ...

models 需要 services，services 又需要 models.User，依赖方向打成了环。更糟的是它们都在模块顶层导入，导入时就触发对方初始化。

models -> services -> models

这个问题在 Django、FastAPI 项目里很常见，尤其是 models、schemas、services、routers 之间互相导入时。

最好的修复通常是让依赖变成单向。公共类型放到更底层模块，业务服务依赖模型，路由依赖服务，但模型不要反过来依赖服务。这样层次清楚，导入也稳定。

bad:
models <-> services

better:
types/common
   ↑
models <- services <- routers

真正好的修复是让依赖方向变清楚；局部 import 只是止血，不一定治病。

把 import 放进函数里可以推迟导入发生的时间，绕开初始化阶段的互相访问。这在某些场景合理，比如只在某个分支使用重依赖，或为了避免类型标注引入运行时依赖。

def handle_user(user_id: int):
    from services import load_user
    return load_user(user_id)

但如果很多函数里都靠局部 import 才能工作，通常说明模块边界已经乱了。延迟导入还可能让错误从启动期推迟到运行期，线上某个冷门分支第一次执行才报错。

很多循环导入只是为了类型标注。可以使用 typing.TYPE_CHECKING 和字符串注解，让类型检查器看到类型，但运行时不执行导入。

from typing import TYPE_CHECKING

if TYPE_CHECKING:
    from models import User

def notify(user: "User") -> None:
    ...

在 Python 新版本里，注解求值策略和 from __future__ import annotations 也能帮助减少运行时导入压力。面试里不需要背版本细节，但要知道“类型需要”和“运行时需要”可以分开。

误区：循环导入就是 Python import 缓存坏了。 不是，缓存正常工作；问题是拿到了尚未执行完成的模块。
误区：把 import 全部放函数里就是最佳实践。 局部导入能止血，但长期应调整模块边界和依赖方向。
误区：只要报循环导入，就是两个文件不能互相引用。 类型标注、运行时调用、模块顶层副作用要分开分析。
追问：为什么会出现 partially initialized module？ 模块已放入 sys.modules，但顶层代码未执行到目标名字定义处。
追问：Django 项目里 models 和 services 循环导入怎么办？ 让 services 依赖 models，models 不依赖 services；公共逻辑抽到更底层。
追问：类型注解导致循环导入怎么处理？ 用 TYPE_CHECKING、字符串注解或 future annotations。
追问：循环导入一定会报错吗？ 不一定；如果访问发生在双方初始化完成之后，可能暂时不报，但依赖仍然脆弱。

循环导入要记成“初始化没完就被拿来用”。Python 为了防止递归导入，会先把模块放进 sys.modules，这让半初始化模块可见；真正危险的是顶层互相访问还没定义的名字。排查时画依赖箭头，看谁在顶层 import 谁，再优先拆公共模块和调整依赖方向，最后才考虑局部 import 止血。