用 AST 提前发现 FastAPI 循环导入
文章以路由、认证服务和 CRUD 模块相互引用导致部署启动失败为例,解释循环导入的形成过程。提出通过 AST 静态分析,在提交检查或 CI 阶段提前发现依赖环。
AI 深度解读
FastAPI 项目里的循环导入,常常要等应用启动时才暴露。作者提出的办法是:先用 Python 的 AST 扫描模块依赖,再检查依赖图有没有环,把原本发生在 QA 部署阶段的错误提前到提交或合并阶段。
这个方向值得借鉴,但原文展示的实现还不能直接充当可靠的 CI 检查器。它没有给出完整的环检测代码,相对导入解析也存在边界问题。读这篇的重点,是理解检查思路,以及上线前还缺哪些验证。
Depends 报错,为什么要先检查模块导入
作者遇到的故障发生在 QA 部署流水线:Python 提示,无法从尚未完成初始化的 app.services.auth 模块中导入 get_current_user。
依赖关系绕了一圈:
app.routers.users → app.services.auth → app.crud.user → app.routers.users
其中,用户路由通过 FastAPI 的 Depends 引用认证函数,认证模块又引用用户 CRUD 模块,后者反过来引用路由模块里的符号。Python 沿着这条路径加载模块,走回起点时,起点还没有初始化完成,于是报错。
这里需要分清两个层次:Depends 管理的是请求处理过程中如何提供依赖;这次异常发生在 Python 加载模块时。依赖注入让这条引用关系更容易出现,但原文实际处理的是模块循环导入。
作者说,他们的项目增长到数万行后遇到了这个问题,局部单元测试没有提前发现,直到测试容器启动才失败。这是作者报告的个案,不能推导成「循环导入只会在 CI 出现」。本地只要按相同路径启动应用,也可能复现。
有用的改进,是把模块结构检查提前,而不是等容器启动替你发现问题。
AST 能画出依赖图,但 Depends 标记还不够
AST(抽象语法树)可以把源代码转换成程序能够遍历的结构。扫描器因此能识别 import、from ... import ... 和函数调用,不需要实际导入业务模块。
作者计划把每个模块作为节点,把导入关系作为有向边,构建邻接表,再用深度优先搜索(DFS)找环。期望的结果是一张有向无环图(DAG):沿着模块依赖一路走,不会回到已经经过的模块。
原文的访问器 FastAPIModuleVisitor 做了三件事:
visit_Import收集直接导入的模块名。visit_ImportFrom收集from导入,并尝试解析相对路径。visit_Call识别名为Depends的调用,记录has_depends。
最后一点容易被标题放大。代码只判断调用名是不是 Depends,或者属性名是不是 Depends,没有解析传入的 callable,也没有建立函数之间的依赖图。它还可能漏掉别名调用,或把其他对象的同名方法算进去。
因此,这是一份模块导入扫描器的雏形,附带 FastAPI 使用标记。它尚未展示完整的依赖注入分析能力。
报告结构使用 Pydantic v2,包含 total_files_analyzed、circular_dependencies 和 dependency_graph,序列化使用 orjson。不过,使用 Pydantic v2 并不自动等于启用了严格模式,原文没有展示相应配置。
更关键的是,公开代码到 visitor.visit(tree) 就结束了。把扫描结果写入图、筛选内部模块、执行 DFS、生成 JSON 和命令行入口,都没有出现。虽然作者表示完整 ZIP 可以在 Gumroad 以 $0+ 获取,但仅凭正文无法验证完整实现。
相对导入和扫描根目录,决定图能不能连对
作者把相对导入视为实现难点,这是合理的。from .models import ... 里的 models 不是全项目唯一标识,必须结合当前位置还原成完整模块路径,否则不同包里的同名模块会混在一起。
下面是原文用于处理相对导入的代码,它尝试根据 node.level 计算需要保留的路径段:
if node.level > 0:
parts = self.current_module.split('.')
target_len = len(parts) - node.level
if target_len >= 0:
prefix = '.'.join(parts[:target_len])
resolved = f"{prefix}.{node.module}" if prefix else node.module
self.imported_modules.add(resolved)
else:
self.imported_modules.add(node.module)
要重点看 target_len = len(parts) - node.level:这个公式依赖 current_module 如何定义,不能脱离文件类型判断正确性。
对普通文件,例如 app.routers.v1.users,去掉最后的模块名后解析一级相对导入,这个思路可以成立。但原文的 _file_to_module_path 会移除路径末尾的 __init__。包初始化文件已经被表示成包名,再套同一套截取逻辑,就可能多退一级。
还有两个遗漏。第一,外层只有在 node.module 存在时才处理,from . import models 这类语句会被跳过。第二,from app import services 只收集 app,没有进一步判断 services 是否对应子模块,可能漏掉实际依赖边。
扫描根目录也必须统一。原文的 CI 命令扫描 ./app,模块名又按相对于扫描根目录的路径生成,于是 app/routers/users.py 会成为 routers.users;源码中的绝对导入却可能仍是 app.services.auth。两边名称不一致,图就接不上。
所以,「准确解析相对导入」是目标,原文片段还不足以证明已经实现。尤其不能把「没有检测到环」直接当作架构健康的证据。
我的判断
我赞成把循环依赖检查放进 pre-commit 或合并门禁。它能为团队提供结构反馈,也能暴露「路由依赖服务,底层模块又反向依赖路由」这类值得拆解的关系。
但作者把函数内延迟导入一概视为掩盖问题,判断偏绝对。局部导入可以用于解决加载时机问题;如果模块职责已经纠缠,它又确实可能只是推迟故障。应该结合依赖方向判断,而不是只看导入语句放在哪里。
静态扫描同样有取舍。访问器会遍历函数体和条件分支,收集到的边不一定都在同一次启动中执行;动态导入又可能逃过扫描。要求所有源码依赖都组成 DAG,可以是一项团队架构规则,但不等于精确模拟 Python 的运行过程。
原文还用 except Exception: continue 跳过读取或解析失败的文件。作为 CI 门禁,这会让未完成的扫描看起来像检查通过,应当显式报告失败文件。
这篇提供了可用的工程方向,没有提供足以直接背书的完整工具和效果数据。
作者没有给出检测准确率、漏报率、扫描耗时,也没有与其他方案做对照。文末关于多 Agent 协作降低约 90.0% 能耗和 token 开销的宣传,没有展示实验方法,与循环导入检查的有效性也没有建立联系。
能拿来做什么
- 如果你维护 FastAPI 服务,可以先审查路由、服务、CRUD 的依赖方向,把底层需要的类型、常量或协议移到独立模块,再引入自动检查,让规则有明确的结构依据。
- 如果准备采用这份 AST 思路,先验证普通模块、
__init__.py、from . import models和绝对导入,确保它们都能映射到同一套模块名称,并让解析失败显式退出。 - 如果让 AI 帮你补全扫描器,要明确要求交付 DFS、内部依赖过滤、CLI、JSON 输出和失败退出码,再用一组已知有环与无环的样例验证,不能把原文片段直接当成完整实现。
- 接入 GitHub Actions 时,可以参考原文的报告检查方式,但前提是
analyze_deps.py已经完整实现,并且扫描根目录与包名规则一致:
- name: Check Circular Dependencies
run: |
python scripts/analyze_deps.py ./app > report.json
python -c "
import orjson, sys
data = orjson.loads(open('report.json').read())
if data['circular_dependencies']:
print(f'Error: Circular dependencies detected: {data[\"circular_dependencies\"]}')
sys.exit(1)
print('Dependency check passed.')
"
这里决定门禁结果的是 sys.exit(1);不过,只有前面的扫描完整且依赖边正确,空的 circular_dependencies 才有参考价值。