目录前言1 环境安装2 第一个 FastAPI 项目2.1 方式 1命令行启动2.2 方式 2代码内直接启动 uvicorn2.3 访问自动交互式文档3 同步 def 与异步 async def 路由区别4 三大参数详解4.1 路径参数URL 路径中变量4.2 查询参数URL? 后键值对4.3 请求体POST/PUT 传 JSONPydantic 模型5大型项目模块化APIRouter 路由拆分5.1 项目结构5.2 子路由 routers/user.py5.3 主文件挂载路由 main.py6 本章总结前言FastAPI 基于 StarlettePydantic自带自动 Swagger 文档、类型校验、依赖注入是 Python 高性能 API 首选。本章从零搭建项目覆盖路由、路径参数、查询参数、请求体、模块化路由拆分。1 环境安装# 框架 异步服务器pipinstallfastapi uvicorn2 第一个 FastAPI 项目2.1 方式 1命令行启动main.pyfromfastapiimportFastAPI appFastAPI()app.get(/)defroot():return{msg:Hello FastAPI}app.get(/items/{item_id})defget_item(item_id:int,q:str|NoneNone):return{item_id:item_id,query:q}终端运行# main文件名 appFastAPI实例 --reload开发热更新uvicorn main:app--reload2.2 方式 2代码内直接启动 uvicornimportuvicornfromfastapiimportFastAPI appFastAPI()app.get(/)asyncdefroot():return{msg:async接口}if__name____main__:uvicorn.run(appmain:app,host0.0.0.0,# 允许局域网访问port8000,reloadTrue# 生产环境删除)2.3 访问自动交互式文档FastAPI Swagger文档页面接口预览文档http://127.0.0.1:8000/docsSwagger UI极简 JSON 文档http://127.0.0.1:8000/redoc3 同步 def 与异步 async def 路由区别async def原生协程内部可使用await异步 IO异步数据库 /aiohttp事件循环直接调度性能最优def同步函数FastAPI 自动放入线程池执行不阻塞事件循环但大量耗时同步操作会耗尽线程池最佳实践数据库、网络 IO 优先 async def纯计算逻辑使用普通 def4 三大参数详解4.1 路径参数URL 路径中变量# item_id强制int类型传字符串自动返回422校验错误app.get(/items/{item_id})asyncdefget_item(item_id:int):return{id:item_id}文档路径参数类型校验参数顺序坑固定路由/users/me必须写在/users/{user_id}前面否则me会被识别为 user_id 参数4.2 查询参数URL? 后键值对# start默认0 limit默认10 short布尔可选app.get(/items/)asyncdeflist_items(start:int0,limit:int10,short:boolFalse):return{slice:[start,startlimit],short:short}不传参数使用默认值不写默认值则为必传参数bool 类型自动转换true/1/on/yes都会识别为 True4.3 请求体POST/PUT 传 JSONPydantic 模型POST请求体文档示例frompydanticimportBaseModel# 定义请求体校验模型classItem(BaseModel):name:strprice:floatdesc:str|NoneNone# 可选字段app.post(/items/)asyncdefcreate_item(item:Item):# item自动转为字典返回自动校验字段类型returnitem5大型项目模块化APIRouter 路由拆分5.1 项目结构myproject/ ├── main.py # 主应用 └── routers/ ├── user.py # 用户模块路由 └── item.py # 商品模块路由5.2 子路由 routers/user.pyfromfastapiimportAPIRouter# prefix统一路由前缀 tags文档分组routerAPIRouter(prefix/users,tags[用户管理])router.get(/)defget_users():return{users:[]}router.get(/{user_id})defget_user(user_id:int):return{user_id:user_id}5.3 主文件挂载路由 main.pyfromfastapiimportFastAPIfromroutersimportuser,item appFastAPI(title路由拆分演示)# 把子路由注册到主应用app.include_router(user.router)app.include_router(item.router)app.get(/)defroot():return{msg:首页}路由拆分后文档分组效果运行后文档自动按tags分组接口地址自动拼接prefix6 本章总结FastAPI 内置自动接口文档无需手写 API 文档三类参数路径参数、查询参数、Pydantic 请求体自动类型校验区分同步 / 异步路由IO 密集优先 async defAPIRouter 实现路由模块化解决单文件路由臃肿问题