很多 FastAPI 教程上来就是一个app FastAPI()然后写几个路由函数完事但真实项目远不止这些。一个可维护的 FastAPI 项目需要考虑应用生命周期管理、路由模块化拆分、多种参数来源的处理路径参数、查询参数、Cookie、Header、请求体以及 Swagger 文档的分组展示。本文带你从零搭建一个结构清晰、可扩展的 FastAPI 工程骨架目录1. 项目结构总览2. 应用入口lifespan 生命周期3. 路由模块化APIRouter 拆分4. 五种参数来源详解5. 路由注册与 Swagger 分组6. 总结1. 项目结构总览先看完整的目录结构心里有个地图web-fastapi/ ├── main.py # 应用入口创建app、注册路由/中间件/异常处理 ├── core/ │ ├── config/pg_config.py # 数据库配置引擎、会话、Base │ ├── po/ # 持久化对象SQLAlchemy ORM模型 │ │ ├── shop.py │ │ └── user.py │ ├── routes/ # 路由层API接口定义 │ │ ├── shop_route.py │ │ └── user_route.py │ └── service/ # 业务逻辑层 │ ├── shop_service.py │ └── user_service.py ├── depends/ # 依赖注入 │ ├── depends.py │ └── depends_route.py ├── exception/ # 异常体系 │ ├── exceptions.py │ ├── exception_handlers.py │ └── exception_route.py ├── middleware/ # 中间件 │ └── middlewares.py └── vo/ # 值对象Pydantic请求/响应模型 ├── shop.py └── user.py一句话总结三层架构routes → service → po配合独立的 depends / exception / middleware / vo 模块每一层职责清晰、互不越界。2. 应用入口lifespan 生命周期main.py是整个应用的起点。FastAPI 提供了lifespan异步上下文管理器来处理启动/关闭逻辑比传统的app.on_event(startup)更推荐。fromcontextlibimportasynccontextmanagerfromfastapiimportFastAPIasynccontextmanagerasyncdeflifespan(app:FastAPI):# 启动时执行 create_database()# 自动建库Base.metadata.create_all(binddb_engine)# 自动建表yield# 关闭时执行如有需要在此清理资源appFastAPI(lifespanlifespan)yield之前的代码在服务启动时执行这里做了两件事自动创建 PostgreSQL 数据库如果不存在和自动创建所有 ORM 模型对应的表。yield之后的代码在服务关闭时执行适合放清理连接池、释放资源等逻辑。一句话总结lifespan 是 FastAPI 推荐的启动/关闭钩子替代了旧的 on_event 装饰器写法更直观、资源管理更安全。3. 路由模块化APIRouter 拆分真实项目不可能把所有接口写在一个文件里。FastAPI 用APIRouter来实现路由的模块化拆分每个业务模块一个 Router 文件。以购物车模块为例core/routes/shop_route.pyfromfastapiimportAPIRouter# 创建购物车模块的分路由shop_routeAPIRouter(tags[购物车模块接口])shop_route.get(/get_all,summary获取所有购物车)defget_all_shop(db:SessionDepends(get_db)):shopsshop_service.get_all_shops(db)return{msg:购物车列表,data:[...]}shop_route.get(/get_detail/{id},summary获取购物车详情)defget_shop_detail(id:intPath(...),db:SessionDepends(get_db)):...shop_route.post(/create,summary创建购物车)defcreate_shop(shop:ShopCreateVo,db:SessionDepends(get_db)):...关键点每个 Router 通过tags参数指定 Swagger 文档中的分组标签让接口在/docs页面中按业务模块展示前端或测试一看就懂。一句话总结APIRouter 让路由按业务模块拆分tag 参数控制 Swagger 文档分组维护起来一目了然。4. 五种参数来源详解FastAPI 支持从多个位置提取请求参数覆盖了日常开发的所有场景参数来源FastAPI 函数使用场景示例路径参数Path()资源ID、固定层级/shop/get_detail/{id}查询参数Query()筛选、分页、排序/shop/get_detail_by_id?id1请求体Pydantic ModelPOST/PUT 创建/更新def create(shop: ShopCreateVo)CookieCookie()会话标识、追踪session_id: str Cookie(None)HeaderHeader()认证Token、追踪IDauthorization: str Header(...)4.1 路径参数 vs 查询参数# 路径参数RESTful风格资源标识作为URL的一部分shop_route.get(/get_detail/{id})defget_shop_detail(id:intPath(...,description购物车ID),db:SessionDepends(get_db)):...# 查询参数适合可选筛选条件URL格式 ?id1shop_route.get(/get_detail_by_id)defget_shop_detail_by_id(id:intQuery(...,description购物车ID),db:SessionDepends(get_db)):...我的理解路径参数适合必填的资源定位如/user/123查询参数适合可选的筛选条件如?page1size10。...是 Python 的Ellipsis在 FastAPI 中表示该参数必填。4.2 Cookie 与 Header 参数user_route.get(/cookie-header)defvalidate_cookie_header(session_id:str|NoneCookie(None,description会话ID),# 可选x_request_id:str|NoneHeader(None,description请求追踪ID),# 可选user_agent:strHeader(...,descriptionUser-Agent),# 必填):return{session_id:session_id,x_request_id:x_request_id,user_agent:user_agent}Cookie 和 Header 本质上都是 HTTP 请求头的一部分但 FastAPI 将它们分开处理语义更清晰。Cookie()提取的是 Cookie 请求头中的值而Header()提取的是普通请求头。一句话总结FastAPI 通过 Path / Query / Cookie / Header / Pydantic Model 五类参数函数统一了参数提取方式你只需要关注业务逻辑不用手动解析 HTTP 请求。5. 路由注册与 Swagger 分组所有模块的 Router 最终在main.py中统一注册# 路由注册prefix 指定URL前缀tags 指定Swagger文档分组app.include_router(shop_route,prefix/shop,tags[购物车模块接口])app.include_router(user_route,prefix/user,tags[用户模块接口])app.include_router(exception_route,prefix/exception,tags[异常抛出演示])app.include_router(depends_route,prefix/depends,tags[依赖注入演示])if__name____main__:importuvicorn uvicorn.run(app,host127.0.0.1,port8000)prefix 的作用每个 Router 内部定义相对路径如/get_all注册时加上 prefix如/shop最终 URL 就是/shop/get_all。这样 Router 文件内部不需要关心全局路径前缀换一个 prefix 就换一套 URL。启动后访问http://127.0.0.1:8000/docs即可看到自动生成的 Swagger 文档接口按 tag 分组展示。一句话总结include_router 的 prefix 控制 URL 前缀tags 控制文档分组两者配合实现了路由的物理拆分和逻辑分组。6. 总结本文从一个真实可运行的 FastAPI 项目出发拆解了工程骨架的核心要素lifespan管理应用启动/关闭逻辑自动建库建表APIRouter实现路由模块化按业务领域拆分五种参数来源路径、查询、请求体、Cookie、Header覆盖所有参数场景include_router统一注册prefix tags 控制 URL 和文档如果用一句话总结FastAPI 项目搭建的核心是模块化——用 lifespan 管理生命周期用 APIRouter 拆分路由用 prefix 控制 URL 空间让项目从一开始就具备良好的可扩展性。