1 min read · 202 words
在基于 FastAPI 的 Web 应用中，如果调用特定 API 时突然遇到 FastAPI 404 错误，确实挺让人头疼。今天分享一次我自己的排错经历：在清理模块时，我不小心误删了路由文件，最后从归档目录中找回并快速恢复。
问题背景
当时我正准备让索引标签页（Index tab）中的 inspector card 正常展示 inspector state。结果界面上啥也没出来，直接报了一个 FastAPI 404 错误，当场翻车。
故障现象
在进行 Chrome MCP visual sweep 时，我发现 `/api/inspector/state` 接口直接返回了 404。索引卡片上赫然写着：`加载 Inspector 状态失败：inspector state HTTP 404`。由于我们内部的 smoke-test 自动化冒烟测试脚本里没把 inspector 加进目标列表，导致没能提前拦截到这个 Bug。
运行环境
标准的 FastAPI Web 应用。前阵子刚做过一次 `sess140` 模块的清理（prune）工作，把一些废弃文件移到了 `_archive/sess140-prune/` 归档目录下。
尝试过的无效方法
起初以为是某种玄学临时故障，随手重启了 Web 服务（webapp restart）。然而 404 依旧，毫无卵用。
解决方案与根因分析
排查后找到了根本原因：在之前的 `sess140` 模块清理过程中，我不小心把 `webapp/routers/inspector.py` 和 `webapp/seo/inspector.py` 这两个模块也一起打包扔进归档目录了。
奇妙的是，因为有 `_NullModule` stub（桩模块）的存在，FastAPI 启动时并没有报错，路由对象依然存在，只是里面绑定的实际路由数量（routes）变成了 0，所以访问时直接报 404。我把这两个文件从归档目录拷回原位，问题瞬间解决。
这波属于是清理无用代码时用力过猛，把核心器官给切了。好在有备份归档的习惯，不然真的要当场重写。以后删代码真的得三思，归档机制诚不欺我。
恢复命令
从归档目录中找回误删的 inspector 模块，执行以下命令：
# 从归档中恢复丢失的 inspector 模块
cp _archive/sess140-prune/inspector.py webapp/routers/
cp _archive/sess140-prune/seo/inspector.py webapp/seo/验证结果
文件恢复后，重启 Web 服务进行验证。再次请求 `/api/inspector/state`，成功返回 HTTP 200。此时 `router.routes` 数量恢复为 6 个端点，索引标签页的卡片也正常展示数据。故障状态：已修复（Fixed）。
写在最后
如果你的 FastAPI 项目某些接口突然报 404，先别慌，优先排查最近有没有做过代码清理或重构。特别是要注意有没有空路由壳子的 stub 模块在“装死”空转，这是快速定位 FastAPI 404 错误的一个绝佳切入点。
Category Coverage Notice
This article follows our label-specific editorial criteria. Details: