APIRouter模块化是FastAPI中大型项目的必备结构基础，必须统一命名router、控制目录深度、严格分离职责、正确使用prefix/tags/responses及模块级dependencies，避免上帝文件与维护灾难。
直接用 APIRouter 拆分路由模块是 FastAPI 工程化的标准做法，不是“可选技巧”，而是中大型项目必须落地的结构基础。不拆分，main.py 很快会变成难以定位、不敢修改的“上帝文件”。
怎么组织 routers/ 目录结构才不会踩坑
结构松散或命名随意会导致导入失败、前缀冲突、文档分类混乱。关键不是“能不能跑”，而是“后续加 20 个模块时还好不好维护”：
- 每个模块文件（如
users.py、orders.py）必须定义且仅定义一个APIRouter实例，推荐统一命名为router，避免user_router、user_api等混用 - 目录层级不宜过深，
routers/v1/users.py比routers/api/versioned/v1/user_management.py更易维护；版本控制建议用前缀（prefix="/v1"）而非目录嵌套 - 避免在
routers/下放业务逻辑或模型定义，只放路由声明和轻量依赖（如Depends调用），否则模块职责失焦 - 如果模块间有共享路径逻辑（如统一的
/health），不要复制粘贴，抽到shared_routes.py单独管理并复用
include_router() 的 prefix 和 tags 容易被忽略的细节
app.include_router() 不只是挂载，它直接影响生成的 OpenAPI 文档结构和实际请求路径。常见误用是把前缀写错位置或重复拼接：
FastAPI Flask Proxy
下载
FastAPI + Flask 混合部署最佳实践，解决路由定义、API 代理等常见问题，适用于同时运行 FastAPI API 与 Flask 前端的场景。
-
prefix是加在模块内所有路径**前面**的，不是替代模块内写的路径。比如router = APIRouter(prefix="/users")+@router.get("/{id}")→ 实际路径是/users/{id}，不是/users//{id} - 如果主应用已带全局前缀（如
FastAPI(root_path="/api")），include_router(prefix="/v1")会叠加为/api/v1/...，需确认 Nginx 或网关是否适配 -
tags必须是 list 类型（如tags=["users"]），写成字符串tags="users"会导致 Swagger UI 分类失效，且不报错 - 多个模块用了相同
tags（如都写["auth"]），OpenAPI 文档里会合并显示——这有时是预期行为，但若想隔离，就得用不同 tag 名
依赖注入（dependencies）在模块级怎么真正生效
模块级 dependencies 是减少样板代码的关键，但它只对当前 APIRouter 实例下的所有路由生效，不穿透到子模块或主应用：
- 写法必须是
APIRouter(dependencies=[Depends(auth_check)])，不能漏掉方括号，否则类型错误且启动时报TypeError: 'Depends' object is not iterable - 如果某个路由需要绕过模块级依赖（如登录接口本身不该校验 token），得显式覆盖：
@router.post("/login", dependencies=[]) - 模块级依赖里的异常（如
HTTPException(401)）会中断后续路由执行，但不会自动触发全局异常处理器——除非你在依赖函数里主动 raise，或在app.add_exception_handler()中注册对应类型 - 依赖项本身（如
verify_token）应定义在独立文件（如dependencies.py），避免循环导入：模块 A 导入 B，B 又反过来导入 A 的 router
最常被跳过的一步是：没给每个 router 配 responses 参数。404、422 这类通用错误响应一旦在模块里统一声明，就不用每个 @router.get 都重复写 responses={...} ——但这点只有在第一个模块上线后、第二个模块开始复制粘贴时才会意识到代价。
