FastAPI 搭建 RESTful API 全记录

最近用 FastAPI 给一个内部工具搭了组接口，体验出乎意料地好。相较于之前用的 Flask + 手动校验，FastAPI 的开发效率确实高出一截。

为什么选 FastAPI

团队本来倾向于继续用 Flask，但评估了以下需求之后，FastAPI 的优势变得很明显：

• 需要自动生成 Swagger 文档（Flask 需要额外的 flasgger 插件）
• 对类型安全有较高要求（团队全员使用 mypy）
• 接口并发量不低，FastAPI 的异步支持开箱即用

最终花了半天搭建 MVP，再花两天完善细节，比预估的工期缩短了将近一半。

项目入口

from fastapi import FastAPI
from app.api.v1 import users, posts, auth

app = FastAPI(title="内部工具 API", version="1.0.0")

app.include_router(auth.router, prefix="/api/v1")
app.include_router(users.router, prefix="/api/v1/users", tags=["用户"])
app.include_router(posts.router, prefix="/api/v1/posts", tags=["文章"])

tags 参数让 Swagger 文档自动按模块分组，不需要额外配置。

Pydantic 数据校验

这是 FastAPI 最让人舒服的部分——定义 Schema，校验自动完成：

from pydantic import BaseModel, EmailStr, Field

class UserCreate(BaseModel):
    username: str = Field(..., min_length=3, max_length=32)
    email: EmailStr
    bio: str | None = Field(None, max_length=200)

class UserResponse(BaseModel):
    id: int
    username: str
    email: str

    model_config = {"from_attributes": True}

请求体不合规范时，FastAPI 自动返回清晰的 422 错误，字段级别的提示让前端同事能精准定位问题。

依赖注入处理认证

from fastapi import Depends, HTTPException, status
from fastapi.security import HTTPBearer

security = HTTPBearer()

async def get_current_user(
    token: str = Depends(security)
) -> User:
    payload = decode_token(token)
    user = await fetch_user(payload.sub)
    if not user:
        raise HTTPException(status_code=status.HTTP_401_UNAUTHORIZED)
    return user

@router.get("/me", response_model=UserResponse)
async def read_me(current_user: User = Depends(get_current_user)):
    return current_user

总结

维度	Flask	FastAPI
自动文档	需插件	内置
数据校验	手动 / marshmallow	Pydantic 自动
异步支持	需额外配置	原生 async
类型安全	弱	强（Pydantic + mypy）

FastAPI 加上 SQLAlchemy 2.0 的 async session，整个链路从接口到数据库都是异步的，性能提升非常可观。唯一的小遗憾是生态还比不上 Flask 的丰富度，一些偏门的第三方扩展需要自己封装。