FastAPI 入门：Python 后端开发新手指南

一开始，我也没想到会用上 FastAPI

去年我们公司有个内部工具需要快速搭建一个轻量级后端服务。原本打算用 Flask 搞个简单的 REST API 就行了，但项目负责人建议试试 FastAPI。我当时其实还有点犹豫——毕竟以前没怎么接触过，而且时间又紧。

不过随着项目的推进，我对 FastAPI 的认识逐渐加深，也越来越喜欢它。现在回头来看，我觉得对于想快速入门 Python 后端开发的朋友来说，FastAPI 真的是一种非常值得尝试的选择。这篇笔记就聊聊我的实战经验和心得体会，希望对你有帮助。

---

背景：为什么我们选用了 FastAPI？

我们当时要做的是一个数据看板平台的后端接口服务，主要负责接收前端请求、从数据库拉取数据、做初步的聚合处理并返回给前端展示。整个系统不需要复杂的业务逻辑，但对性能和响应速度有一定要求。

考虑到后续可能会对接 AI 分析模块，所以我们也希望后端能支持异步请求（比如调用模型推理接口），这成了我们选择技术栈的重要参考因素之一。

最终选择了 FastAPI，主要是因为：

• 内置对异步的支持
• 性能接近 Node.js 和 Go（相比 Flask 提升明显）
• 自动生成 OpenAPI 文档，调试方便
• 强类型语法支持（Python 3.8+）
• 社区活跃，文档清晰

事实证明，这个选择真的没有错。

---

遇到的问题和挑战

挑战一：新手如何快速上手？

虽然 Python 是一门相对容易上手的语言，但对于刚入行的后端开发者来说，要快速写出结构清晰、可维护性好的 FastAPI 应用并不是一件简单的事情。特别是在组织代码结构、设计路由、连接数据库这些地方，很容易踩坑。

刚开始写的时候，我一股脑地把所有逻辑都堆在 main.py 里面，后来加了几个功能以后根本看不懂自己写的是啥 😅。直到请教了组里的前辈才意识到模块化的重要性。

挑战二：性能优化怎么做？

虽然 FastAPI 宣称性能好，但如果你不注意，比如频繁操作数据库、或者阻塞式地处理任务，照样卡得飞起。我们在初期测试阶段就遇到了接口响应慢、并发性能差的问题。

挑战三：异步编程不熟练？

FastAPI 支持 async/await 语法，但我们团队之前大部分都是同步开发经验，刚开始写异步函数时常常忘记加上 await，导致程序跑不起来。有些异步库使用方式也和同步不太一样，增加了学习成本。

---

我们的解决方案与实现思路

为了解决这些问题，我们采取了以下几项关键措施：

结构化项目架构

为了避免“一锅乱炖”，我们采用了一个基础目录结构：

myproject/
│
├── app/
│   ├── __init__.py
│   ├── main.py
│   ├── routers/
│   │   └── data.py
│   ├── models/
│   │   └── user.py
│   ├── schemas/
│   │   └── user.py
│   ├── database/
│   │   └── database.py
│   └── utils/
│       └── helper.py
│
└── requirements.txt

这样的结构让我们能更清晰地管理模块，提高复用性和可测试性。

使用 SQLAlchemy + Asyncpg 异步 ORM

我们使用 SQLAlchemy 作为 ORM 层，并结合 asyncpg 来支持异步数据库操作。这样既能保持 SQL 的灵活性，又能避免阻塞主线程。

示例配置如下：

from sqlalchemy.ext.asyncio import create_async_engine, AsyncSession
from sqlalchemy.orm import sessionmaker
from sqlalchemy.ext.declarative import declarative_base

DATABASE_URL = "postgresql+asyncpg://user:password@localhost/mydb"

engine = create_async_engine(DATABASE_URL, echo=True)
AsyncDBSession = sessionmaker(engine, class_=AsyncSession, expire_on_commit=False)

Base = declarative_base()

引入 Pydantic 做数据校验

FastAPI 内置对 Pydantic 的支持，我们在每一个接口中都使用了输入输出模型进行数据校验，既保证了接口安全，也能提升前后端协作效率。

比如用户注册接口：

from pydantic import BaseModel
from typing import Optional

class UserCreate(BaseModel):
    email: str
    password: str
    name: Optional[str] = None

class UserOut(BaseModel):
    id: int
    email: str
    name: Optional[str]

    class Config:
        orm_mode = True

然后 FastAPI 会自动帮你校验请求体是否符合预期。

---

实战代码片段分享

下面是一个真实的路由接口代码例子：

# app/routers/data.py

from fastapi import APIRouter, Depends, HTTPException
from sqlalchemy.ext.asyncio import AsyncSession
from app.database.database import AsyncDBSession
from app.models.data_model import DataRecord
from app.schemas.data_schema import DataResponse
from typing import List

router = APIRouter(prefix="/data", tags=["Data"])

@router.get("/{record_id}", response_model=DataResponse)
async def get_data_by_id(record_id: int, db: AsyncSession = Depends(AsyncDBSession)):
    result = await db.get(DataRecord, record_id)
    if not result:
        raise HTTPException(status_code=404, detail="Record not found")
    return result

再看一段异步数据库操作的 Model 定义：

# app/models/data_model.py

from sqlalchemy import Column, Integer, String, DateTime
from datetime import datetime
from app.database.database import Base

class DataRecord(Base):
    __tablename__ = 'data_records'
    
    id = Column(Integer, primary_key=True)
    content = Column(String)
    created_at = Column(DateTime, default=datetime.utcnow)

有了这些结构，你只需要在 main.py 里挂载 router：

# app/main.py

from fastapi import FastAPI
from app.routers import data

app = FastAPI()

app.include_router(data.router)

---

踩过的坑和解决办法

坑1：忘了加 await 导致程序卡住

刚开始写异步代码的时候，很容易忘记加 await，比如调用了一个异步方法但是没等结果就继续执行了。

解决方法：多写单元测试，特别是异步函数的测试；另外借助 IDE（比如 VSCode）的 linting 功能，可以提醒你是否有未 await 的协程。

坑2：数据库连接池太小导致并发瓶颈

我们最开始用默认设置运行，但在压力测试时发现，当并发数达到几十以上时，响应变得很慢。

原因是我们没有设置足够大的连接池。后来改成这样：

engine = create_async_engine(
    DATABASE_URL,
    pool_size=20,     # 连接池大小
    max_overflow=10,  # 可额外创建的连接数量
    pool_recycle=3600, # 一小时回收一次连接
    echo=True
)

这个问题才得以缓解。

坑3：OpenAPI 文档路径被占用 / 访问不到

有时候部署之后 /docs 页面打不开。检查一下是不是路径冲突了，比如有人把 GET /docs 占用了。另外确保你部署的服务器（例如 Nginx）没有拦截掉这些路径。

---

实施后的效果和收益

经过一系列调整后，我们的服务在上线后表现非常稳定。主要收益包括：

• 开发效率高了很多：得益于自动生成文档和强类型约束，前后端沟通几乎零误差。
• 性能比 Flask 好不少：在压测中，单机 QPS 达到 2000+，平均响应时间控制在 30ms 左右。
• 维护成本低：模块化的代码结构让后期新增功能变得轻松很多。
• 易于扩展：后续引入 AI 推理接口时，异步特性帮了大忙，几乎无缝集成。

---

给新手的一些建议和注意事项

✅ 从一个清晰的项目结构开始

别想着先“搞定功能”再说，结构混乱会让你后面付出更高代价。FastAPI 官网上的示例结构就很清晰，不妨直接照着学。

✅ 多写 Pydantic 模型

别图省事直接在接口里用字典或原始类型传参。Pydantic 模型不仅能帮你做数据校验，还能生成 OpenAPI 文档说明字段含义。

✅ 重视异步编程的学习

即使你现在做的只是一个简单的服务，掌握异步编程思想对未来非常重要。AI、大数据、IoT 等场景都会用到异步能力。

✅ 别迷信“框架很牛就一定能快”

任何框架都需要合理使用，否则性能反而可能不如预期。比如数据库操作还是要注意避免 N+1 查询问题，必要时使用缓存（如 Redis）降低负载。

✅ 上生产前一定做好测试和监控

我们是在某个版本上线后才发现内存泄漏问题的。后来我们加上 Prometheus + Grafana 监控服务指标，还写了自动化测试用例来保障质量。

---

最后的小结

FastAPI 是目前 Python 后端生态中最值得投入学习的框架之一。它不仅性能优越，还具备良好的开发体验和文档生态。对于刚入行的开发者来说，它是很好的起点，而对于有经验的人来说，它也是一个强大而灵活的选择。

在这个项目中，我最大的体会是：一个好的后端服务不是写出来的，而是设计和打磨出来的。FastAPI 给了我们一个很棒的基础，剩下的就需要我们用心去规划结构、优化性能、关注细节。

希望这篇文章能帮你在学习 FastAPI 的路上少走些弯路，早点写出优雅高效的后端服务！

---

如果你也在使用 FastAPI，欢迎留言交流～一起探索更高效的后端开发方式！