🟦 导语：为什么 FastAPI 会火成这样？
FastAPI 是目前 Python 生态中发展最快、社区最活跃的新一代 Web 框架，以 类型提示驱动、自动文档、异步高性能 为核心特性，迅速成为构建 REST API、微服务的首选框架。
本文将从 环境搭建 → 启动服务 → 路由设计 → 参数校验 → 依赖注入 → 统一返回 → 并发 → API 文档 → 示例模板 一次讲清楚所有你需要掌握的 FastAPI 核心知识点。
整篇文章从基础到生产可用，适合作为 学习路径文章 / 团队内部培训文档 / 技术分享文档。
一、官方文档：FastAPI 能做什么？优缺点是什么？
🔹 官方能力说明（来自 FastAPI 官方文档的核心总结）
FastAPI 提供：
✔ 高性能（可媲美 Node.js / Go）
基于 Starlette（异步 Web 框架） + Pydantic（高性能数据校验）
Python Web 框架中性能天花板之一
✔ 自动生成 API 文档：Swagger + ReDoc
无需编写文档，自动生成：
/docs（Swagger UI）/redoc（Redoc）
✔ 使用 Python 类型提示自动校验参数
自动请求参数校验
自动响应模型校验
自动补全（IDE 体验极佳）
✔ 原生异步 async/await 支持
适合高并发 IO 场景。
✔ 依赖注入系统非常灵活
支持：
权限校验
Token 校验
DB 会话管理
统一行为注入
🔹 官方总结的优点
| 优点 | 描述 |
|---|---|
| 🚀 高性能 | 内部使用 uvicorn + Starlette |
| 🧩 自动文档 | 你写代码 = 文档自动生成 |
| 🛡 强大的数据校验 | Pydantic 模型校验非常强 |
| 🧵 原生异步 | 完全支持 async/await |
| ♻ 易维护 | 类型提示 + 自动补全 |
| 🧱 适合微服务 | 易拆分、易扩展 |
🔸 FastAPI 的缺点（客观）
| 缺点 | 描述 |
|---|---|
| 生态比 Django 小 | ORM / Admin 不如 Django 完整 |
| Pydantic 学习成本 | 初学者需要适应 Model 模式 |
| 高度依赖类型提示 | 代码量相比 Flask 多 |
| 部分组件需要自行封装 | 如全局异常、中间件体系等 |
二、社区活跃度与框架排名
🔹 GitHub Star 数（截至 2025）
| 框架 | Star 数量 | 备注 |
|---|---|---|
| FastAPI | 80k+ | 增长最快的 Python Web 框架 |
| Flask | 65k+ | Python Web 老二 |
| Django | 75k+ | 全家桶框架 |
| Sanic | 18k+ | 高性能异步 |
| Tornado | 22k+ | 实时框架 |
FastAPI 的增长速度是所有框架中 最快 的。
🔹 Google Trends 过去 5 年对比
FastAPI 曲线一路向上，已经与 Flask 接近并逼近 Django。
🔹 社区热度总结
企业采用率迅速上升（微软/Netflix/滴滴等在使用）
文档库/教程更新频繁
插件生态不断扩大（FastAPI Users、FastAPI Cache 等）
结论：FastAPI 已成为 Python Web 开发的主流第一选择。
三、如何快速启动 FastAPI 服务（环境安装 + 启动服务）
🔹 1. 安装 Python 环境（建议 3.9+）
推荐使用 pyenv 或 conda：
<pre class="overflow-visible!" data-start="1990" data-end="2061">
brew install pyenv pyenv install 3.11.5 pyenv global 3.11.5
</pre>
🔹 2. 创建 FastAPI 项目目录
<pre class="overflow-visible!" data-start="2094" data-end="2140">
mkdir fastapi-demo cd fastapi-demo
</pre>
🔹 3. 安装 FastAPI + Uvicorn
<pre class="overflow-visible!" data-start="2178" data-end="2227">
pip install fastapi uvicorn[standard]
</pre>
🔹 4. 编写主程序 main.py
<pre class="overflow-visible!" data-start="2260" data-end="2398">
`from fastapi import FastAPI
app = FastAPI() @app.get("/hello") async def hello(): return {"message": "Hello FastAPI!"}`
</pre>
🔹 5. 启动服务
<pre class="overflow-visible!" data-start="2420" data-end="2457">
uvicorn main:app --reload
</pre>
浏览器访问：
四、FastAPI 如何定制路由（Router 分模块管理）
FastAPI 强烈建议用 APIRouter 进行路由拆分：
<pre class="overflow-visible!" data-start="2639" data-end="2822">
`# routers/user.py from fastapi import APIRouter
router = APIRouter(prefix="/user", tags=["User"]) @router.get("/info") async def get_user(): return {"user": "Tom"}`
</pre>
主入口引用：
<pre class="overflow-visible!" data-start="2832" data-end="2969">
`from fastapi import FastAPI from routers.user import router as user_router
app = FastAPI()
app.include_router(user_router)`
</pre>
优势：
模块化清晰
便于拆分团队协作
路由自动按 tags 分类出现在文档里
五、请求参数如何设置必传 / 非必传？如何使用 Pydantic Model？
🔹 1. Query 参数可设置默认值/必传：
<pre class="overflow-visible!" data-start="3105" data-end="3271">
from fastapi import Query @app.get("/items") async def get_item(name: str = Query(...), size: int = Query(10)): return {"name": name, "size": size}
</pre>
...→ 必传10→ 默认值 = 非必传
🔹 2. Body 参数使用 Pydantic Model
<pre class="overflow-visible!" data-start="3350" data-end="3540">
from pydantic import BaseModel class User(BaseModel): name: str age: int city: str | None = None @app.post("/add") async def add_user(user: User): return user
</pre>
自动完成：
数据校验
类型转换
API 文档生成
六、FastAPI 支持的 HTTP 请求方式
除了 GET、POST，还支持：
| 方法 | 用法 |
|---|---|
| PUT | 更新资源 |
| DELETE | 删除资源 |
| PATCH | 局部更新 |
| OPTIONS | 预检请求 |
| HEAD | 返回响应头 |
示例：
<pre class="overflow-visible!" data-start="3756" data-end="3854">
@app.delete("/item/{id}") async def delete_item(id: int): return {"deleted": id}
</pre>
七、依赖注入 Dependencies：如何配置校验？
FastAPI 最强大的部分是依赖注入，可用于：
数据库 Session
Token/权限验证
请求前统一校验
公共逻辑注入
🔹 声明一个依赖
<pre class="overflow-visible!" data-start="3991" data-end="4167">
from fastapi import Depends, HTTPException def verify_token(token: str): if token != "123": raise HTTPException(401, "Invalid token") return True
</pre>
🔹 接口使用依赖
<pre class="overflow-visible!" data-start="4183" data-end="4292">
@app.get("/secure") async def secure_route(auth=Depends(verify_token)): return {"ok": True}
</pre>
八、统一返回结构 & 统一异常处理
🔹 1. 自定义统一返回结构
<pre class="overflow-visible!" data-start="4344" data-end="4470">
def success(data=None): return { "code": 0, "message": "success", "data": data }
</pre>
接口使用：
<pre class="overflow-visible!" data-start="4479" data-end="4564">
@app.get("/info") async def info(): return success({"name": "Tom"})
</pre>
🔹 2. 自定义异常
<pre class="overflow-visible!" data-start="4587" data-end="4736">
from fastapi import HTTPException @app.get("/error") async def error(): raise HTTPException(status_code=400, detail="Bad Request")
</pre>
🔹 3. 统一异常拦截
<pre class="overflow-visible!" data-start="4760" data-end="5008">
from fastapi.responses import JSONResponse @app.exception_handler(Exception) async def global_exception_handler(request, exc): return JSONResponse( status_code=500, content={"code": 500, "message": str(exc)} )
</pre>
九、FastAPI 如何实现并发？（async + await）
FastAPI 本身是异步框架，只需要：
使用
async def结合
awaitIO 操作
示例：
<pre class="overflow-visible!" data-start="5119" data-end="5247">
import asyncio @app.get("/concurrent") async def concurrent(): await asyncio.sleep(1) return {"ok": True}
</pre>
多个请求会自动并发执行，不阻塞。
十、FastAPI 自动生成接口 API 文档
FastAPI 自动支持两个文档：
| 文档 | 地址 | 用途 |
|---|---|---|
| Swagger UI | /docs |
在线调试 + 文档 |
| ReDoc | /redoc |
更适合阅读的文档 |
接口定义完成后即自动出现在文档中，无需额外处理。
十一、完整代码模板（可直接复制使用）
以下模板包含：
路由模块化
参数校验
依赖注入
统一返回
自定义异常
主文件启动
🟩 main.py
<pre class="overflow-visible!" data-start="5580" data-end="6034">
`from fastapi import FastAPI from routers.user import router as user_router from fastapi.responses import JSONResponse
app = FastAPI(title="FastAPI Demo") # 全局异常 @app.exception_handler(Exception) async def global_exception_handler(request, exc): return JSONResponse(status_code=500, content={"code": 500, "message": str(exc)}) # 注册路由 app.include_router(user_router) @app.get("/health") async def health(): return {"status": "ok"}`
</pre>
🟦 routers/user.py
<pre class="overflow-visible!" data-start="6068" data-end="6677">
`from fastapi import APIRouter, Depends, HTTPException, Query from pydantic import BaseModel
router = APIRouter(prefix="/user", tags=["User"]) # 依赖：token 校验 def verify_token(token: str = Query(...)): if token != "123": raise HTTPException(status_code=401, detail="Invalid Token") return True # 请求体模型 class User(BaseModel):
name: str age: int city: str | None = None @router.post("/add") async def add_user(user: User, auth=Depends(verify_token)): return {"code": 0, "data": user} @router.get("/info") async def get_info(name: str): return {"name": name}`
</pre>
十二、总结：FastAPI 是现代 Python 服务端最佳实践
FastAPI 的优势不是某一项功能，而是：
类型提示优先
自动文档
原生异步
依赖注入
强数据校验
工程化优秀
结合 Uvicorn + Pydantic + Starlette，成为 Python 现代 Web 框架中最均衡、最适合团队开发的选择。
如果你正在写 API、微服务、后台系统、网关层，FastAPI 都能提供极高的开发效率和生产可用性。
