FastAPI 从入门到生产

沈宥

发布于 2026-01-08 10:48:51

7700

文章被收录于专栏：从头开始学习测试开发从头开始学习测试开发

🟦 导语：为什么 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：

brew install pyenv
pyenv install 3.11.5
pyenv global 3.11.5

🔹 2. 创建 FastAPI 项目目录

mkdir fastapi-demo
cd fastapi-demo

🔹 3. 安装 FastAPI + Uvicorn

pip install fastapi uvicorn[standard]

🔹 4. 编写主程序 `main.py`

from fastapi import FastAPI
app = FastAPI()
@app.get("/hello")
async def hello():
return
 {"message": "Hello FastAPI!"}

🔹 5. 启动服务

uvicorn main:app --reload

浏览器访问：

http://127.0.0.1:8000/hello
http://127.0.0.1:8000/docs
http://127.0.0.1:8000/redoc

四、FastAPI 如何定制路由（Router 分模块管理）

FastAPI 强烈建议用 APIRouter 进行路由拆分：

# routers/user.py
from fastapi import APIRouter
router = APIRouter(prefix="/user", tags=["User"])

@router.get("/info")
async def get_user():
return {"user": "Tom"}


主入口引用：
from fastapi import FastAPI
from routers.user import router as user_router
app = FastAPI()
app.include_router(user_router)

优势：

模块化清晰
便于拆分团队协作
路由自动按 tags 分类出现在文档里

五、请求参数如何设置必传 / 非必传？如何使用 Pydantic Model？

🔹 1. Query 参数可设置默认值/必传：

from fastapi import Query
@app.get("/items")
async def get_item(name: str = Query(...), size: int = Query(10)):
return {"name": name, "size": size}

name → 必传
size → 默认值 = 非必传

🔹 2. Body 参数使用 Pydantic Model

from pydantic import BaseModel
class User(BaseModel):
    name: str
    age: int
    city: str | None = None

    
@app.post("/add")
async defadd_user(user: User):
return user

自动完成：

数据校验
类型转换
API 文档生成

六、FastAPI 支持的 HTTP 请求方式

除了 GET、POST，还支持：

方法	用法
PUT	更新资源
DELETE	删除资源
PATCH	局部更新
OPTIONS	预检请求
HEAD	返回响应头

示例：

@app.delete("/item/{id}")
async def delete_item(id: int):
return {"deleted": id}

七、依赖注入 Dependencies：如何配置校验？

FastAPI 最强大的部分是依赖注入，可用于：

数据库 Session
Token/权限验证
请求前统一校验
公共逻辑注入

🔹 声明一个依赖

from fastapi import Depends, HTTPException
def verify_token(token: str):
if token != "123":
  raise HTTPException(401, "Invalid token")
return True

🔹 接口使用依赖

@app.get("/secure")
async def secure_route(auth=Depends(verify_token)):
return {"ok": True}

八、统一返回结构 & 统一异常处理

🔹 1. 自定义统一返回结构

def success(data=None):
return {"code": 0,"message": "success","data": data}

接口使用：

@app.get("/info")
async def info():
return success({"name": "Tom"})

🔹 2. 自定义异常

from fastapi import HTTPException
@app.get("/error")
async def error():
raise
 HTTPException(status_code=400, detail="Bad Request")

🔹 3. 统一异常拦截

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)}
    )

九、FastAPI 如何实现并发？（async + await）

FastAPI 本身是异步框架，只需要：

使用 async def
结合 await IO 操作

示例：

import asyncio

@app.get("/concurrent")
async def concurrent():
await asyncio.sleep(1)
return {"ok": True}

多个请求会自动并发执行，不阻塞。

十、FastAPI 自动生成接口 API 文档

FastAPI 自动支持两个文档：

文档	地址	用途
Swagger UI	/docs	在线调试 + 文档
ReDoc	/redoc	更适合阅读的文档

接口定义完成后即自动出现在文档中，无需额外处理。

十一、完整代码模板（可直接复制使用）

以下模板包含：

路由模块化
参数校验
依赖注入
统一返回
自定义异常
主文件启动

🟩 main.py

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"}

🟦 routers/user.py

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 defadd_user(user: User, auth=Depends(verify_token)):
return {"code": 0, "data": user}

@router.get("/info")
async def get_info(name: str):
return
 {"name": name}

十二、总结：FastAPI 是现代 Python 服务端最佳实践

FastAPI 的优势不是某一项功能，而是：

类型提示优先
自动文档
原生异步
依赖注入
强数据校验
工程化优秀

结合 Uvicorn + Pydantic + Starlette，成为 Python 现代 Web 框架中最均衡、最适合团队开发的选择。

如果你正在写 API、微服务、后台系统、网关层，FastAPI 都能提供极高的开发效率和生产可用性。

本文参与腾讯云自媒体同步曝光计划，分享自微信公众号。

原始发表：2025-12-10，如有侵权请联系 [email protected] 删除

异步

本文分享自质量工程与测开技术栈微信公众号，前往查看

如有侵权，请联系 [email protected] 删除。

本文参与腾讯云自媒体同步曝光计划，欢迎热爱写作的你一起参与！

登录后参与评论

0 条评论

热度