FastAPI 实战：构建高效待办事项 Web API 的增删改查系统

一、FastAPI 框架简介与优势

FastAPI 是一个基于 Python 的现代 Web 框架，利用类型注解和异步支持，能够快速构建高性能的 API 服务。其核心优势在于：

1. 开发效率高：基于 Python 类型提示，自动生成 API 文档（Swagger UI 和 ReDoc），减少手动编写文档的时间。
2. 性能卓越：基于 Starlette 和 Pydantic，支持异步请求处理，性能接近 Node.js 和 Go。
3. 数据验证便捷：通过 Pydantic 模型实现请求/响应数据的自动校验和序列化。
4. 依赖注入灵活：支持通过 Depends 实现依赖管理，简化路由逻辑。

在待办事项（Todo）管理场景中，FastAPI 的类型安全和自动文档功能能显著提升开发效率，尤其适合快速迭代的 CRUD（增删改查）需求。

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

1. 环境准备

• Python 3.7+：FastAPI 依赖 Python 的类型注解功能。
• 依赖安装：

  pip install fastapi uvicorn pydantic

  • fastapi：核心框架。
  • uvicorn：ASGI 服务器，用于运行应用。
  • pydantic：数据模型验证库。

2. 项目结构

todo_api/
├── main.py          # 主应用入口
├── models.py        # 数据模型定义
├── schemas.py       # Pydantic 模式（请求/响应结构）
└── routers/         # 路由模块（可选）
    └── todos.py     # 待办事项路由

三、数据模型与模式设计

1. 数据模型（Models）

使用 pydantic.BaseModel 定义待办事项的数据结构：

from pydantic import BaseModel
from typing import Optional
class Todo(BaseModel):
    id: Optional[int] = None  # 可选，数据库自动生成时使用
    title: str
    description: Optional[str] = None
    completed: bool = False

• 字段说明：
  • id：唯一标识，数据库生成时可设为可选。
  • title：必填，待办事项标题。
  • description：可选，详细描述。
  • completed：布尔值，标记完成状态。

2. 请求/响应模式（Schemas）

分离请求和响应模式以提高灵活性：

from pydantic import BaseModel
class TodoCreate(BaseModel):
    title: str
    description: str = None
class TodoUpdate(BaseModel):
    title: str = None
    description: str = None
    completed: bool = None

• 设计原则：
  • TodoCreate：仅包含创建时必需的字段。
  • TodoUpdate：允许部分更新，字段为可选。

四、实现 CRUD 路由

1. 初始化 FastAPI 应用

from fastapi import FastAPI
app = FastAPI()

2. 内存存储模拟（替代数据库）

from typing import Dict, List
# 模拟数据库
todos_db: Dict[int, Todo] = {}
current_id = 1

3. 创建待办事项（POST /todos/）

from fastapi import HTTPException
@app.post("/todos/", response_model=Todo)
def create_todo(todo: TodoCreate):
    global current_id
    new_todo = Todo(id=current_id, **todo.dict())
    todos_db[current_id] = new_todo
    current_id += 1
    return new_todo

• 关键点：
  • 使用 response_model 自动序列化响应。
  • **todo.dict() 将 Pydantic 模型转为字典。

4. 读取所有待办事项（GET /todos/）

@app.get("/todos/", response_model=List[Todo])
def read_todos():
    return list(todos_db.values())

5. 读取单个待办事项（GET /todos/{todo_id}）

@app.get("/todos/{todo_id}", response_model=Todo)
def read_todo(todo_id: int):
    if todo_id not in todos_db:
        raise HTTPException(status_code=404, detail="Todo not found")
    return todos_db[todo_id]

• 错误处理：使用 HTTPException 返回 404 状态码。

6. 更新待办事项（PUT /todos/{todo_id}）

@app.put("/todos/{todo_id}", response_model=Todo)
def update_todo(todo_id: int, todo_update: TodoUpdate):
    if todo_id not in todos_db:
        raise HTTPException(status_code=404, detail="Todo not found")
    # 获取现有数据并部分更新
    todo_data = todos_db[todo_id].dict()
    update_data = todo_update.dict(exclude_unset=True)  # 仅更新非空字段
    updated_todo = Todo(**{**todo_data, **update_data})
    todos_db[todo_id] = updated_todo
    return updated_todo

• 技巧：exclude_unset=True 避免覆盖未修改的字段。

7. 删除待办事项（DELETE /todos/{todo_id}）

@app.delete("/todos/{todo_id}")
def delete_todo(todo_id: int):
    if todo_id not in todos_db:
        raise HTTPException(status_code=404, detail="Todo not found")
    del todos_db[todo_id]
    return {"message": "Todo deleted successfully"}

五、路由组织与模块化

1. 使用 APIRouter 拆分路由

创建 routers/todos.py：

from fastapi import APIRouter, HTTPException
from typing import Dict, List
from ..models import Todo
from ..schemas import TodoCreate, TodoUpdate
router = APIRouter(prefix="/todos", tags=["todos"])
todos_db: Dict[int, Todo] = {}
current_id = 1
@router.post("/", response_model=Todo)
def create_todo(todo: TodoCreate):
    # ...（同上）
# 其他路由类似...

2. 在主应用中注册路由

from fastapi import FastAPI
from routers import todos
app = FastAPI()
app.include_router(todos.router)

六、运行与测试

1. 启动服务

uvicorn main:app --reload

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

2. 测试 API

• Swagger UI：访问 http://127.0.0.1:8000/docs 交互式测试。

• cURL 示例：

  # 创建待办事项
  curl -X POST "http://127.0.0.1:8000/todos/" \
  -H "Content-Type: application/json" \
  -d '{"title": "Learn FastAPI", "description": "Build a Todo API"}'
  # 获取所有待办事项
  curl "http://127.0.0.1:8000/todos/"

七、进阶优化建议

1. 数据库集成：替换内存存储为 SQLAlchemy + PostgreSQL。
2. 身份验证：添加 JWT 认证保护路由。
3. 分页支持：为 GET /todos/ 添加分页参数。
4. 异步支持：使用 async/await 处理 I/O 密集型操作。

八、总结

通过 FastAPI，我们快速实现了一个功能完整的待办事项 CRUD API，涵盖了从路由设计到错误处理的全部流程。其类型安全、自动文档和异步支持特性，使得开发效率远超传统框架。下一步可结合数据库和前端框架（如 React/Vue）构建全栈应用。