FastAPI 是一个现代、快速（高性能）的 Python Web 框架，用于构建 API，基于标准的 Python 类型提示。

FastAPI

核心特性

• 高性能：与 NodeJS 和 Go 相媲美，是最快的 Python 框架之一
• 快速开发：代码编写量减少约 200%到 300%
• 智能编辑器支持：内置编辑补全
• 自动文档：自动生成 OpenAPI 文档和交互式 API 文档 UI
• 类型安全：基于 Python 3.6+类型提示

快速开始

安装 FastAPI

pip 安装

pip install fastapi uvicorn[standard]

conda 安装

conda install -c conda-forge fastapi uvicorn

第一个 API

创建 main.py：

from fastapi import FastAPI

app = FastAPI()

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

运行应用

uvicorn main:app --reload

访问 http://localhost:8000/docs 查看自动生成的交互式 API 文档。

基础路由

路径参数

@app.get("/items/{item_id}")
async def read_item(item_id: int):
    return {"item_id": item_id}

查询参数

@app.get("/items/")
async def read_items(skip: int = 0, limit: int = 10):
    return {"skip": skip, "limit": limit}

请求体

from pydantic import BaseModel

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

@app.post("/items/")
async def create_item(item: Item):
    return {"item": item}

依赖注入

from fastapi import Depends

async def get_token_header(x_token: str = Header(...)):
    if x_token != "fake-super-secret-token":
        raise HTTPException(status_code=400, detail="X-Token header invalid")
    return x_token

@app.get("/items/", dependencies=[Depends(get_token_header)])
async def read_items():
    return [{"item": "Foo"}, {"item": "Bar"}]

数据库集成

SQLAlchemy

from sqlalchemy import create_engine
from sqlalchemy.ext.declarative import declarative_base
from sqlalchemy.orm import sessionmaker

DATABASE_URL = "sqlite:///./sql_app.db"
engine = create_engine(DATABASE_URL)
SessionLocal = sessionmaker(autocommit=False, autoflush=False, bind=engine)
Base = declarative_base()

# 依赖
async def get_db():
    db = SessionLocal()
    try:
        yield db
    finally:
        db.close()

中间件与异常处理

添加中间件

from fastapi.middleware.cors import CORSMiddleware

app.add_middleware(
    CORSMiddleware,
    allow_origins=["http://localhost:3000"],
    allow_credentials=True,
    allow_methods=["*"],
    allow_headers=["*"],
)

自定义异常

class UnicornException(Exception):
    def __init__(self, name: str):
        self.name = name

@app.exception_handler(UnicornException)
async def unicorn_exception_handler(request: Request, exc: UnicornException):
    return JSONResponse(
        status_code=418,
        content={"message": f"Oops! {exc.name} did something."},
    )

异步支持

import asyncio

@app.get("/async-items/{item_id}")
async def read_async_item(item_id: int):
    await asyncio.sleep(1)
    return {"item_id": item_id}

WebSocket 支持

from fastapi import WebSocket

@app.websocket("/ws/{client_id}")
async def websocket_endpoint(websocket: WebSocket, client_id: str):
    await websocket.accept()
    await websocket.send_text(f"Client #{client_id} connected")
    while True:
        data = await websocket.receive_text()
        await websocket.send_text(f"Message received: {data}")

部署方式

使用 Gunicorn

pip install gunicorn uvicorn[standard]
gunicorn main:app -w 4 -k uvicorn.workers.UvicornWorker

Docker 部署

FROM python:3.11-slim

WORKDIR /app
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt

COPY ../../multi .

CMD ["uvicorn", "main:app", "--host", "0.0.0.0", "--port", "8000"]

Docker Compose

version: "3.8"

services:
  web:
    build: .
    ports:
      - "8000:8000"
    environment:
      - DATABASE_URL=postgresql://user:password@db:5432/dbname
    depends_on:
      - db

  db:
    image: postgres:15
    environment:
      POSTGRES_USER: user
      POSTGRES_PASSWORD: password
      POSTGRES_DB: dbname

生产环境优化

启用 HTTPS

uvicorn main:app --ssl-keyfile=./key.pem --ssl-certfile=./cert.pem

性能优化

from fastapi import FastAPI
from fastapi.responses import ORJSONResponse

app = FastAPI(default_response_class=ORJSONResponse)

常用扩展

• fastapi-users: 用户认证与授权
• sqladmin: SQLAlchemy 管理界面
• fastapi-cache: 缓存支持
• fastapi-pagination: 分页工具
• fastapi-limiter: 限速功能
• fastapi-mail: 邮件发送

常见问题

Q: 如何启用热重载？

A: 使用 --reload 参数：uvicorn main:app --reload

Q: 如何访问 API 文档？

A: 访问 /docs (Swagger UI) 或 /redoc (ReDoc)

Q: 如何处理文件上传？

A: 使用 File 和 UploadFile：

@app.post("/uploadfile/")
async def create_upload_file(file: UploadFile):
    return {"filename": file.filename}

Q: 如何配置跨域？

A: 使用 CORSMiddleware 中间件

Q: 如何返回自定义状态码？

A: 使用 status_code 参数：

@app.post("/items/", status_code=201)
async def create_item(item: Item):
    return item

总结

FastAPI 是现代 Python API 开发的首选框架，提供高性能、类型安全和自动生成文档等功能，适合微服务架构和云原生应用。丰富的生态系统使其能够快速构建生产级 API 服务。

贡献者: paiad