用 Python ast 与 graphlib 检测循环导入，定位架构腐化点

问题场景

项目模块数量增长后，模块之间容易形成循环导入。循环导入不仅会导致 ImportError，还会让代码难以测试、难以复用，是架构腐化的典型信号。手动排查需要逐个文件阅读 import，效率低且容易遗漏。

解决思路

我们可以写一个小工具，自动完成以下步骤：

1. 遍历项目根目录下所有 .py 文件。
2. 用 Python 标准库 ast 解析每个文件的抽象语法树，提取 Import 和 ImportFrom 节点。
3. 将文件路径映射为模块名，只保留项目内部的模块依赖，构建有向图。
4. 用 graphlib.TopologicalSorter 尝试拓扑排序，若抛出 CycleError 则说明存在循环导入。
5. 用深度优先搜索（DFS）在依赖图中找到一条具体的循环路径并打印。

最小可运行示例

以下脚本不依赖第三方库，保存为 detect_cycles.py 即可使用。需要 Python 3.9 或更高版本（graphlib 从 3.9 开始提供）。

import ast
import sys
from pathlib import Path
from graphlib import TopologicalSorter, CycleError

def module_name_from_path(file_path, root):
    rel = file_path.relative_to(root)
    parts = list(rel.with_suffix('').parts)
    is_package = False
    if parts and parts[-1] == '__init__':
        parts = parts[:-1]
        is_package = True
    return '.'.join(parts) if parts else root.name, is_package

def resolve_relative_import(current_module, is_package, level, module):
    if is_package:
        base_parts = current_module.split('.')
    else:
        base_parts = current_module.split('.')[:-1]
    if level > len(base_parts):
        return None
    prefix = base_parts[:len(base_parts) - level + 1]
    if module:
        return '.'.join(prefix + module.split('.'))
    else:
        return '.'.join(prefix)

def _candidates(name):
    parts = name.split('.')
    for i in range(len(parts), 0, -1):
        yield '.'.join(parts[:i])

def collect_imports(file_path, root, all_modules):
    module_name, is_package = module_name_from_path(file_path, root)
    deps = set()
    try:
        source = file_path.read_text(encoding='utf-8')
        tree = ast.parse(source, filename=str(file_path))
    except (SyntaxError, UnicodeDecodeError) as e:
        print(f'跳过无法解析的文件 {file_path}: {e}', file=sys.stderr)
        return deps

    for node in ast.walk(tree):
        if isinstance(node, ast.Import):
            for alias in node.names:
                name = alias.name
                for candidate in _candidates(name):
                    if candidate in all_modules:
                        deps.add(candidate)
                        break
        elif isinstance(node, ast.ImportFrom):
            if node.level > 0:
                abs_name = resolve_relative_import(module_name, is_package, node.level, node.module)
                if abs_name:
                    for candidate in _candidates(abs_name):
                        if candidate in all_modules:
                            deps.add(candidate)
                            break
            else:
                if node.module:
                    for candidate in _candidates(node.module):
                        if candidate in all_modules:
                            deps.add(candidate)
                            break
    return deps

def build_graph(root):
    py_files = list(root.rglob('*.py'))
    all_modules = set()
    file_to_module = {}
    for f in py_files:
        mod, _ = module_name_from_path(f, root)
        all_modules.add(mod)
        file_to_module[f] = mod

    graph = {mod: set() for mod in all_modules}
    for f in py_files:
        mod = file_to_module[f]
        deps = collect_imports(f, root, all_modules)
        deps.discard(mod)
        graph[mod] = deps
    return graph

def find_cycle(graph):
    WHITE, GRAY, BLACK = 0, 1, 2
    color = {node: WHITE for node in graph}
    parent = {}
    cycle = []

    def dfs(node):
        color[node] = GRAY
        for neighbor in graph.get(node, ()):
            if neighbor not in color:
                continue
            if color[neighbor] == GRAY:
                cycle.append(neighbor)
                cur = node
                while cur != neighbor:
                    cycle.append(cur)
                    cur = parent[cur]
                cycle.append(neighbor)
                cycle.reverse()
                return True
            elif color[neighbor] == WHITE:
                parent[neighbor] = node
                if dfs(neighbor):
                    return True
        color[node] = BLACK
        return False

    for node in graph:
        if color[node] == WHITE:
            if dfs(node):
                return cycle
    return None

def main():
    if len(sys.argv) < 2:
        print('用法: python detect_cycles.py <项目根目录>')
        sys.exit(1)
    root = Path(sys.argv[1]).resolve()
    if not root.is_dir():
        print(f'错误: {root} 不是目录')
        sys.exit(1)

    graph = build_graph(root)
    print(f'扫描到 {len(graph)} 个模块')

    ts = TopologicalSorter(graph)
    try:
        ts.prepare()
        print('未检测到循环导入')
    except CycleError as e:
        print('检测到循环导入！')
        cycle_nodes = e.args[1] if len(e.args) > 1 else None
        if cycle_nodes:
            print(f'环中节点: {cycle_nodes}')
        path = find_cycle(graph)
        if path:
            print('循环路径:')
            print(' -> '.join(path))
        else:
            print('无法自动定位具体路径，请检查依赖图。')

if __name__ == '__main__':
    main()

运行方法

假设项目结构如下：

example_project/
├── main.py
└── pkg/
    ├── __init__.py
    ├── a.py
    └── b.py

其中 a.py 导入 pkg.b，b.py 导入 pkg.a，形成循环。在终端执行：

python detect_cycles.py ./example_project

输出类似：

扫描到 4 个模块
检测到循环导入！
环中节点: ['pkg.a', 'pkg.b']
循环路径:
pkg.a -> pkg.b -> pkg.a

这样就能直接看到循环发生在哪几个模块之间。

边界与限制

• 动态导入无法检测：通过 importlib.import_module()、__import__() 或 exec() 动态加载的模块不会出现在 AST 中，工具无法发现。
• 条件导入可能误报：放在 if TYPE_CHECKING: 或 try/except ImportError 中的导入会被当作真实依赖，可能产生误报。需要结合代码上下文人工确认。
• 相对导入解析有限：脚本按常见包结构解析相对导入，但命名空间包（没有 __init__.py 的目录）或复杂 sys.path 操作可能导致模块名映射不准确。
• 循环导入不一定是错误：有些框架允许在运行时延迟导入，或通过函数内导入打破循环。工具的作用是提示可疑点，而非强制判定为缺陷。
• 性能与规模：AST 解析所有文件需要一定时间，大型项目可能较慢；可以增加文件过滤或缓存，避免重复扫描。
• 版本依赖：graphlib 在 Python 3.9 引入，低版本 Python 需要自行实现拓扑排序或升级解释器。

总结

用 ast 做静态导入分析，再借助 graphlib.TopologicalSorter 检测循环依赖，可以快速绘制项目的模块依赖图并定位架构腐化点。将脚本接入 CI 或代码检查流程，有助于在早期发现模块间的循环引用，保持代码结构清晰。工具本身不复杂，但能为大型项目的架构治理提供实用参考。