【超详细】Python FastAPI 入门：写给新手的“保姆级”教程
【超详细】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|shuv venvsource.venv/bin/activate# Windows 用 .venv\Scripts\activateuv pipinstallfastapi[standard]uvicorn[standard]备选方式（经典 pip + venv）
python -m venv venvsourcevenv/bin/activate# Windows: venv\Scripts\activatepipinstall--upgrade pip pipinstallfastapi[standard]uvicorn[standard]安装完成后运行下面代码测试：
# main.pyfromfastapiimportFastAPI app=FastAPI()@app.get("/")defread_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
frompydanticimportBaseModel,FieldfromtypingimportOptionalclassBookBase(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)classBookCreate(BookBase):passclassBook(BookBase):id:intis_available:bool=TrueclassConfig:from_attributes=True# 兼容 ORMmain.py（逐步添加）
fromfastapiimportFastAPI,HTTPException,Query,PathfromtypingimportListfrommodelsimportBook,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])defget_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]ifauthor:result=[bforbinresultifb.author.lower()==author.lower()]returnresult@app.get("/books/{book_id}",response_model=Book)defget_book(book_id:int=Path(...,ge=1)):forbookinbooks_db:ifbook.id==book_id:returnbookraiseHTTPException(status_code=404,detail="图书不存在")@app.post("/books/",response_model=Book,status_code=201)defcreate_book(book:BookCreate):new_id=max(b.idforbinbooks_db)+1ifbooks_dbelse1new_book=Book(id=new_id,**book.model_dump())books_db.append(new_book)returnnew_book启动后就能在 Swagger 上直接测试增删改查了。
下一阶段预告（建议按顺序继续）
- 第 5–8 节：请求体、响应模型、依赖注入、异步路由
- 第 9–10 节：连真实数据库（PostgreSQL + SQLAlchemy 异步）
- 第 11–13 节：认证（JWT）、项目结构、错误处理
- 第 14–15 节：Docker 部署 + 生产化配置
你现在最想先深入哪一部分？
- 继续跟着上面的图书系统写数据库部分（SQLAlchemy async）
- 先把认证（JWT + OAuth2）补上
- 想看完整项目结构推荐（文件夹怎么分）
- 想直接看 Docker + 生产部署方案
- 有具体报错或想改某个功能（告诉我）
回复我，我继续陪你写下去～ 😄