错误写法 ❌
从Django到FastAPI：我的Python后端新旅程
初识FastAPI的契机
那是一个项目重启的日子。我们团队之前用的是Django + DRF（Django REST framework）搭建的一套后端系统，虽然功能齐全、社区活跃，但随着接口调用频率的提升，性能瓶颈逐渐显现。尤其是在某些高并发场景下，接口响应时间不稳定，调试也变得越来越复杂。
更头疼的是，前端团队频繁要求接口文档更新，而Swagger/OpenAPI 的支持在 Django 生态中并不是原生且流畅的体验。我们尝试了 drf-yasg，但在复杂模型和动态路径参数的情况下经常出错，维护成本很高。
就在这个时候，我偶然听说了一个叫 FastAPI 的框架，官方宣传语是 “现代的、快速（高性能）的 Web 框架，用于构建 API，基于 Python 类型提示”。听起来很诱人：快？有类型检查？自动生成接口文档？这些可都是我们亟需解决的问题。
于是我决定带着好奇心试试看，在一个小型内部服务里做一个技术验证。
项目背景与挑战
这个内部服务叫做 UserAction Tracker，主要用来记录用户在前端页面上的点击行为，比如“点击了登录按钮”、“打开了某个弹窗”等等，用于后续的数据分析和产品优化。
它的核心需求包括：
- 接收前端发送的行为事件（POST）
- 对事件做格式校验
- 写入数据库
- 提供简单的查询接口（按时间、用户ID等条件）
看起来很简单对吧？但现实并不总是理想状态，我们很快遇到了几个问题：
- 接口文档不一致：前端每次发请求都要找对应的字段说明，开发效率低；
- 数据校验繁琐：需要手动写大量 if-else 校验逻辑，容易遗漏；
- 性能瓶颈初现：在测试环境中模拟500并发请求时，平均响应时间超过预期；
- 维护成本上升：随着模型扩展，代码结构臃肿，难以阅读和维护。
所以，我们决定把这个小项目作为 FastAPI 的试水实验，看看它是否真的如传说中那么好。
技术方案选型与实现思路
为什么选择FastAPI？
经过简单调研，我总结了 FastAPI 的几个关键优势：
- 基于 Starlette 构建，异步支持天然强
- 使用 Pydantic 做数据校验，类型安全
- 自动 OpenAPI 和 Swagger UI 文档生成
- 简洁的路由定义和依赖注入机制
这几点正好命中我们的痛点，特别是自动文档生成和类型校验。
整体架构设计
我们采用了如下架构：
FastAPI
│
├─ Models (Pydantic) ← 请求/响应数据结构定义
├─ Routes ← 路由处理逻辑
├─ Services ← 业务逻辑抽象层
├─ DAOs ← 数据访问层
├─ Database ← ORM 模型（SQLAlchemy 异步）
└─ Config ← 环境配置 & 启动项
这套分层设计让我们可以在不影响其他模块的情况下快速迭代某个部分，比如换数据库或者添加缓存。
实践中的代码片段和配置示例
1. 定义数据模型（Pydantic）
from pydantic import BaseModel, Field
from datetime import datetime
from typing import Optional
class UserActionRequest(BaseModel):
user_id: str = Field(..., example="user_123")
action_type: str = Field(..., example="button_click")
timestamp: datetime = Field(default_factory=datetime.utcnow)
extra_data: Optional[dict] = None
有了这个模型，FastAPI会自动完成请求参数解析和校验，如果客户端传错了字段或类型不符，就会直接返回错误，省去了大量的if-else判断。
2. 定义接口路由
from fastapi import APIRouter, Depends
from sqlalchemy.orm import Session
router = APIRouter()
@router.post("/actions")
def record_action(
action: UserActionRequest,
db: Session = Depends(get_db)
):
# 使用DAO保存到数据库
action_dao.create(db=db, obj_in=action)
return {"status": "success"}
这样的写法非常直观，而且路由会自动生成OpenAPI信息，前端可以直接查看可用的参数和示例。
3. 自动文档效果
启动服务后，访问 /docs 就可以打开交互式文档界面，像这样：
![FastAPI swagger示意图]
不仅能看到所有接口的参数说明，还可以在线发起测试请求。前端同事第一次看到的时候都惊呼：“终于不用去翻Postman集合啦！”
4. 异步数据库连接（SQLAlchemy + asyncpg）
我们用的是 SQLAlchemy（通过 sqlalchemy.ext.asyncio），配合 PostgreSQL + asyncpg：
from sqlalchemy.ext.asyncio import AsyncSession, create_async_engine
from sqlalchemy.orm import sessionmaker
DATABASE_URL = "postgresql+asyncpg://user:password@localhost/dbname"
engine = create_async_engine(DATABASE_URL, echo=True)
AsyncSessionLocal = sessionmaker(engine, class_=AsyncSession, expire_on_commit=False)
async def get_db():
async with AsyncSessionLocal() as session:
yield session
这样就能在FastAPI中轻松使用异步IO了，特别是在批量写入数据时节省了不少网络等待时间。
踩过的坑与经验教训
虽然FastAPI整体上手体验很好，但也并非完美无瑕。以下是我在开发过程中踩过的一些坑：
1. 异步编程习惯改变
原本我们习惯了同步方式操作数据库，但在FastAPI中要用异步的方式处理ORM。例如：
result = db.query(MyModel).all()
# 正确写法 ✅
result = await db.execute(select(MyModel))
一开始没注意，导致很多地方卡死在await关键字之外，CPU占用率奇高。后来统一约定所有数据库操作必须加async/await，并封装成DAO类避免混用。
2. Pydantic 版本兼容性问题
早期我们用了Pydantic v1版本，结果升级到v2之后很多字段定义方式变了，比如Field.default变成了Field(default=...)，一跑起来就报错。建议大家一开始就用最新的稳定版，否则版本混乱会让你欲哭无泪。
3. 日志输出混乱
刚开始部署生产环境时，日志输出特别乱，各种INFO、DEBUG、ERROR混在一起，根本看不出重点。后来统一引入 structlog，结构化日志让排查问题轻松很多。
上线后的效果和收益
将原有的Django小模块迁移到FastAPI之后，我们得到了以下几方面的收益：
| 指标 | 迁移前 | 迁移后 |
|---|---|---|
| 平均接口响应时间（单次请求） | ~80ms | ~25ms |
| 吞吐量（并发500） | ~600 RPS | ~1100 RPS |
| 开发效率（新接口开发） | 2人天 | 0.5人天 |
| 接口文档准确率 | 70%左右 | 100%自动同步 |
最关键的是，接口文档再也不用人工维护了，前后端沟通效率提升了至少两倍不止。
上线几个月后，我们又把另一个数据分析接口模块也迁了过来，结果同样令人满意。现在整个平台的核心API基本都迁到了FastAPI生态中。
给新手的建议与注意事项
如果你也是刚入门FastAPI，或者打算尝试转型，这里有几个建议送给你：
1. 先理解异步不是万能药
FastAPI虽然内置异步支持，但并不是所有业务场景都适合异步。尤其是涉及到大量计算任务的时候，GIL的存在会让效果大打折扣。合理使用才是王道。
2. 类型定义越早越好
FastAPI的强大之处在于类型驱动开发。Pydantic模型不仅是数据校验工具，也是API定义的重要组成部分。建议你从最开始就养成写Model的习惯。
3. 不要忽视依赖管理
FastAPI的依赖注入系统非常强大，不要图方便直接把db.session扔进函数里。合理使用 Depends() 可以大大增强代码的可测试性和可维护性。
4. 性能优化别只盯着框架
很多时候瓶颈不在FastAPI本身，而在你的业务逻辑、数据库设计甚至网络环境。建议结合压测工具（locust）、日志分析和慢查询监控来综合定位。
5. 关注社区和生态成熟度
FastAPI发展迅猛，很多生态组件也在快速迭代。记得定期关注GitHub仓库，或者加入相关社群讨论。比如我发现很多问题其实别人早就踩过了，直接看issue比自己debug快多了。
结语：技术是用来解决问题的
回想起当初那个犹豫要不要尝试FastAPI的晚上，其实我也曾纠结：“Django用得好好的，为什么要换？”但事实证明，面对不断变化的业务需求和技术挑战，拥抱新工具、探索新方法才是我们作为开发者该有的态度。
FastAPI并不仅仅是“一个新的Web框架”，它代表了一种更现代化的开发范式：类型安全、异步友好、文档自动生成、强调可维护性。这些东西看似细节，却在长线维护和团队协作中发挥了巨大的作用。
如果你也在寻找一种更轻量、更灵活的Python后端方案，不妨试一试FastAPI。它或许不会立刻成为你项目的唯一答案，但我相信，它会打开一扇通往更高效开发的大门。
最后送你一句话：
技术没有绝对的优劣，只有适不适合的场景。但总要去尝试才知道是不是你要的答案。
评论 0