FastAPI + SQLAlchemy 零基础完整教程
一套面向新手小白的系统教程，从环境搭建开始，一步步带你学会用 FastAPI 和 SQLAlchemy 开发一个完整的 Web API 项目。
这套教程适合谁？
- 会一点 Python 基础（变量、函数、类、字典列表），但没写过 Web 后端
- 想学习如何开发 API 接口
- 想学习如何用 Python 操作数据库
- 想做出一个能上线的完整后端项目
技术栈版本说明
本教程使用当前主流的现代写法：
| 技术 | 版本 | 说明 |
|---|---|---|
| Python | 3.10+ | 建议 3.11 或 3.12 |
| FastAPI | 0.110+ | 现代 Python Web 框架 |
| Pydantic | v2 | 数据校验库（FastAPI 自带） |
| SQLAlchemy | 2.0+ | Python 最流行的 ORM，使用 2.0 新语法 |
| Uvicorn | 最新 | ASGI 服务器，用来运行 FastAPI |
| SQLite / MySQL | - | 教学用 SQLite，也讲 MySQL 的接法 |
目录结构与学习路线
请按顺序学习，每一章都建立在前一章的基础上。
第一部分：入门准备（01-入门准备/）
| 文件 | 内容 |
|---|---|
| 1.1 认识 FastAPI | FastAPI 是什么、为什么选它、Web API 基本概念 |
| 1.2 环境搭建 | 安装 Python、创建虚拟环境、安装依赖 |
| 1.3 第一个 API 程序 | Hello World、启动服务、自动交互文档 |
第二部分：FastAPI 基础（02-FastAPI基础/）
| 文件 | 内容 |
|---|---|
| 2.1 路径参数 | URL 中的动态参数、类型校验 |
| 2.2 查询参数 | ?page=1&size=10 这类参数的处理 |
| 2.3 请求体与 Pydantic 模型 | 接收 JSON 数据、数据校验 |
| 2.4 响应模型与状态码 | 控制返回的数据结构和 HTTP 状态码 |
| 2.5 表单和文件上传 | 处理表单提交和文件上传 |
| 2.6 错误处理 | HTTPException、自定义异常 |
| 2.7 依赖注入（Depends） | FastAPI 最核心的机制 Depends |
第三部分：SQLAlchemy 基础（03-SQLAlchemy基础/）
| 文件 | 内容 |
|---|---|
| 3.1 数据库与 ORM 入门 | 数据库、SQL、ORM 都是什么 |
| 3.2 安装与连接数据库 | engine、Session、连接 SQLite/MySQL |
| 3.3 定义数据模型 | 用 Python 类定义数据表（2.0 语法） |
| 3.4 增删改查（CRUD） | 最常用的数据库操作 |
| 3.5 表关系：一对多与多对多 | 一对多、多对多关系 |
第四部分：整合实战（04-整合实战/）
从这里开始，我们把 FastAPI 和 SQLAlchemy 结合起来，做一个「博客 API」项目（用户、文章、标签）。
| 文件 | 内容 |
|---|---|
| 4.1 项目结构设计 | 多文件项目怎么组织 |
| 4.2 数据库会话与依赖注入 | get_db 依赖、生命周期管理 |
| 4.3 用户接口实战 | 完整的用户 CRUD 接口 |
| 4.4 文章与标签接口 | 带关联关系的接口 |
| 4.5 分页、搜索、排序 | 列表接口的标配功能 |
第五部分：进阶主题（05-进阶主题/）
| 文件 | 内容 |
|---|---|
| 5.1 用户认证（JWT） | 注册、登录、Token 鉴权 |
| 5.2 中间件与 CORS | 跨域、请求日志 |
| 5.3 数据库迁移（Alembic） | 表结构变更的正确姿势 |
| 5.4 自动化测试 | pytest + TestClient |
| 5.5 部署上线 | 生产环境部署方案 |
附录（06-附录/）
| 文件 | 内容 |
|---|---|
| 附录 A：常见错误排查 | 新手最容易踩的坑 |
| 附录 B：常用命令与代码速查 | 命令和代码片段速查表 |
学习建议
- 一定要动手敲代码。只看不练是学不会编程的，每一章的代码都请自己敲一遍、跑起来。
- 遇到报错不要慌。先看报错信息的最后几行，再查 常见错误排查。
- 善用自动文档。FastAPI 自带的
/docs页面可以直接测试接口，是你最好的调试工具。 - 学完基础就去做项目。第四部分的博客项目请完整跟着做一遍，做完你就入门了。
准备好了吗？从 1.1 认识 FastAPI 开始吧！