【python】通过FastAPI构建复杂的Web API

通过FastAPI构建复杂的Web API

构建复杂的 Web API 通常涉及到多个方面，包括良好的架构设计、清晰的路由组织、数据验证与处理、安全措施、性能优化等。使用 FastAPI 构建复杂 Web API 的关键在于充分利用其提供的工具和特性，同时遵循软件工程的最佳实践。以下是一个详细的指南，帮助你使用 FastAPI 构建一个复杂且高效的 Web API。

1. 项目结构

为你的项目创建一个合理的文件夹结构，这有助于代码的组织和维护。例如：

my_project/
├── app/
│   ├── __init__.py
│   ├── main.py
│   ├── dependencies.py
│   ├── models.py
│   ├── schemas.py
│   ├── routers/
│   │   ├── __init__.py
│   │   ├── items.py
│   │   └── users.py
│   ├── services/
│   │   ├── __init__.py
│   │   ├── item_service.py
│   │   └── user_service.py
│   ├── database.py
│   └── config.py
└── tests/
    ├── __init__.py
    └── test_main.py

2. 依赖管理

使用 requirements.txt 或者更现代的 poetry 来管理项目的依赖关系。确保所有开发和生产环境所需的库都被列出。

# 使用 poetry 初始化项目并添加依赖
poetry init
poetry add fastapi uvicorn sqlalchemy alembic bcrypt passlib[bcrypt] pydantic email-validator

3. 配置管理

使用环境变量或配置文件来管理应用程序的不同设置（如数据库连接字符串、密钥等）。可以借助 Pydantic 的 BaseSettings 类。

# config.py
from pydantic import BaseSettings

class Settings(BaseSettings):
    app_name: str = "My Complex API"
    admin_email: str
    items_per_user: int = 50
    secret_key: str
    algorithm: str = "HS256"
    access_token_expire_minutes: int = 30

    class Config:
        env_file = ".env"

settings = Settings()

4. 数据库集成

选择合适的 ORM（如 SQLAlchemy）并与 FastAPI 集成。创建数据库模型，并考虑使用 Alembic 进行数据库迁移。

# database.py
from sqlalchemy import create_engine
from sqlalchemy.ext.declarative import declarative_base
from sqlalchemy.orm import sessionmaker

SQLALCHEMY_DATABASE_URL = "sqlite:///./test.db"

engine = create_engine(SQLALCHEMY_DATABASE_URL, connect_args={"check_same_thread": False})
SessionLocal = sessionmaker(autocommit=False, autoflush=False, bind=engine)
Base = declarative_base()

def get_db():
    db = SessionLocal()
    try:
        yield db
    finally:
        db.close()

5. 定义模型与模式

创建数据模型用于映射到数据库表，以及 Pydantic 模型用于请求体和响应的验证。

# models.py
from sqlalchemy import Column, Integer, String
from .database import Base

class Item(Base):
    __tablename__ = "items"

    id = Column(Integer, primary_key=True, index=True)
    name = Column(String, index=True)
    description = Column(String, index=True)

# schemas.py
from pydantic import BaseModel

class ItemCreate(BaseModel):
    name: str
    description: str = None

class Item(BaseModel):
    id: int
    name: str
    description: str = None

    class Config:
        orm_mode = True

6. 服务层

为了保持控制器（路由处理函数）的简洁性，将业务逻辑分离到服务层中。

# services/item_service.py
from typing import List
from sqlalchemy.orm import Session
from ..models import Item as ItemModel
from ..schemas import ItemCreate, Item

def get_items(db: Session, skip: int = 0, limit: int = 10) -> List[Item]:
    return db.query(ItemModel).offset(skip).limit(limit).all()

def create_item(db: Session, item: ItemCreate) -> Item:
    db_item = ItemModel(**item.dict())
    db.add(db_item)
    db.commit()
    db.refresh(db_item)
    return db_item

7. 路由分组

将相关路径操作分组到不同的路由器模块中，以提高代码的可读性和可维护性。

# routers/items.py
from fastapi import APIRouter, Depends
from sqlalchemy.orm import Session
from ... import schemas, services
from ...dependencies import get_db

router = APIRouter()

@router.get("/", response_model=List[schemas.Item])
def read_items(skip: int = 0, limit: int = 10, db: Session = Depends(get_db)):
    items = services.get_items(db, skip=skip, limit=limit)
    return items

@router.post("/", response_model=schemas.Item)
def create_item(item: schemas.ItemCreate, db: Session = Depends(get_db)):
    return services.create_item(db=db, item=item)

8. 主应用入口

在主应用文件中导入并包含各个路由器。

# main.py
from fastapi import FastAPI
from .routers import items, users

app = FastAPI()

app.include_router(items.router)
app.include_router(users.router)

9. 安全性

实现身份验证和授权机制，例如使用 JWT Token 进行用户认证。

# dependencies.py
from datetime import datetime, timedelta
from jose import JWTError, jwt
from fastapi import Depends, HTTPException, status
from fastapi.security import OAuth2PasswordBearer
from . import models, schemas, config

oauth2_scheme = OAuth2PasswordBearer(tokenUrl="token")

async def get_current_user(token: str = Depends(oauth2_scheme)):
    credentials_exception = HTTPException(
        status_code=status.HTTP_401_UNAUTHORIZED,
        detail="Could not validate credentials",
        headers={"WWW-Authenticate": "Bearer"},
    )
    try:
        payload = jwt.decode(token, config.settings.secret_key, algorithms=[config.settings.algorithm])
        username: str = payload.get("sub")
        if username is None:
            raise credentials_exception
        token_data = schemas.TokenData(username=username)
    except JWTError:
        raise credentials_exception
    user = get_user(db, username=token_data.username)
    if user is None:
        raise credentials_exception
    return user

10. 测试

编写单元测试和集成测试来确保你的 API 按预期工作。FastAPI 提供了方便的测试客户端 TestClient。

# tests/test_main.py
from fastapi.testclient import TestClient
from my_project.app.main import app

client = TestClient(app)

def test_read_main():
    response = client.get("/")
    assert response.status_code == 200
    assert response.json() == {"message": "Hello World"}

11. 部署

考虑使用 Docker 容器化你的应用程序，并通过 CI/CD 管道自动部署到云平台或服务器上。

# Dockerfile
FROM tiangolo/uvicorn-gunicorn-fastapi:python3.9

COPY ./app /app
WORKDIR /app

RUN pip install --no-cache-dir -r requirements.txt

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

总结

通过以上步骤可以使用 FastAPI 构建复杂的 Web API。

FastAPI支持的工具

FastAPI 提供了丰富的工具和特性，使得开发高效、安全且易于维护的 Web API 变得更加简单。除了核心功能外，还有一些重要的工具和特性可以帮助你构建更强大的应用程序。以下是 FastAPI 的一些重要工具和特性：

1. 依赖注入系统

FastAPI 内置了一个强大且灵活的依赖注入系统，这使得你可以轻松地管理和重用代码逻辑，比如身份验证、数据库连接等。

from fastapi import Depends, FastAPI

app = FastAPI()

async def get_db():
    db = DBSession()
    try:
        yield db
    finally:
        db.close()

@app.get("/items/")
async def read_items(db: Session = Depends(get_db)):
    items = db.query(Item).all()
    return items

2. Pydantic 模型

Pydantic 是一个数据验证库，它允许你定义数据模型，并自动处理数据解析和验证。FastAPI 使用 Pydantic 来确保请求体、查询参数和其他输入符合预期格式。

from pydantic import BaseModel

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

3. 中间件

中间件是在请求到达路由处理函数之前或响应发送给客户端之后执行的代码。你可以使用中间件来添加通用的行为，如日志记录、身份验证、CORS 处理等。

from fastapi.middleware.cors import CORSMiddleware

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

4. 异常处理

FastAPI 提供了内置的异常处理机制，并允许你自定义异常处理器来处理特定类型的错误。

from fastapi import Request, status
from fastapi.responses import JSONResponse
from fastapi.exceptions import RequestValidationError

@app.exception_handler(RequestValidationError)
async def validation_exception_handler(request: Request, exc: RequestValidationError):
    return JSONResponse(
        status_code=status.HTTP_422_UNPROCESSABLE_ENTITY,
        content={"detail": exc.errors(), "body": exc.body},
    )

5. 背景任务

如果你需要在返回响应后继续执行某些操作（如发送电子邮件），可以使用背景任务。

from fastapi import BackgroundTasks

def write_log(message: str):
    with open("log.txt", mode="a") as log:
        log.write(message)

@app.post("/send-notification/{email}")
async def send_notification(email: str, background_tasks: BackgroundTasks):
    background_tasks.add_task(write_log, f"Notification sent to {email}\n")
    return {"message": "Notification sent in the background"}

6. 静态文件和模板

FastAPI 支持服务静态文件（如 HTML、CSS、JavaScript 文件）以及渲染模板，这对于创建完整的 Web 应用程序非常有用。

from fastapi.staticfiles import StaticFiles
from fastapi.templating import Jinja2Templates

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

@app.get("/")
async def read_root(request: Request):
    return templates.TemplateResponse("index.html", {"request": request})

7. WebSocket 支持

FastAPI 支持 WebSocket 连接，这对于实现实时双向通信非常有用，例如聊天应用或实时更新的数据展示。

from fastapi import WebSocket, WebSocketDisconnect

@app.websocket("/ws")
async def websocket_endpoint(websocket: WebSocket):
    await websocket.accept()
    try:
        while True:
            data = await websocket.receive_text()
            await websocket.send_text(f"Message text was: {data}")
    except WebSocketDisconnect:
        pass

8. 环境变量与配置管理

使用 pydantic 的 BaseSettings 类来管理应用程序的配置和环境变量，这有助于分离配置和代码。

from pydantic import BaseSettings

class Settings(BaseSettings):
    app_name: str = "Awesome API"
    admin_email: str
    items_per_user: int = 50

    class Config:
        env_file = ".env"

settings = Settings()

9. 测试工具

FastAPI 提供了方便的测试工具，包括测试客户端 TestClient 和模拟器，帮助你在本地快速测试 API。

from fastapi.testclient import TestClient

client = TestClient(app)

def test_read_main():
    response = client.get("/")
    assert response.status_code == 200
    assert response.json() == {"message": "Hello World"}

10. OpenAPI 和 Swagger UI

FastAPI 自动生成 OpenAPI 规范，并提供交互式的 API 文档界面（Swagger UI 和 ReDoc）。这不仅方便开发者调试 API，也便于用户了解如何使用你的 API。

# 自动生成并提供交互式文档
# 访问 http://127.0.0.1:8000/docs 或 http://127.0.0.1:8000/redoc

11. 速率限制

虽然 FastAPI 本身不直接提供速率限制功能，但可以通过中间件或其他扩展来实现这一特性，以防止滥用或保护服务器资源。

from fastapi import FastAPI, HTTPException, status
from fastapi.middleware import Middleware
from fastapi.middleware.trustedhost import TrustedHostMiddleware

app = FastAPI(middleware=[
    Middleware(TrustedHostMiddleware, allowed_hosts=["example.com"])
])

# 或者使用第三方库如 fastapi-limiter 实现速率限制

这些工具和特性共同构成了 FastAPI 强大而灵活的生态系统，使得开发者能够更高效地构建现代 Web API。

FastAPI 路由操作

FastAPI 支持所有标准的 HTTP 方法（也称为“路由操作”或“HTTP 动词”），这些方法定义了客户端与服务器之间的交互类型。以下是 FastAPI 支持的主要路由操作：

1. GET

用于请求从服务器获取信息，通常用于查询资源。

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

2. POST

用于向指定资源提交数据，常用于创建新资源或发送表单数据。

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

3. PUT

用于更新现有资源，通常整个资源会被替换。

@app.put("/items/{item_id}")
async def update_item(item_id: int, item: Item):
    return {"item_id": item_id, "item": item}

4. DELETE

用于删除指定的资源。

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

5. PATCH

用于对资源进行部分更新，只修改指定字段。

@app.patch("/items/{item_id}")
async def patch_item(item_id: int, item: ItemUpdate):
    return {"item_id": item_id, "item": item}

6. OPTIONS

用于描述目标资源的通信选项。它返回服务器支持的方法列表。

@app.options("/items/")
async def describe_options():
    return {"Allow": "GET, POST, PUT, DELETE, PATCH, OPTIONS"}

7. HEAD

类似于 GET 请求，但不返回消息体，仅用于获取响应头信息。

@app.head("/items/{item_id}")
async def head_item(item_id: int):
    # 处理逻辑，但不会返回响应体
    pass

8. TRACE

用于回显服务器收到的请求，主要用于测试或诊断。

@app.trace("/trace")
async def trace_request():
    return {"method": "TRACE"}

路由参数

除了上述的 HTTP 方法外，FastAPI 还允许你定义路径参数、查询参数、请求体等，以更灵活地处理不同的请求场景。

路径参数

直接在路径中定义参数，如 /items/{item_id} 中的 item_id。

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

查询参数

通过 URL 的查询字符串传递参数，例如 /items/?skip=0&limit=10。

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

请求体

使用 Pydantic 模型来解析和验证 JSON 请求体。

from pydantic import BaseModel

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

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

额外功能

• 路径操作函数：可以是同步函数（def）或异步函数（async def），根据你的需求选择。
• 依赖注入：可以在路径操作函数中添加依赖项，以便于共享状态或执行预处理逻辑。
• 中间件：为所有请求添加额外的行为，比如日志记录、身份验证等。
• 自定义响应：你可以返回不同类型的响应，包括 JSONResponse、HTMLResponse 等。
• WebSocket：FastAPI 同样支持 WebSocket 连接，可以用来实现实时双向通信。

以上就是 FastAPI 支持的主要路由操作。FastAPI 的设计使得它不仅支持标准的 HTTP 方法，还提供了强大的工具来帮助开发者构建现代的 Web API。