FastAPI 极简教程（偏实战，一篇搞定）

FastAPI 极简教程（偏实战，一篇搞定）

目标：用最少的概念把 FastAPI 的常用能力串起来：路由、参数、数据校验、依赖注入、错误处理、鉴权、数据库、测试、部署与 Docker。看完能直接起一个可用的小服务。
参考文档：FastAPI 官方文档、Starlette、Pydantic、Uvicorn 等（文末有链接）。

目录

文章目录

• FastAPI 极简教程（偏实战，一篇搞定）
• • 目录
  • 1. FastAPI 是什么
  • 2. 安装与最小可运行项目
  • • 2.1 环境准备
    • 2.2 目录结构（极简）
  • 3. 第一个接口：Hello World
  • 4. 路由与参数：Path、Query、Body
  • • 4.1 Path 参数
    • 4.2 Query 参数
    • 4.3 参数约束（Query / Path）
    • 4.4 Body 参数（JSON 请求体）
  • 5. 数据模型与校验：Pydantic
  • 6. 响应模型与状态码
  • • 6.1 用 response_model 控制输出
    • 6.2 自定义状态码
  • 7. 错误处理：HTTPException 与全局异常
  • • 7.1 主动抛 HTTPException
    • 7.2 全局异常处理器（把内部异常变成统一结构）
  • 8. 依赖注入：Dependencies（FastAPI 的核心技巧）
  • • 8.1 最简单的 Depends
    • 8.2 带参数的依赖：做权限校验
    • 8.3 依赖的“资源释放”：yield 写法
  • 9. 中间件、CORS、请求日志
  • • 9.1 CORS
    • 9.2 简单请求耗时日志中间件
  • 10. 文件上传与静态文件
  • • 10.1 上传文件
    • 10.2 静态文件
  • 11. 鉴权：API Key 与 JWT（OAuth2 密码模式）
  • • 11.1 API Key（最短路径）
    • 11.2 JWT 思路（极简版）
  • 12. 数据库：SQLAlchemy + 会话依赖
  • • 12.1 建库与模型（SQLite 示例）
    • 12.2 提供 Session 的依赖
    • 12.3 在接口里用 db
  • 13. 异步与并发：什么时候用 async
  • 14. 后台任务与定时任务的替代方案
  • • 14.1 后台任务 BackgroundTasks（轻量场景）
    • 14.2 定时任务
  • 15. 测试：pytest + TestClient
  • 16. 部署：Uvicorn / Gunicorn / Docker
  • • 16.1 直接用 Uvicorn（简单）
    • 16.2 Gunicorn + Uvicorn Worker（多进程）
    • 16.3 Docker（可复制粘贴）
  • 17. 一个小而完整的项目骨架
  • • 17.1 路由拆分示例
  • 文末参考链接

---

1. FastAPI 是什么

FastAPI 是一个基于Starlette（Web 框架）与Pydantic（数据校验）的 Python API 框架，主打：

• 自动生成 OpenAPI 文档与交互式 Swagger UI
• 类型标注驱动的数据校验与序列化
• 天然支持 async
• 依赖注入（Dependencies）很好用

这些能力都来自官方设计：FastAPI 建在 Starlette 之上，用 Pydantic 处理请求/响应数据模型。FastAPI 文档 对此有明确说明。

---

2. 安装与最小可运行项目

2.1 环境准备

建议：Python 3.10+（越新越好）。

安装 FastAPI 与 Uvicorn：

pipinstallfastapi uvicorn

• uvicorn是常用的 ASGI Server，用来运行 FastAPI。