这是一份面向现代 Python 开发者的 FastAPI 核心教程。FastAPI 是目前 Python 生态中构建 API 最快、最现代的框架，以其自动文档生成、类型提示驱动的数据验证和强大的依赖注入系统著称。
本教程将从零开始，带你快速掌握 FastAPI 的核心概念，并给出符合生产标准的工程化实践。
📦 一、环境准备与安装
要求：Python 3.9+（推荐 3.10+）
# 安装 FastAPI 和 ASGI 服务器 Uvicorn
pip install fastapi uvicorn[standard]
# 推荐同时安装开发工具
pip install pydantic[email] python-multipart httpx🚀 二、第一个 API：3 分钟跑起来
创建文件 main.py：
from fastapi import FastAPI
app = FastAPI(title="我的第一个 FastAPI 应用", version="1.0.0")
@app.get("/")
def read_root():
return {"message": "Hello FastAPI!"}
@app.get("/items/{item_id}")
def get_item(item_id: int, q: str | None = None):
return {"item_id": item_id, "query": q}启动服务：
uvicorn main:app --reload🌐 访问：
- API 根路径：
http://127.0.0.1:8000 - 交互式文档 (Swagger UI)：
http://127.0.0.1:8000/docs⭐ - ReDoc 文档：
http://127.0.0.1:8000/redoc
💡
--reload会在代码修改时自动重启服务器，开发时必加。
🧱 三、核心概念：参数、请求体与响应模型
1. 路径参数 & 查询参数
@app.get("/users/{user_id}")
def get_user(user_id: int, include_posts: bool = False):
# user_id 来自路径，include_posts 来自查询参数 (?include_posts=true)
return {"user_id": user_id, "include_posts": include_posts}2. 请求体 (Request Body) 与 Pydantic 验证
FastAPI 使用 Pydantic 模型自动解析、验证 JSON 请求体。
from pydantic import BaseModel, Field, EmailStr
class UserCreate(BaseModel):
username: str = Field(..., min_length=3, max_length=50)
email: EmailStr
age: int = Field(..., ge=18, le=120) # ge: >=, le: <=
@app.post("/users/")
def create_user(user: UserCreate):
# 如果请求体不符合 UserCreate 定义，FastAPI 会自动返回 422 错误
return {"msg": f"用户 {user.username} 创建成功", "user": user.model_dump()}3. 响应模型 (Response Model)
控制 API 返回的数据结构，自动过滤内部字段（如密码），并生成 OpenAPI 响应 Schema。
class UserOut(BaseModel):
id: int
username: str
email: EmailStr
@app.post("/users/", response_model=UserOut)
def create_user_v2(user: UserCreate):
# 模拟保存到数据库后返回
return {"id": 1, "username": user.username, "email": user.email, "password": "hashed"}
# ⚠️ 注意：password 字段会被 response_model 自动过滤，不会返回给客户端🔗 四、依赖注入 (Dependency Injection)：FastAPI 的灵魂
Depends() 让代码高度复用、易于测试。常用于：数据库连接、分页参数、权限校验、日志记录等。
from fastapi import Depends, HTTPException, status
# 1. 定义可复用的依赖函数
def pagination(skip: int = 0, limit: int = 100):
return {"skip": skip, "limit": limit}
def get_current_user(token: str = Depends(oauth2_scheme)):
if token != "valid_token":
raise HTTPException(status_code=status.HTTP_401_UNAUTHORIZED, detail="无效令牌")
return {"username": "admin"}
# 2. 在路由中使用
@app.get("/items/", dependencies=[Depends(pagination)])
def list_items(page: dict = Depends(pagination)):
return {"items": ["item1", "item2"], "page_info": page}
@app.get("/me")
def read_me(current_user: dict = Depends(get_current_user)):
return current_user💡 依赖可以嵌套，FastAPI 会自动解析调用顺序。支持同步和异步 (
async def)。
📁 五、工程化项目结构（生产推荐）
不要把所有代码塞进 main.py。推荐结构：
my_api/
├── app/
│ ├── __init__.py
│ ├── main.py # FastAPI 实例、路由挂载、生命周期事件
│ ├── config.py # 环境变量配置 (pydantic-settings)
│ ├── dependencies.py # 全局依赖 (DB Session, Auth 等)
│ ├── models/ # Pydantic Schemas (请求/响应模型)
│ ├── routers/ # 业务路由拆分
│ │ ├── users.py
│ │ └── items.py
│ └── services/ # 业务逻辑层 (与路由解耦)
├── tests/ # 单元测试 & 集成测试
├── .env # 环境变量
└── pyproject.toml # 依赖管理 (推荐 uv/poetry)app/main.py 示例：
from fastapi import FastAPI
from app.routers import users, items
app = FastAPI()
# 挂载子路由
app.include_router(users.router, prefix="/users", tags=["用户管理"])
app.include_router(items.router, prefix="/items", tags=["商品管理"])
@app.get("/health")
def health_check():
return {"status": "ok"}路由拆分示例 app/routers/users.py：
from fastapi import APIRouter, Depends
from app.models.users import UserCreate, UserOut
router = APIRouter()
@router.post("/", response_model=UserOut)
def create_user(user: UserCreate):
return {"id": 1, **user.model_dump()}🧪 六、测试与部署
1. 自动化测试 (使用 httpx + pytest)
FastAPI 官方推荐用 TestClient 进行集成测试：
# tests/test_users.py
from fastapi.testclient import TestClient
from app.main import app
client = TestClient(app)
def test_create_user():
response = client.post("/users/", json={
"username": "testuser",
"email": "test@example.com",
"age": 25
})
assert response.status_code == 200
assert response.json()["username"] == "testuser"2. 生产部署
- 开发：
uvicorn main:app --reload - 生产：使用
Gunicorn+Uvicorn Workers管理进程
gunicorn app.main:app -w 4 -k uvicorn.workers.UvicornWorker -b 0.0.0.0:8000- Docker 示例：
FROM python:3.11-slim
WORKDIR /app
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt
COPY . .
CMD ["uvicorn", "app.main:app", "--host", "0.0.0.0", "--port", "8000"]🗺️ 七、进阶学习路线
掌握基础后，建议按以下顺序深入：
- 数据库集成：
SQLAlchemy 2.0+Alembic(迁移) 或直接使用 FastAPI 作者推荐的SQLModel - 认证授权：
OAuth2PasswordBearer+ JWT 实现登录/刷新令牌 - 后台任务：
BackgroundTasks或接入Celery/ARQ - 中间件 & 生命周期：CORS、请求耗时统计、全局异常处理 (
@app.exception_handler) - 性能优化：异步数据库驱动 (
asyncpg,aiosqlite)、连接池配置、缓存 (Redis)
📚 官方资源
- 📘 官方文档（极其优秀，必读）：https://fastapi.tiangolo.com/zh/
- 🐙 GitHub 源码与示例：https://github.com/tiangolo/fastapi
- 🔍 Pydantic V2 文档：https://docs.pydantic.dev/latest/
如果你在搭建过程中遇到具体问题（例如：如何连接 PostgreSQL、如何实现 JWT 登录、如何处理文件上传），告诉我你的场景，我可以提供完整可运行的代码片段！
