在FastAPI启动阶段检查依赖环
文章介绍一项启动检查实验,遍历 FastAPI 路由的依赖关系,用 NetworkX 构建有向图,再通过拓扑排序或环检测定位循环引用。
AI 深度解读
FastAPI 的项目拆出多个 router 后,循环依赖常在启动或后期测试时才暴露。作者做了一个实验:启动时遍历路由,把 Depends() 关系画成有向图,在接收请求前找出闭环。脚本在隔离的单元测试里能找出环,接入 CI/CD 后却遇到了缺包退出和框架内部接口耦合的问题。
这篇工程记录最值得带走的是检查时机的取舍。模块之间互相导入,和依赖函数之间互相调用,是两类要分别检查的问题。把它们混在一起,很容易装了工具、加了门禁,真遇到故障时却查错了图。
启动时建图,能抓住哪一种环?
作者用 networkx 的 DiGraph 表示 FastAPI 的依赖关系。每个依赖函数是一个节点,A 通过 Depends() 依赖 B,就画一条从 A 指向 B 的边。沿着边走一圈回到 A,说明这条依赖链形成了闭环。拓扑排序可以判断图能否排出无环的依赖顺序,simple_cycles() 则能给出具体的环路,方便定位是哪几段依赖连了回来。
原文的时序图展示了校验器如何从 APIRoute 收集依赖,再把环路整理成报告。
sequenceDiagram
participant App as FastAPI Application
participant Val as DependencyValidator
participant Graph as NetworkX (DiGraph)
App->>Val: Pass startup instance
Val->>Val: Traverse all routes (APIRoute)
loop Dependencies for each route
Val->>Graph: Add dependency function as node
Val->>Graph: Connect Depends() relationship as edge
end
Val->>Graph: Detect cycles via simple_cycles()
Graph-->>Val: Detected cycle paths
Val-->>App: Generate validation report
最后一行只画到了生成校验报告。原文没有交代发现环后是记录告警还是阻止应用启动。整个方案还要求应用先走到执行校验器的阶段。如果模块导入或路由构建已经失败,启动钩子里的检查就没有机会运行。
为什么单测能跑,接入流水线却卡住了?
第一个问题出在缺包处理。作者预判环境里可能没有 networkx 或 orjson,就在校验脚本顶层加了 try-except。自动化 QA 环境缺少这些包时,进程以 Exit Code 1 退出。此时连建图都还没开始,失败来自导入时的退出逻辑。把依赖声明放进 pyproject.toml 或 requirements.txt,并在 CI 安装阶段或 Dockerfile 构建阶段处理,流水线就能在对应步骤报告缺包。
第二个问题是校验器要读取 FastAPI 内部的 dependant 属性和 dependencies 列表。作者指出,这些结构缺少稳定公开 API 的保证。将来框架一升级,校验器可能直接报错,也可能漏读依赖关系。原文没有给出测试所用的 FastAPI 版本、兼容范围或启动耗时,所以能确认的是脚本在隔离用例里检出了预期的环,以及缺包时出现了退出问题。升级风险和启动成本没有实测数据。
先把 router 之间的依赖方向理顺
作者建议把多个 router 共用的依赖函数抽到独立的 services 模块,让 router 调用 services。只要 services 又去导入 router,原来的依赖方向就会被拉回来,单纯搬文件也消不了环。把方向定下来之后,可以在 CI 里用 pydeps 排查导入图里的环,或用 import-linter 约束哪些模块可以依赖哪些模块。
作者还建议用 Protocol 抽象出调用方需要的接口。落到 FastAPI 里,接口负责描述类型,Depends() 仍需要明确由哪个可调用对象提供依赖。如果提供者的实现仍反向导入 router,给参数加上 Protocol 也消不掉这条边。
我的判断
我认同先梳理模块边界,再决定要不要加启动校验。CI 里的导入图检查适合查跨层引用,启动建图看的是 FastAPI 已经构建出来的依赖关系,两者覆盖范围不同。原文把 mypy、pylint 和导入图分析一道提及,但没有给出规则或配置,不能据此认为打开常规类型检查就能查出 Depends() 的环。
作者把运行时方案评为「不完整」,有缺包退出和内部接口耦合作为依据。至于静态方案是否更快、能否覆盖他们项目里遇到的环,原文没有对照数据,这部分是经验判断。如果团队的问题集中在 router 互相导入,先做模块约束就有明确收益。只有当常规检查覆盖不到实际的依赖装配问题,额外维护一套启动校验才有更清楚的理由。
能拿来做什么
- FastAPI 启动失败时,先从堆栈确认卡在模块导入、路由构建还是依赖解析,再选对应的图来查。
- 两个 router 开始共享鉴权或查询依赖时,把共用函数提到独立模块,并给 CI 加一条禁止 services 导入 router 的规则。
- 如果团队确实需要检查
Depends()的环,先把建图校验放进独立测试,用一个已知有环的用例确认报告能指出闭环路径,再决定要不要接进应用启动流程。