FastAPI 教程：从零开始构建高性能 Web API
你是否曾经为写一个简单的接口而反复调试？是否在使用传统框架时，发现响应速度不够理想，代码冗长难维护？如果你正面临这些问题，那么 FastAPI 可能正是你一直在寻找的解决方案。
FastAPI 是一个现代、快速（高性能）的 Python Web 框架，用于构建 API。它基于 Starlette 框架和 Pydantic 数据验证库，支持异步编程，自动生成交互式 API 文档（Swagger UI 和 ReDoc），并且在开发效率和运行性能上都表现出色。它特别适合构建 RESTful API、微服务、数据接口等场景。
本篇 FastAPI 教程将带你从零开始，逐步掌握 FastAPI 的核心用法，包括项目初始化、路由定义、数据验证、异步支持、依赖注入等关键特性。无论你是刚接触 Python Web 开发的初学者，还是已有经验但想提升开发效率的中级开发者，都能在这里找到实用价值。
快速搭建你的第一个 FastAPI 项目
在开始之前，确保你已安装 Python 3.7 或更高版本。我们先来创建一个最基础的 FastAPI 项目。
打开终端，执行以下命令：
mkdir fastapi-demo && cd fastapi-demo
python -m venv venv
venv\Scripts\activate
source venv/bin/activate
pip install fastapi uvicorn
现在，我们创建一个名为 main.py 的文件，这是 FastAPI 项目的入口文件。
from fastapi import FastAPI
app = FastAPI(title="我的第一个 FastAPI 项目", description="一个简单的 API 示例")
@app.get("/")
def read_root():
# 返回一个字典作为响应数据
return {"message": "欢迎来到 FastAPI 教程！"}
@app.get("/items/{item_id}")
def read_item(item_id: int, q: str = None):
# item_id 是路径参数，必须是整数类型（自动验证）
# q 是查询参数，可选，默认为 None
return {"item_id": item_id, "q": q}
代码说明：
FastAPI()创建应用实例，支持设置标题、描述等元信息。@app.get("/")是路由装饰器，表示当用户访问根路径时，调用下方函数。item_id: int表示该参数必须是整数，FastAPI 会自动进行类型校验。q: str = None定义了一个可选的查询参数，若未传入则默认为 None。
保存文件后，在终端运行：
uvicorn main:app --reload
main:app：表示模块名:应用实例名--reload：开启热重载，代码修改后自动重启服务
访问浏览器打开 http://127.0.0.1:8000，你会看到返回的 JSON 数据。更棒的是，访问 http://127.0.0.1:8000/docs，你将看到自动生成的 Swagger UI 文档界面，可以在线测试接口！
使用 Pydantic 实现数据模型与自动验证
在实际开发中，接口通常需要接收和返回结构化数据。FastAPI 通过 Pydantic 实现了强大的数据模型定义与自动验证功能。
让我们定义一个用户数据模型，用于接收用户注册信息。
from pydantic import BaseModel # 用于定义数据模型
from typing import Optional # 用于可选字段
class User(BaseModel):
# 用户名，必须为字符串，长度至少 3 个字符
username: str
# 邮箱，必须为有效邮箱格式
email: str
# 年龄，可选，范围在 18 到 120 之间
age: Optional[int] = None
# 是否为管理员，可选，默认为 False
is_admin: bool = False
# 可以添加自定义验证逻辑（可选）
@property
def is_eligible(self) -> bool:
return self.age is not None and self.age >= 18
现在，我们创建一个接口，用于接收用户数据：
@app.post("/users/")
def create_user(user: User):
# user 参数会自动从请求体中解析并验证
# 如果数据不符合模型定义，FastAPI 会自动返回 422 错误（验证失败）
return {
"message": "用户创建成功",
"user": user.dict(), # 转为字典返回
"eligible": user.is_eligible
}
关键点解释：
User类定义了数据结构，FastAPI 会自动解析 JSON 请求体并校验。Optional[int]表示字段可选。@property可以在模型中添加逻辑判断。- 如果你发送一个无效请求，比如
{"username": "ab", "email": "abc"}，FastAPI 会返回清晰的错误信息，告诉你username长度不足。
路由分组与模块化设计
随着项目规模扩大，将所有路由写在 main.py 会变得混乱。FastAPI 支持通过 APIRouter 实现模块化路由。
创建一个 routers/users.py 文件：
from fastapi import APIRouter, Depends, HTTPException
from typing import List
from .models import User, UserCreate
router = APIRouter(prefix="/users", tags=["用户管理"])
fake_users_db = []
@router.get("/", response_model=List[User])
def get_users():
return fake_users_db
@router.post("/", response_model=User)
def create_user(user: UserCreate):
# 检查用户名是否已存在
if any(u.username == user.username for u in fake_users_db):
raise HTTPException(status_code=400, detail="用户名已存在")
# 添加到数据库
fake_users_db.append(user)
return user
然后在 main.py 中引入并挂载该路由组：
from fastapi import FastAPI
from routers.users import router as users_router
app = FastAPI(title="模块化 FastAPI 项目")
app.include_router(users_router)
@app.get("/")
def read_root():
return {"message": "FastAPI 项目运行中"}
优势说明：
prefix="/users"为该组所有路由添加前缀。tags=["用户管理"]用于在 Swagger 文档中分类接口。response_model=List[User]明确响应数据结构，帮助文档生成更准确。
异步编程支持与性能优势
FastAPI 的一大亮点是原生支持异步编程（async/await），这使其在高并发场景下表现优异。
我们来写一个异步接口，模拟一个耗时的数据库查询。
import asyncio
from fastapi import FastAPI
app = FastAPI()
async def fetch_data_from_db():
await asyncio.sleep(2) # 模拟 2 秒延迟
return {"data": "这是从数据库获取的数据"}
@app.get("/async-data/")
async def get_async_data():
# 使用 await 调用异步函数
result = await fetch_data_from_db()
return result
性能比喻：
- 同步模式就像你排队买票，必须等前一个人买完才能轮到你。
- 异步模式则像你在窗口点完票后，先去旁边休息，等系统处理完再通知你。
- FastAPI 利用异步机制，可以同时处理成百上千个请求，极大提升吞吐量。
依赖注入：构建可复用的逻辑组件
依赖注入是 FastAPI 的核心特性之一，它允许你将重复逻辑封装为可复用的依赖项。
例如，我们想在多个接口中验证用户权限。
from fastapi import Depends, HTTPException
def get_current_user(token: str = None):
if not token or token != "secret123":
raise HTTPException(status_code=401, detail="认证失败")
return {"username": "admin", "role": "superuser"}
def require_admin(user: dict = Depends(get_current_user)):
if user["role"] != "superuser":
raise HTTPException(status_code=403, detail="权限不足")
return user
@app.get("/admin-only/")
def admin_only(user: dict = Depends(require_admin)):
return {"message": f"欢迎，{user['username']}，您是管理员"}
依赖注入的优势：
- 逻辑集中管理，避免重复代码。
- 可轻松组合多个依赖项。
- 支持作用域控制（全局、请求级等）。
总结与下一步建议
通过本篇 FastAPI 教程，你已经掌握了构建现代化 API 的核心能力：快速启动、数据验证、模块化路由、异步支持与依赖注入。FastAPI 不仅提升了开发效率，还保证了代码的健壮性与可维护性。
接下来，你可以尝试：
- 集成数据库（如 SQLAlchemy、Tortoise ORM）
- 添加 JWT 认证
- 部署到生产环境（使用 Gunicorn + Uvicorn）
- 用 Docker 容器化项目
FastAPI 正在成为 Python 后端开发的首选框架。它既适合初创项目快速验证，也适合中大型系统长期维护。掌握它，等于为你的技术栈增添了一项强有力的竞争优势。
如果你在学习过程中遇到问题，不妨打开 Swagger 文档，通过交互式界面调试接口，这是 FastAPI 带给开发者最贴心的礼物。