FastAPI 从 0 到 1：史上最良心的现代 Python Web 框架入门指南

标签：

FastAPI · Python · 异步 · 类型提示 · 自动生成文档 · 高性能

---

一、为什么又是新框架？

Django / Flask 已经够好了，但新时代有了新痛点：

1. 前后端分离 → 需要强制类型 & 自动文档
2. 高并发 IO → 需要原生异步
3. 机器学习模型上线 → 需要高性能 + 自动序列化

FastAPI = Starlette（异步）+ Pydantic（数据校验）+ 自动生成 OpenAPI 文档，三箭齐发，官方 benchmark latency 直追 NodeJS 和 Go。

---

二、5 分钟跑通 Hello World

安装

pip install "fastapi[all]"   # all = uvicorn + 常用 extras

main.py

from fastapi import FastAPI

app = FastAPI(title="Hello API")

@app.get("/")
def root():
    return {"message": "Hello FastAPI"}

启动

uvicorn main:app --reload

浏览器访问 http://127.0.0.1:8000

交互式文档 http://127.0.0.1:8000/docs（Swagger UI）自动生成！

---

三、类型提示 = 自动生成文档 + 运行时校验

from pydantic import BaseModel

class Item(BaseModel):
    name: str
    price: float
    tax: float | None = None

@app.post("/items/", response_model=Item)
async def create_item(item: Item):
    if item.tax:
        item.price += item.tax
    return item    # 自动序列化 JSON

• 请求体少字段 → 422 错误 + 详细位置提示
• 文档里 Schema 与代码单点真理，永不同步失败

---

四、异步全程高能

FastAPI 默认基于 async def，与 asyncio、aiohttp、aiomysql 全家桶无缝协作：

import asyncio
from aiohttp import ClientSession

@app.get("/proxy")
async def proxy():
    async with ClientSession() as sess:
        async with sess.get("https://httpbin.org/delay/2") as r:
            data = await r.json()
    return data

单进程可并发 1000+ 慢 IO 请求，latency 远低于同步框架。

---

五、路径参数 & 查询参数一把梭

@app.get("/user/{user_id}")
async def read_user(user_id: int, q: str | None = None, limit: int = 10):
    return {"user_id": user_id, "q": q, "limit": limit}

• user_id 自动校验 int → 非法返回 422
• q 可选，缺省 None
• 文档实时体现参数类型、默认值

---

六、依赖注入 ------ 像 Spring 一样优雅

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

security = HTTPBearer()

async def get_current_user(token: HTTPAuthorizationCredentials = Depends(security)):
    if token.credentials != "fake-token":
        raise HTTPException(status_code=status.HTTP_401_UNAUTHORIZED,
                            detail="Invalid token")
    return {"uid": 42}

@app.get("/secure")
async def secure_endpoint(user=Depends(get_current_user)):
    return {"message": "secret data", "user": user}

依赖可嵌套、可复用，单元测试时直接 mock 依赖即可。

---

七、上线必备：CORS / 静态文件 / 异常处理

from fastapi.middleware.cors import CORSMiddleware
from fastapi.staticfiles import StaticFiles
from fastapi.responses import JSONResponse

app.add_middleware(
    CORSMiddleware,
    allow_origins=["*"],
    allow_methods=["*"],
    allow_headers=["*"],
)

app.mount("/static", StaticFiles(directory="static"), name="static")

@app.exception_handler(ValueError)
async def value_error_handler(request, exc):
    return JSONResponse(status_code=400,
                        content={"detail": str(exc)})

全同步/异步混合写皆可，保持代码风格一致。

---

八、与 SQL 数据库联动 ------ 异步 ORM 示例

pip install databases[aiosqlite] sqlalchemy

database.py

from databases import Database
database = Database("sqlite+aiosqlite:///./demo.db")

model.py

import sqlalchemy
metadata = sqlalchemy.MetaData()
notes = sqlalchemy.Table(
    "notes",
    metadata,
    sqlalchemy.Column("id", sqlalchemy.Integer, primary_key=True),
    sqlalchemy.Column("text", sqlalchemy.String),
    sqlalchemy.Column("completed", sqlalchemy.Boolean),
)

main.py 节选

@app.on_event("startup")
async def startup():
    await database.connect()

@app.on_event("shutdown")
async def shutdown():
    await database.disconnect()

@app.post("/notes/")
async def create_note(text: str):
    query = notes.insert().values(text=text, completed=False)
    last_record_id = await database.execute(query)
    return {**dict(id=last_record_id, text=text, completed=False)}

全程 async，吞吐量比同步 SQL 提高一个量级。

---

九、性能 & 生态

• Starlette 打底：支持 HTTP/2、WebSocket、GraphQL
• Pydantic 加持：校验速度是传统 schema 库的 2~4 倍
• Uvicorn + Gunicorn 多 worker 部署，8 核轻松破 10k RPS
• 官方 benchmark：FastAPI latency 与 Starlette/Go Echo 同级，比 Flask 快 3~5 倍

---

十、部署一条命令

# 本地开发
uvicorn main:app --reload

# 生产多核
gunicorn main:app -w 4 -k uvicorn.workers.UvicornWorker --bind 0.0.0.0:8000

Dockerfile 示例

FROM python:3.11-slim
WORKDIR /app
COPY requirements.txt .
RUN pip install -r requirements.txt
COPY . .
CMD ["uvicorn", "main:app", "--host", "0.0.0.0", "--port", "8000"]

镜像 <100 MB，K8s/Serverless 随意扩。

---

十一、总结：一张图记住 FastAPI

┌-------------┐        ┌------------┐
│ Pydantic    │ <----->│ 请求/响应   │  <-- 自动校验+序列化
│ 数据模型     │        │ 类型提示    │
└-------------┘        └------------┘
        ^                       |
        |                       v
┌-------------┐        ┌------------┐
│ 依赖注入     │        │ OpenAPI    │  <-- 自动生成 docs
│ 安全/DB/逻辑 │        │ 文档/redoc │
└-------------┘        └------------┘
        ^                       |
        |                       v
┌-------------------------------┐
│ Starlette（ASGI）异步核心      │  <-- 高性能
└-------------------------------┘

FastAPI = 类型提示 + 异步 + 自动生成文档 三箭齐发，

写更少代码，跑更快服务，出更全文档。2024 年了，如果你还在手写 Swagger JSON，不妨给 FastAPI 一个周末，它会还你整个生产力。