1. 项目概述：用FastAPI构建待办事项API

去年接手公司内部任务管理系统重构时，我首次将FastAPI用于生产环境。这个Python框架的自动文档生成和类型提示让我在两周内就交付了核心API，比原计划提前了40%。今天要分享的待办事项API项目，正是基于那次实战经验提炼出的最佳实践模板。

这个项目完整演示了如何用FastAPI实现标准的RESTful路由操作：

• 创建虚拟环境隔离依赖
• 设计符合OpenAPI规范的端点
• 实现增删改查(CRUD)业务逻辑
• 集成Pydantic模型验证
• 自动生成交互式API文档

特别适合有以下需求的开发者：

1. 需要快速搭建原型系统的创业团队
2. 想从Flask/Django转型到现代API框架的工程师
3. 学习异步Web开发的Python程序员

2. 环境配置与项目初始化

2.1 开发环境准备

推荐使用PyCharm Professional或VS Code作为IDE，它们对FastAPI的调试支持最为完善。我实测Python 3.8-3.10版本兼容性最好，3.11+可能存在某些依赖包兼容问题。

创建虚拟环境并安装核心依赖：

python -m venv venv source venv/bin/activate # Linux/Mac venv\Scripts\activate.bat # Windows pip install fastapi==0.95.2 pip install "uvicorn[standard]"==0.22.0 pip install pydantic==1.10.7

注意：避免混用pip和pipenv，我在多个项目中遇到过依赖冲突。坚持使用纯pip+requirements.txt是最稳定的方案。

2.2 项目结构设计

经过多个生产项目验证，推荐采用这种可扩展的结构：

/todo_api ├── /app │ ├── __init__.py │ ├── main.py # 应用入口 │ ├── models.py # Pydantic模型 │ ├── database.py # 数据库连接 │ └── /routes │ ├── __init__.py │ └── todos.py # 待办事项路由 ├── requirements.txt └── .env # 环境变量

这种结构后期可以轻松扩展为：

• 添加auth路由
• 支持多数据库配置
• 实现单元测试模块

3. 核心实现解析

3.1 数据模型设计

在app/models.py中定义核心数据结构：

from pydantic import BaseModel from typing import Optional class TodoCreate(BaseModel): title: str description: Optional[str] = None completed: bool = False class TodoUpdate(BaseModel): title: Optional[str] = None description: Optional[str] = None completed: Optional[bool] = None class Todo(TodoCreate): id: int

Pydantic模型带来三大优势：

1. 自动数据验证（如title必须为字符串）
2. 请求/响应数据转换
3. 完善的IDE类型提示

3.2 内存数据库实现

为简化演示，使用内存字典模拟数据库。实际项目可替换为SQLAlchemy或Tortoise-ORM。

# app/database.py from typing import Dict todos_db: Dict[int, dict] = {} current_id = 0 def get_next_id(): global current_id current_id += 1 return current_id

踩坑提醒：生产环境务必添加线程锁，我在高并发场景下遇到过ID重复问题。

3.3 路由控制器实现

完整CRUD路由示例（app/routes/todos.py）：

from fastapi import APIRouter, HTTPException from app.models import Todo, TodoCreate, TodoUpdate from app.database import todos_db, get_next_id router = APIRouter(prefix="/todos", tags=["todos"]) @router.post("/", response_model=Todo) async def create_todo(todo: TodoCreate): todo_id = get_next_id() todos_db[todo_id] = { "id": todo_id, **todo.dict() } return todos_db[todo_id] @router.get("/{todo_id}", response_model=Todo) async 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] @router.put("/{todo_id}", response_model=Todo) async def update_todo(todo_id: int, todo: TodoUpdate): if todo_id not in todos_db: raise HTTPException(status_code=404, detail="Todo not found") stored_todo = todos_db[todo_id] update_data = todo.dict(exclude_unset=True) updated_todo = {**stored_todo, **update_data} todos_db[todo_id] = updated_todo return updated_todo @router.delete("/{todo_id}") async 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"}

关键设计要点：

1. 使用APIRouter实现模块化路由
2. 每个端点都有明确的response_model
3. 错误处理遵循HTTP语义
4. PUT操作实现部分更新

4. 高级功能与优化

4.1 异步数据库访问

内存数据库改为异步版本：

# app/database.py import asyncio from typing import Dict todos_db: Dict[int, dict] = {} current_id = 0 lock = asyncio.Lock() async def get_next_id(): global current_id async with lock: current_id += 1 return current_id

对应路由需要添加async/await：

@router.post("/", response_model=Todo) async def create_todo(todo: TodoCreate): todo_id = await get_next_id() todos_db[todo_id] = { "id": todo_id, **todo.dict() } return todos_db[todo_id]

4.2 依赖注入优化

提取公共的todo_id验证逻辑：

from fastapi import Depends async def get_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] @router.put("/{todo_id}", response_model=Todo) async def update_todo( todo: TodoUpdate, stored_todo: dict = Depends(get_todo) ): update_data = todo.dict(exclude_unset=True) updated_todo = {**stored_todo, **update_data} todos_db[stored_todo["id"]] = updated_todo return updated_todo

这种模式的优势：

1. 减少重复代码
2. 便于统一修改验证逻辑
3. 提高代码可测试性

5. 常见问题排查

5.1 调试技巧

当路由不生效时，按以下步骤排查：

1. 检查router是否正确注册到app
2. 确认路径前缀(prefix)是否冲突
3. 使用app.openapi()查看生成的OpenAPI文档

调试请求的小技巧：

import logging logging.basicConfig(level=logging.DEBUG) @router.post("/") async def create_todo(todo: TodoCreate): logging.debug(f"Received todo: {todo}") ...

5.2 性能优化

针对高并发场景的三个建议：

1. 使用@router.api_route合并相同路径的不同方法
2. 对GET请求添加缓存头

from fastapi import Response @router.get("/{todo_id}") async def read_todo(todo_id: int, response: Response): response.headers["Cache-Control"] = "max-age=60" ...

3. 启用Gzip压缩中间件

from fastapi.middleware.gzip import GZipMiddleware app.add_middleware(GZipMiddleware)

6. 项目扩展方向

这个基础模板可以进一步扩展为：

1. 用户认证系统（JWT/OAuth2）
2. 数据库迁移（Alembic）
3. 后台任务（Celery）
4. WebSocket实时更新
5. 自动化测试（pytest）

我在实际项目中最常添加的是Redis缓存层，能显著提升API响应速度。一个简单的实现示例：

from fastapi_cache import FastAPICache from fastapi_cache.backends.redis import RedisBackend @app.on_event("startup") async def startup(): FastAPICache.init(RedisBackend("redis://localhost"))