FastAPI 快速开发 Web API 项目：实现待办事项路由增删改查

FastAPI 作为一款基于 Python 的高性能 Web 框架，凭借其自动生成 API 文档、类型注解支持和异步请求处理能力，已成为开发 RESTful API 的首选工具。本文将以待办事项管理为例，详细讲解如何使用 FastAPI 实现完整的 CRUD（增删改查）路由功能，涵盖从环境配置到路由设计的全流程。

一、项目初始化与环境配置

1.1 创建虚拟环境与依赖安装

首先，通过 Python 内置的 venv 模块创建隔离环境，避免依赖冲突：

python -m venv fastapi_todo_env
source fastapi_todo_env/bin/activate  # Linux/macOS
# 或 fastapi_todo_env\Scripts\activate (Windows)

安装 FastAPI 及其依赖：

pip install fastapi uvicorn

• fastapi：核心框架，提供路由、请求/响应处理等功能。
• uvicorn：ASGI 服务器，用于运行 FastAPI 应用。

1.2 项目结构规划

合理的项目结构能提升代码可维护性。推荐采用以下分层设计：

todo_api/
├── main.py          # 入口文件
├── models.py        # 数据模型（如待办事项的 Pydantic 模型）
├── routers/         # 路由模块
│   └── todo.py      # 待办事项路由
└── requirements.txt # 依赖列表

二、数据模型设计（Pydantic 模型）

2.1 定义待办事项模型

使用 Pydantic 的 BaseModel 定义数据结构，确保类型安全与自动文档生成：

# models.py
from pydantic import BaseModel
from typing import Optional
class TodoItem(BaseModel):
    id: Optional[int] = None  # 可选，用于更新时忽略
    title: str
    description: Optional[str] = None
    completed: bool = False

• Optional[int]：允许 id 为空，新增时无需提供。
• 自动生成 OpenAPI 文档中的字段描述。

2.2 模拟数据存储

为简化示例，使用内存列表模拟数据库：

# 在 routers/todo.py 中初始化
todos = []  # 存储待办事项的列表

三、路由设计与实现（CRUD 操作）

3.1 创建路由模块

在 routers/todo.py 中定义所有待办事项相关路由：

from fastapi import APIRouter, HTTPException
from typing import List
from models import TodoItem
router = APIRouter(prefix="/todos", tags=["todos"])
todos = []  # 模拟数据库
@router.post("/")
def create_todo(todo: TodoItem):
    if todo.id is None:
        todo.id = len(todos) + 1  # 简单自增 ID
    todos.append(todo)
    return {"message": "Todo created", "todo": todo}
@router.get("/", response_model=List[TodoItem])
def get_all_todos():
    return todos
@router.get("/{todo_id}", response_model=TodoItem)
def get_todo(todo_id: int):
    todo = next((t for t in todos if t.id == todo_id), None)
    if todo is None:
        raise HTTPException(status_code=404, detail="Todo not found")
    return todo
@router.put("/{todo_id}", response_model=TodoItem)
def update_todo(todo_id: int, updated_todo: TodoItem):
    for index, todo in enumerate(todos):
        if todo.id == todo_id:
            todos[index] = updated_todo  # 覆盖更新
            return updated_todo
    raise HTTPException(status_code=404, detail="Todo not found")
@router.delete("/{todo_id}")
def delete_todo(todo_id: int):
    global todos
    todos = [t for t in todos if t.id != todo_id]
    return {"message": "Todo deleted"}

3.2 路由详解

• POST /todos/：新增待办事项，自动分配 ID。
• GET /todos/：返回所有待办事项列表。
• GET /todos/{todo_id}：根据 ID 查询单个事项，未找到返回 404。
• PUT /todos/{todo_id}：完全替换指定 ID 的事项（需提供完整字段）。
• DELETE /todos/{todo_id}：删除指定事项。

3.3 路由集成到主应用

在 main.py 中加载路由模块：

from fastapi import FastAPI
from routers.todo import router as todo_router
app = FastAPI()
app.include_router(todo_router)
@app.get("/")
def read_root():
    return {"message": "Welcome to the Todo API"}

四、运行与测试

4.1 启动服务

使用 Uvicorn 运行应用：

uvicorn main:app --reload

• --reload：开发模式下自动重载代码变更。

4.2 测试 API

访问 http://127.0.0.1:8000/docs 查看自动生成的 Swagger UI 文档，或通过 curl 测试：

# 新增待办事项
curl -X POST "http://127.0.0.1:8000/todos/" \
-H "Content-Type: application/json" \
-d '{"title": "Learn FastAPI", "description": "Complete the tutorial"}'
# 查询所有待办事项
curl "http://127.0.0.1:8000/todos/"

五、进阶优化建议

5.1 数据库集成

将内存列表替换为真实数据库（如 SQLite、PostgreSQL）：

# 使用 SQLModel 或 Tortoise-ORM 示例
from sqlmodel import SQLModel, Field, Session, create_engine
class Todo(SQLModel, table=True):
    id: Optional[int] = Field(default=None, primary_key=True)
    title: str
    completed: bool = False
engine = create_engine("sqlite:///todos.db")
SQLModel.metadata.create_all(engine)

5.2 依赖注入与异步支持

使用 FastAPI 的 Depends 实现依赖注入，提升代码复用性：

from fastapi import Depends
def get_db():
    db = Session(engine)  # 实际需处理连接池
    try:
        yield db
    finally:
        db.close()
@router.get("/")
def get_all_todos(db: Session = Depends(get_db)):
    return db.query(Todo).all()

5.3 输入验证与错误处理

通过 Pydantic 模型自动验证输入，并自定义异常处理：

from fastapi import Request
from fastapi.responses import JSONResponse
from fastapi.exceptions import HTTPException
@app.exception_handler(HTTPException)
async def http_exception_handler(request: Request, exc: HTTPException):
    return JSONResponse(
        status_code=exc.status_code,
        content={"message": exc.detail},
    )

六、总结与最佳实践

1. 路由设计：遵循 RESTful 原则，使用清晰的路径和 HTTP 方法。
2. 数据模型：利用 Pydantic 确保类型安全，减少手动验证。
3. 错误处理：统一异常响应格式，提升 API 可用性。
4. 文档生成：FastAPI 自动生成的 OpenAPI 文档可替代手动编写 API 文档。
5. 扩展性：模块化设计便于后续添加用户认证、日志记录等功能。

通过本文的实践，开发者已掌握 FastAPI 的核心功能，能够快速构建结构清晰、性能优异的 Web API。下一步可探索中间件、背景任务等高级特性，进一步提升应用能力。