【超详细】Python FastAPI 入门：写给新手的“保姆级”教程（2025–2026 最新版）
这篇教程的目标是：
零基础 → 能独立写出生产级别的 RESTful API
预计认真跟着做完前 80%，你大概需要 3–10 天（每天 2–4 小时）。
目录（建议按顺序阅读）
- 为什么选择 FastAPI（而不是 Flask / Django）
- 环境准备（最稳的几种方式）
- 第一个 FastAPI 程序（Hello World）
- 核心概念速览（5 分钟建立大局观）
- 路径参数、查询参数、请求体（最常用三大输入方式）
- 响应模型 & 状态码
- 依赖注入（Dependency Injection）入门
- 异步 vs 同步（什么时候用 async def）
- 数据库连接（SQLAlchemy + asyncpg 推荐组合）
- 自动生成的交互式文档（Swagger & ReDoc）
- 错误处理 & 自定义异常
- 安全基础（JWT + OAuth2）
- 项目结构推荐（中大型项目怎么组织）
- 部署（Docker + gunicorn + uvicorn 最常见组合）
- 常见问题 & 调试技巧
1. 为什么选择 FastAPI（2025–2026 视角）
| 维度 | FastAPI | Flask | Django | 结论（2025–2026） |
|---|---|---|---|---|
| 开发速度 | ★★★★★ | ★★★★☆ | ★★★☆☆ | 最快 |
| 性能 | 接近 Node.js / Go | 中等 | 中等偏下 | 目前 Python 最快 |
| 自动文档 | OpenAPI + Swagger + ReDoc | 需手动或扩展 | admin 强大但 API 需额外写 | 碾压 |
| 类型提示支持 | 原生 Pydantic v2 | 需插件 | 部分支持 | 现代开发标配 |
| 异步支持 | 原生 async/await | 需 gevent 或异步扩展 | Channels（较重） | 天生异步 |
| 学习曲线（新手） | 中等（但文档极好） | 最低 | 较高 | 性价比最高 |
| 社区活跃度 | 爆炸式增长 | 成熟但增速放缓 | 非常成熟 | 未来 3–5 年首选 |
一句话结论：
如果你 2025–2026 年想用 Python 写高性能、现代、好维护的 API，FastAPI 几乎是唯一主流选择。
2. 环境准备（选一种最适合你的）
推荐组合（最稳）
Python 3.10 / 3.11 / 3.12 + uv / pdm / poetry（现代包管理） + venv
最快上手方式（5 分钟）
# 方式一：用 uv（2025 年最推荐的极简工具，速度比 pip 快 10–100 倍）
curl -LsSf https://astral.sh/uv/install.sh | sh
uv venv
source .venv/bin/activate # Windows 用 .venv\Scripts\activate
uv pip install fastapi[standard] uvicorn[standard]备选方式（经典 pip + venv）
python -m venv venv
source venv/bin/activate # Windows: venv\Scripts\activate
pip install --upgrade pip
pip install fastapi[standard] uvicorn[standard]安装完成后运行下面代码测试：
# main.py
from fastapi import FastAPI
app = FastAPI()
@app.get("/")
def read_root():
return {"Hello": "FastAPI"}启动：
uvicorn main:app --reload
# 或
python -m uvicorn main:app --reload浏览器打开：http://127.0.0.1:8000
看到 JSON 就成功了！
再访问 http://127.0.0.1:8000/docs → 自动 Swagger 界面出现，恭喜你进入 FastAPI 世界！
3. 核心概念速览（5 分钟建立心智模型）
| 概念 | 通俗解释 | 代码例子简写 |
|---|---|---|
| FastAPI() | 创建应用实例 | app = FastAPI() |
| @app.get/post/… | 路由装饰器 | @app.get(“/items/{item_id}”) |
| 路径参数 | URL 里的动态部分 | item_id: int |
| 查询参数 | ?key=value | q: str = None |
| 请求体 | POST/PUT 里的 JSON | item: Item |
| Pydantic BaseModel | 数据验证 + 序列化 + 自动文档 | class Item(BaseModel): … |
| Depends | 依赖注入（认证、数据库、配置等） | Depends(get_current_user) |
| BackgroundTasks | 后台任务（发邮件、记录日志） | background_tasks.add_task(…) |
4. 经典入门案例：图书管理 API（边学边写）
我们用一个“简易图书管理系统”贯穿全文。
models.py
from pydantic import BaseModel, Field
from typing import Optional
class BookBase(BaseModel):
title: str = Field(..., min_length=1, max_length=100)
author: str = Field(..., min_length=1, max_length=50)
year: int = Field(..., ge=1900, le=2100)
class BookCreate(BookBase):
pass
class Book(BookBase):
id: int
is_available: bool = True
class Config:
from_attributes = True # 兼容 ORMmain.py（逐步添加）
from fastapi import FastAPI, HTTPException, Query, Path
from typing import List
from models import Book, BookCreate
app = FastAPI(title="图书管理 API", version="0.1.0")
# 假数据库
books_db: List[Book] = [
Book(id=1, title="Python速成", author="重阳", year=2025),
]
@app.get("/books/", response_model=List[Book])
def get_books(
skip: int = Query(0, ge=0),
limit: int = Query(10, ge=1, le=100),
author: Optional[str] = None
):
result = books_db[skip : skip + limit]
if author:
result = [b for b in result if b.author.lower() == author.lower()]
return result
@app.get("/books/{book_id}", response_model=Book)
def get_book(book_id: int = Path(..., ge=1)):
for book in books_db:
if book.id == book_id:
return book
raise HTTPException(status_code=404, detail="图书不存在")
@app.post("/books/", response_model=Book, status_code=201)
def create_book(book: BookCreate):
new_id = max(b.id for b in books_db) + 1 if books_db else 1
new_book = Book(id=new_id, **book.model_dump())
books_db.append(new_book)
return new_book启动后就能在 Swagger 上直接测试增删改查了。
下一阶段预告（建议按顺序继续）
- 第 5–8 节：请求体、响应模型、依赖注入、异步路由
- 第 9–10 节：连真实数据库（PostgreSQL + SQLAlchemy 异步）
- 第 11–13 节：认证（JWT）、项目结构、错误处理
- 第 14–15 节：Docker 部署 + 生产化配置
你现在最想先深入哪一部分？
- 继续跟着上面的图书系统写数据库部分（SQLAlchemy async）
- 先把认证（JWT + OAuth2）补上
- 想看完整项目结构推荐（文件夹怎么分）
- 想直接看 Docker + 生产部署方案
- 有具体报错或想改某个功能（告诉我）
回复我，我继续陪你写下去～ 😄
