Back to Details

python-fastapi-patterns

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

FastAPI Patterns

FastAPI 设计模式

Modern async API development with FastAPI.
基于FastAPI的现代异步API开发。

Basic Application

基础应用

python
from fastapi import FastAPI
from contextlib import asynccontextmanager

@asynccontextmanager
async def lifespan(app: FastAPI):
    """Application lifespan - startup and shutdown."""
    # Startup
    app.state.db = await create_db_pool()
    yield
    # Shutdown
    await app.state.db.close()

app = FastAPI(
    title="My API",
    version="1.0.0",
    lifespan=lifespan,
)

@app.get("/")
async def root():
    return {"message": "Hello World"}
python
from fastapi import FastAPI
from contextlib import asynccontextmanager

@asynccontextmanager
async def lifespan(app: FastAPI):
    """Application lifespan - startup and shutdown."""
    # Startup
    app.state.db = await create_db_pool()
    yield
    # Shutdown
    await app.state.db.close()

app = FastAPI(
    title="My API",
    version="1.0.0",
    lifespan=lifespan,
)

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

Request/Response Models

请求/响应模型

python
from pydantic import BaseModel, Field, EmailStr
from datetime import datetime

class UserCreate(BaseModel):
    """Request model with validation."""
    name: str = Field(..., min_length=1, max_length=100)
    email: EmailStr
    age: int = Field(..., ge=0, le=150)

class UserResponse(BaseModel):
    """Response model."""
    id: int
    name: str
    email: EmailStr
    created_at: datetime

    model_config = {"from_attributes": True}  # Enable ORM mode

@app.post("/users", response_model=UserResponse, status_code=201)
async def create_user(user: UserCreate):
    db_user = await create_user_in_db(user)
    return db_user
python
from pydantic import BaseModel, Field, EmailStr
from datetime import datetime

class UserCreate(BaseModel):
    """Request model with validation."""
    name: str = Field(..., min_length=1, max_length=100)
    email: EmailStr
    age: int = Field(..., ge=0, le=150)

class UserResponse(BaseModel):
    """Response model."""
    id: int
    name: str
    email: EmailStr
    created_at: datetime

    model_config = {"from_attributes": True}  # Enable ORM mode

@app.post("/users", response_model=UserResponse, status_code=201)
async def create_user(user: UserCreate):
    db_user = await create_user_in_db(user)
    return db_user

Path and Query Parameters

路径与查询参数

python
from fastapi import Query, Path
from typing import Annotated

@app.get("/users/{user_id}")
async def get_user(
    user_id: Annotated[int, Path(..., ge=1, description="User ID")],
):
    return await fetch_user(user_id)

@app.get("/users")
async def list_users(
    skip: Annotated[int, Query(ge=0)] = 0,
    limit: Annotated[int, Query(ge=1, le=100)] = 10,
    search: str | None = None,
):
    return await fetch_users(skip=skip, limit=limit, search=search)
python
from fastapi import Query, Path
from typing import Annotated

@app.get("/users/{user_id}")
async def get_user(
    user_id: Annotated[int, Path(..., ge=1, description="User ID")],
):
    return await fetch_user(user_id)

@app.get("/users")
async def list_users(
    skip: Annotated[int, Query(ge=0)] = 0,
    limit: Annotated[int, Query(ge=1, le=100)] = 10,
    search: str | None = None,
):
    return await fetch_users(skip=skip, limit=limit, search=search)

Dependency Injection

依赖注入

python
from fastapi import Depends
from typing import Annotated

async def get_db():
    """Database session dependency."""
    async with async_session() as session:
        yield session

async def get_current_user(
    token: Annotated[str, Depends(oauth2_scheme)],
    db: Annotated[AsyncSession, Depends(get_db)],
) -> User:
    """Authenticate and return current user."""
    user = await authenticate_token(db, token)
    if not user:
        raise HTTPException(status_code=401, detail="Invalid token")
    return user
python
from fastapi import Depends
from typing import Annotated

async def get_db():
    """Database session dependency."""
    async with async_session() as session:
        yield session

async def get_current_user(
    token: Annotated[str, Depends(oauth2_scheme)],
    db: Annotated[AsyncSession, Depends(get_db)],
) -> User:
    """Authenticate and return current user."""
    user = await authenticate_token(db, token)
    if not user:
        raise HTTPException(status_code=401, detail="Invalid token")
    return user

Annotated types for reuse

Annotated types for reuse

DB = Annotated[AsyncSession, Depends(get_db)] CurrentUser = Annotated[User, Depends(get_current_user)]
@app.get("/me") async def get_me(user: CurrentUser): return user
undefined
DB = Annotated[AsyncSession, Depends(get_db)] CurrentUser = Annotated[User, Depends(get_current_user)]
@app.get("/me") async def get_me(user: CurrentUser): return user
undefined

Exception Handling

异常处理

python
from fastapi import HTTPException
from fastapi.responses import JSONResponse
python
from fastapi import HTTPException
from fastapi.responses import JSONResponse

Built-in HTTP exceptions

Built-in HTTP exceptions

@app.get("/items/{item_id}") async def get_item(item_id: int): item = await fetch_item(item_id) if not item: raise HTTPException(status_code=404, detail="Item not found") return item
@app.get("/items/{item_id}") async def get_item(item_id: int): item = await fetch_item(item_id) if not item: raise HTTPException(status_code=404, detail="Item not found") return item

Custom exception handler

Custom exception handler

class ItemNotFoundError(Exception): def init(self, item_id: int): self.item_id = item_id
@app.exception_handler(ItemNotFoundError) async def item_not_found_handler(request, exc: ItemNotFoundError): return JSONResponse( status_code=404, content={"detail": f"Item {exc.item_id} not found"}, )
undefined
class ItemNotFoundError(Exception): def init(self, item_id: int): self.item_id = item_id
@app.exception_handler(ItemNotFoundError) async def item_not_found_handler(request, exc: ItemNotFoundError): return JSONResponse( status_code=404, content={"detail": f"Item {exc.item_id} not found"}, )
undefined

Router Organization

路由组织

python
from fastapi import APIRouter
python
from fastapi import APIRouter

users.py

users.py

router = APIRouter(prefix="/users", tags=["users"])
@router.get("/") async def list_users(): return []
@router.get("/{user_id}") async def get_user(user_id: int): return {"id": user_id}
router = APIRouter(prefix="/users", tags=["users"])
@router.get("/") async def list_users(): return []
@router.get("/{user_id}") async def get_user(user_id: int): return {"id": user_id}

main.py

main.py

from app.routers import users, items
app.include_router(users.router) app.include_router(items.router, prefix="/api/v1")
undefined
from app.routers import users, items
app.include_router(users.router) app.include_router(items.router, prefix="/api/v1")
undefined

Quick Reference

快速参考

FeatureUsage
Path param
@app.get("/items/{id}")
Query param
def f(q: str = None)
Body
def f(item: ItemCreate)
Dependency
Depends(get_db)
Auth
Depends(get_current_user)
Response model
response_model=ItemResponse
Status code
status_code=201
特性用法
路径参数
@app.get("/items/{id}")
查询参数
def f(q: str = None)
请求体
def f(item: ItemCreate)
依赖项
Depends(get_db)
身份验证
Depends(get_current_user)
响应模型
response_model=ItemResponse
状态码
status_code=201

Additional Resources

额外资源

  • ./references/dependency-injection.md
    - Advanced DI patterns, scopes, caching
  • ./references/middleware-patterns.md
    - Middleware chains, CORS, error handling
  • ./references/validation-serialization.md
    - Pydantic v2 patterns, custom validators
  • ./references/background-tasks.md
    - Background tasks, async workers, scheduling
  • ./references/dependency-injection.md
    - 高级依赖注入模式、作用域、缓存
  • ./references/middleware-patterns.md
    - 中间件链、CORS、异常处理
  • ./references/validation-serialization.md
    - Pydantic v2模式、自定义验证器
  • ./references/background-tasks.md
    - 后台任务、异步工作器、调度

Scripts

脚本

  • ./scripts/scaffold-api.sh
    - Generate API endpoint boilerplate
  • ./scripts/scaffold-api.sh
    - 生成API端点模板代码

Assets

资源文件

  • ./assets/fastapi-template.py
    - Production-ready FastAPI app skeleton
  • ./assets/fastapi-template.py
    - 生产就绪的FastAPI应用骨架

See Also

另请参阅

Prerequisites:
  • python-typing-patterns
    - Pydantic models and type hints
  • python-async-patterns
    - Async endpoint patterns
Related Skills:
  • python-database-patterns
    - SQLAlchemy integration
  • python-observability-patterns
    - Logging, metrics, tracing middleware
  • python-pytest-patterns
    - API testing with TestClient
前置要求：
  • python-typing-patterns
    - Pydantic模型与类型提示
  • python-async-patterns
    - 异步端点模式
相关技能：
  • python-database-patterns
    - SQLAlchemy集成
  • python-observability-patterns
    - 日志、指标、追踪中间件
  • python-pytest-patterns
    - 使用TestClient进行API测试