FastAPI快速开发Web API：待办事项路由增删改查实战指南

FastAPI作为新一代Python Web框架，以其高性能、自动生成API文档和类型提示支持等特性，成为构建现代Web API的首选工具。本文将通过一个完整的待办事项管理案例，深入解析如何使用FastAPI实现CRUD（增删改查）功能的路由设计，帮助开发者快速掌握核心开发技巧。

一、项目初始化与基础配置

1.1 环境搭建

使用Python 3.8+环境，通过pip安装FastAPI和Uvicorn（ASGI服务器）：

pip install fastapi uvicorn

项目目录结构建议如下：

todo_api/
├── main.py          # 主入口
├── models.py        # 数据模型
├── schemas.py       # 数据验证
├── crud.py          # 数据操作
└── requirements.txt # 依赖管理

1.2 基础应用创建

在main.py中初始化FastAPI应用：

from fastapi import FastAPI
app = FastAPI(
    title="待办事项API",
    version="1.0.0",
    description="基于FastAPI的待办事项管理系统"
)
@app.get("/")
def read_root():
    return {"message": "欢迎使用待办事项API"}

运行应用：

uvicorn main:app --reload

访问http://127.0.0.1:8000/docs即可查看自动生成的交互式API文档。

二、数据模型设计

2.1 Pydantic模型定义

在schemas.py中定义请求/响应数据结构：

from pydantic import BaseModel
from typing import Optional
from datetime import datetime
class TodoItem(BaseModel):
    title: str
    description: Optional[str] = None
    completed: bool = False
    created_at: datetime = datetime.now()
class TodoUpdate(BaseModel):
    title: Optional[str] = None
    description: Optional[str] = None
    completed: Optional[bool] = None

2.2 内存数据存储（简化版）

实际项目中建议使用数据库，这里使用字典模拟：

# crud.py
from typing import Dict, Optional
from schemas import TodoItem
db: Dict[int, TodoItem] = {}
counter = 0
def create_todo(todo: TodoItem) -> Dict[str, int]:
    global counter
    new_id = counter
    counter += 1
    db[new_id] = todo
    return {"id": new_id}
def get_todo(todo_id: int) -> Optional[TodoItem]:
    return db.get(todo_id)
# 其他CRUD操作...

三、路由设计与实现

3.1 创建待办事项（POST）

from fastapi import APIRouter, HTTPException
from schemas import TodoItem
import crud
router = APIRouter(prefix="/todos", tags=["todos"])
@router.post("/")
def create_todo(todo: TodoItem):
    result = crud.create_todo(todo)
    return {"id": result["id"], **todo.dict()}

3.2 查询待办事项（GET）

3.2.1 查询单个

@router.get("/{todo_id}")
def read_todo(todo_id: int):
    todo = crud.get_todo(todo_id)
    if todo is None:
        raise HTTPException(status_code=404, detail="待办事项不存在")
    return todo

3.2.2 查询所有（带分页）

from fastapi import Query
@router.get("/")
def read_todos(
    skip: int = Query(0, ge=0),
    limit: int = Query(10, le=100)
):
    return list(db.values())[skip:skip+limit]

3.3 更新待办事项（PUT/PATCH）

@router.put("/{todo_id}")
def update_todo(todo_id: int, updated_todo: TodoUpdate):
    existing = crud.get_todo(todo_id)
    if not existing:
        raise HTTPException(404)
    # 合并更新字段
    update_data = updated_todo.dict(exclude_unset=True)
    for field, value in update_data.items():
        setattr(existing, field, value)
    return existing

3.4 删除待办事项（DELETE）

@router.delete("/{todo_id}")
def delete_todo(todo_id: int):
    if todo_id not in db:
        raise HTTPException(404)
    del db[todo_id]
    return {"message": "删除成功"}

四、高级功能实现

4.1 依赖注入与路径操作

使用FastAPI的Depends实现认证：

from fastapi import Depends, Header
def get_token_header(x_token: str = Header(...)):
    if x_token != "secret-token":
        raise HTTPException(403)
    return x_token
@router.get("/secure/", dependencies=[Depends(get_token_header)])
def secure_endpoint():
    return {"message": "认证通过"}

4.2 异步操作支持

修改CRUD操作使用异步：

# 模拟异步数据库操作
async def async_create_todo(todo: TodoItem):
    await asyncio.sleep(0.1)  # 模拟I/O操作
    return create_todo(todo)
@router.post("/async/")
async def create_todo_async(todo: TodoItem):
    result = await async_create_todo(todo)
    return result

4.3 响应模型定制

使用response_model控制返回字段：

from fastapi import Response
@router.get("/{todo_id}/simple", response_model=TodoItem)
def get_simple_todo(todo_id: int):
    todo = crud.get_todo(todo_id)
    if not todo:
        raise HTTPException(404)
    # 这里可以处理敏感字段
    return todo

五、完整项目整合

将所有路由整合到主应用：

# main.py
from fastapi import FastAPI
from routes.todo_router import router as todo_router
app = FastAPI()
app.include_router(todo_router)
@app.get("/")
def read_root():
    return {"message": "待办事项API v1.0"}

六、测试与部署

6.1 使用TestClient测试

# tests/test_main.py
from fastapi.testclient import TestClient
from main import app
client = TestClient(app)
def test_create_todo():
    response = client.post(
        "/todos/",
        json={"title": "测试事项", "description": "测试描述"}
    )
    assert response.status_code == 200
    assert "id" in response.json()

6.2 生产环境部署

使用Docker容器化部署：

# Dockerfile
FROM python:3.9-slim
WORKDIR /app
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt
COPY . .
CMD ["uvicorn", "main:app", "--host", "0.0.0.0", "--port", "8000"]

七、最佳实践建议

1. 分层架构：保持路由、服务、数据层的分离
2. 类型提示：充分利用Python类型系统提高代码可靠性
3. 文档完善：为每个路由添加详细的描述和示例
4. 错误处理：统一异常处理机制
5. 性能优化：对耗时操作使用异步

八、扩展方向

1. 集成SQLite/PostgreSQL等真实数据库
2. 添加JWT认证
3. 实现WebSocket实时通知
4. 添加速率限制中间件
5. 实现多版本API支持

通过本文的完整实现，开发者可以快速掌握FastAPI的核心开发模式，构建出高性能、易维护的Web API服务。实际项目中，建议结合具体业务需求进行功能扩展和优化。