FastAPI 快速上手教程

FastAPI 快速上手建议按"安装 → 写接口 → 启动服务 → 看文档"这条主线，10 分钟就能跑通第一个 API，再花 20 分钟掌握数据校验和流式输出。

1. 准备环境

需要 Python 3.10 以上版本（FastAPI 0.129+ 已不再支持 3.9）。

python --version

2. 安装

pip install "fastapi[standard]"

[standard] 会自动带上 uvicorn、pydantic 等核心依赖。如果用 uv 工具，则 uv add fastapi --extra standard。

3. 写第一个接口

创建 main.py：

from fastapi import FastAPI

app = FastAPI(title="我的 API", version="1.0.0")

@app.get("/")
def read_root():
    return {"message": "Hello World"}

@app.get("/items/{item_id}")
def get_item(item_id: int, q: str = None):
    return {"item_id": item_id, "query": q}

4. 启动服务

推荐方式（FastAPI CLI）：

fastapi dev main.py

传统方式：

uvicorn main:app --reload --host 0.0.0.0 --port 8000

启动后打开 http://localhost:8000/docs 即可看到 Swagger UI 交互式文档，/redoc 是 ReDoc 文档。

5. 数据校验（Pydantic 模型）

FastAPI 的核心优势：用类型提示自动完成请求校验和序列化。

from pydantic import BaseModel, Field

class ItemCreate(BaseModel):
    name: str = Field(min_length=1, max_length=50)
    price: float = Field(gt=0)
    tags: list[str] = []

@app.post("/items", status_code=201)
def create_item(item: ItemCreate):
    return {"id": 1, **item.model_dump()}

发送非法数据（如 price: -1）会自动返回 422 错误，无需手写校验逻辑。

6. 流式输出（SSE）

FastAPI 0.135+ 原生支持 SSE，非常适合 LLM 流式对话场景。

from fastapi import FastAPI
from fastapi.responses import StreamingResponse
import asyncio, json

app = FastAPI()

async def token_stream():
    for word in ["Hello", ",", " ", "world", "!"]:
        yield f"data: {json.dumps({'token': word})}\n\n"
        await asyncio.sleep(0.1)
    yield "data: [DONE]\n\n"

@app.get("/chat/stream")
def stream_chat():
    return StreamingResponse(
        token_stream(),
        media_type="text/event-stream",
        headers={"Cache-Control": "no-cache", "X-Accel-Buffering": "no"}
    )

前端用浏览器原生 EventSource 即可接收：

const es = new EventSource("/chat/stream");
es.onmessage = (e) => {
    if (e.data === "[DONE]") { es.close(); return; }
    console.log(JSON.parse(e.data).token);
};

7. 依赖注入

from fastapi import Depends, Header, HTTPException

def verify_token(x_token: str = Header()):
    if x_token != "secret":
        raise HTTPException(status_code=401, detail="Invalid token")
    return x_token

@app.get("/protected")
def protected_route(token: str = Depends(verify_token)):
    return {"message": "Access granted", "token": token}

8. 项目结构建议

project/
├── main.py          # 入口
├── routers/         # 路由模块
│   ├── items.py
│   └── users.py
├── models/          # Pydantic 模型
│   └── schemas.py
├── services/        # 业务逻辑
└── tests/           # 测试

9. 生产部署

# 多 worker 生产模式
uvicorn main:app --host 0.0.0.0 --port 8000 --workers 4

推荐架构：Nginx（HTTPS/反向代理）→ Uvicorn（多 worker）→ FastAPI。