Python — ImportError: cannot import name（模块部分初始化）

症状

　　现代 Python 直接在报错信息里点名罪行：ImportError: cannot import name ‘User’ from partially initialized module ‘app.models’ (most likely due to a circular import)。把回溯自底向上读成一条导入链，每个 import 帧是一跳，出现两次的模块就是环节点。决定性实验是顺序敏感性：先导入某一侧一切正常，先导入另一侧立刻报错。这种不对称的根源是 sys.modules 在模块体执行完之前就登记了条目，第二次遍历才发现名字缺失。启动时即失败、先于任何请求，是导入期问题的标志。

诊断思路

　　先从回溯提取导入链找到重复模块与失败行；再用两个方向的导入命令复现顺序敏感性并确定环的方向；最后用 pydeps 渲染导入图，让环路可见并评估哪条边删起来最便宜。常见成因：models 与 schemas 互导、模块顶层类型注解互相引用、包 init.py 急切导入互相依赖的子模块、重构时把函数内导入挪到了模块顶层从而闭合了环。

根因

　　Python 在首次导入时执行模块体，并在执行完成之前就把它注册进 sys.modules。环里那个执行到一半的模块已经在 sys.modules 中，反向导入作为对象能成功，但其上还没有被请求的名字，于是产生部分初始化的 ImportError。

修复与验证

　　选择最便宜的边切断：通常是把共享名字抽成双方都导入的叶子模块；只有单个函数需要反向引用时，把 import 移进函数体做延迟导入；仅用于类型注解的引用，用 from future import annotations 加 TYPE_CHECKING 块彻底移出运行时。绝不要用 try/except ImportError 包住失败的导入——那会把结构性错误换成延迟到运行时的 None 属性错误，调试难度直线上升。验证时在干净解释器里导入每个入口（服务器、CLI、任务），零 ImportError；每个入口再反向跑一遍确认与顺序无关；最后把 pydeps 环检测加进 CI，让重新闭合环路的重构在评审前失败。

代码示例

ImportError: cannot import name 'User' from partially initialized
module 'app.models' (most likely due to a circular import)
(most likely due to a circular import)

app/models/base.py   <- leaf: shared classes and constants
app/models/user.py   <- imports base
app/schemas.py        <- imports base

# app/schemas.py
def render_user(user):
    from app.models import User   # resolved at call time
    return User.__name__ + ':' + user.id

# app/schemas.py
from __future__ import annotations
from typing import TYPE_CHECKING

if TYPE_CHECKING:
    from app.models import User

def serialize(u: 'User') -> dict: ...