⚡ FastAPI 完整教程

从零基础到生产上线，一本覆盖 FastAPI 全链路的实战教程。

每章独立成篇，配可运行代码、踩坑清单与配套练习；所有示例统一采用 Pydantic v2 + SQLAlchemy 2.0 现代写法。

---

🗺️ 学习路线图

阶段	章节	内容
📗 入门篇	第 1 ~ 3 章	初识 FastAPI、环境搭建、路由与参数
📘 核心篇	第 4 ~ 7 章	Pydantic 数据模型、响应模型、依赖注入、参数进阶
📙 进阶篇	第 8 ~ 11 章	异常处理、中间件与生命周期、数据库集成、分层架构
📕 高级篇	第 12 ~ 15 章	认证授权、异步并发、文件与模板、WebSocket
📒 实践篇	第 16 ~ 19 章	测试体系、部署上线、综合实战、最佳实践

---

📚 章节导航

#	章节	难度	预计阅读	内容概要
1	初识 FastAPI	⭐	12 min	FastAPI 是什么、ASGI 生态、与 Flask/Django 对比、适用场景
2	环境搭建与第一个应用	⭐	13 min	Python/uv 环境、项目结构、fastapi dev、Swagger UI 与 ReDoc
3	路由与路径/查询参数	⭐	13 min	路径参数、查询参数、路由顺序陷阱、APIRouter 模块化
4	请求体与 Pydantic 模型	⭐⭐	20 min	BaseModel、Field 校验、嵌套模型、Pydantic v2 校验器
5	响应模型与状态码	⭐⭐	19 min	response_model、status_code、Response、敏感字段过滤
6	依赖注入系统	⭐⭐⭐	22 min	Depends、类依赖、子依赖、yield 依赖、全局依赖
7	参数进阶	⭐⭐⭐	15 min	Path/Query/Body/Header/Cookie/Form/File 全解
8	错误处理与异常体系	⭐⭐	14 min	HTTPException、自定义异常处理器、统一错误响应体
9	中间件、CORS 与生命周期	⭐⭐⭐	16 min	自定义中间件、CORS 配置、lifespan、后台任务
10	数据库集成（SQLAlchemy 2.0）	⭐⭐⭐	23 min	异步引擎、AsyncSession、依赖注入会话、Alembic 迁移
11	分层架构与 CRUD 工程化	⭐⭐⭐⭐	28 min	目录分层、Repository/Service、事务边界、分页与排序
12	认证与授权（OAuth2 + JWT）	⭐⭐⭐⭐	28 min	密码哈希、JWT 签发校验、OAuth2PasswordBearer、权限依赖
13	异步编程与并发模型	⭐⭐⭐	13 min	async def vs def、阻塞调用陷阱、线程池、httpx 调用外部服务
14	文件上传、静态资源与模板	⭐⭐	14 min	UploadFile、大小与类型校验、StaticFiles、Jinja2 模板
15	WebSocket 实时通信	⭐⭐⭐	17 min	WebSocket 端点、连接管理器、广播、心跳与断线重连
16	测试体系（pytest + httpx）	⭐⭐⭐	14 min	同步/异步测试、依赖覆盖、测试数据库、覆盖率
17	部署与生产实践	⭐⭐⭐⭐	14 min	多进程启动、Docker 镜像、Nginx 反代、配置管理、可观测性
18	综合实战 —— 构建完整 REST API	⭐⭐⭐⭐	45 min	从零搭建一个带认证、权限、分页、测试与 Docker 的博客 API
19	最佳实践与速查表	⭐⭐⭐	23 min	项目结构、命名规范、性能清单、常见坑、速查表

全书 19 章约 1.1 万行，完整通读 + 动手实践约需 6 小时；只求上手的话，第 1 ~ 3 章 + 第 18 章共约 1.5 小时即可跑通一个完整项目。

---

🎯 适合人群

人群	推荐起点	阅读建议
完全零基础	第 1 章	从头按顺序阅读，第 2 章动手跑通第一个应用
写过 Flask / Django	第 3 章	重点看依赖注入、Pydantic 校验、异步模型三块差异
用过 FastAPI 但不系统	第 6 章	从依赖注入与分层架构切入，补齐工程化能力
只想要一份速查	第 19 章	直接跳到第 19 章速查表，按需回看

---

🧰 技术栈与版本

本教程面向以下版本编写（版本号为写作时的最新稳定版），不要混用 Pydantic v1 的旧写法：

组件	版本	用途
Python	≥ 3.10（推荐 3.12 / 3.13）	运行环境（FastAPI 官方要求 ≥ 3.10）
FastAPI	0.141.x	Web 框架本体
Pydantic	2.13.x	数据校验与序列化
Uvicorn	随 fastapi[standard] 安装	ASGI 服务器
SQLAlchemy	2.0.x（异步）	ORM
Alembic	1.x	数据库迁移
pydantic-settings	2.x	环境变量配置管理
PyJWT + pwdlib[argon2]	最新	JWT 签发与密码哈希
pytest + pytest-asyncio + httpx	最新	测试体系

---

📂 目录结构

fastapi/
├── README.md                    # 本页：课程总览与导航
├── chapters/                    # 📝 19 个章节，每章独立文件
│   ├── 01-introduction.md
│   ├── ...
│   ├── 19-best-practices.md
│   ├── _template.md             # 新增章节的写作模板
│   └── _writing-guide.md        # 章节写作规范
└── examples/                    # 📦 可直接复用的完整示例
    ├── hello/                   #   最小可运行应用
    ├── crud-api/                #   分层架构 CRUD 示例
    ├── auth-api/                #   JWT 认证示例
    └── capstone/                #   综合实战项目骨架

---

📖 使用建议

1. 按路线读：入门篇不要跳，第 2 章的环境与项目结构约定贯穿全书。
2. 边读边跑：每章代码都可以直接落到 app/ 包结构中，第 18 章的实战项目就是把前面所有章节拼起来。
3. 查坑点：每章末尾的「常见坑与排查」表格按「现象 → 原因 → 解决」组织，报错时可当索引查。
4. 配示例：examples/ 下是完整可运行的工程，卡住时对照阅读。

---

💡 提示：每章末尾都附有「下一章预告」，帮你建立章节间的知识关联。