fastapi-best-practices（FastAPI 最佳实践）

When to use

Use this skill when working with FastAPI code. It teaches current best practices and prevents common mistakes that AI agents make with outdated patterns.

Critical Rules

1. Use async def for I/O-bound endpoints, def for CPU-bound

Wrong (agents do this):

@app.get("/users")
def get_users():
    users = db.query(User).all()
    return users

@app.get("/data")
async def get_data():
    result = heavy_computation()
    return result

Correct:

@app.get("/users")
async def get_users(db: AsyncSession = Depends(get_db)):
    result = await db.execute(select(User))
    return result.scalars().all()

@app.get("/data")
def get_data():
    return heavy_computation()

Why: FastAPI runs async endpoints in the event loop; sync endpoints run in a thread pool. Use async for I/O (DB, HTTP, file) to avoid blocking. Use def for CPU-bound work; making it async would block the event loop.

2. Use Depends() for dependency injection

Wrong (agents do this):

db = get_database()

@app.get("/items")
async def get_items():
    return db.query(Item).all()

Correct:

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

@app.get("/items")
async def get_items(db: Annotated[Session, Depends(get_db)]):
    return db.query(Item).all()

Why: Global DB connections leak, are not testable, and bypass FastAPI's dependency system. Depends() provides proper scoping, cleanup, and test overrides.

3. Use Pydantic v2 patterns

Wrong (agents do this):

from pydantic import validator

class Item(BaseModel):
    name: str
    price: float

    class Config:
        orm_mode = True

    @validator("price")
    def price_positive(cls, v):
        if v <= 0:
            raise ValueError("must be positive")
        return v

Correct:

from pydantic import BaseModel, field_validator, ConfigDict

class Item(BaseModel):
    model_config = ConfigDict(from_attributes=True)
    name: str
    price: float

    @field_validator("price")
    @classmethod
    def price_positive(cls, v: float) -> float:
        if v <= 0:
            raise ValueError("must be positive")
        return v

Why: Pydantic v1 validator, Config, and orm_mode are deprecated. Use field_validator, model_validator, ConfigDict, and from_attributes.

4. Use lifespan context manager

Wrong (agents do this):

@app.on_event("startup")
async def startup():
    app.state.db = await create_pool()

@app.on_event("shutdown")
async def shutdown():
    await app.state.db.close()

Correct:

from contextlib import asynccontextmanager

@asynccontextmanager
async def lifespan(app: FastAPI):
    app.state.db = await create_pool()
    yield
    await app.state.db.close()

app = FastAPI(lifespan=lifespan)

Why: on_event is deprecated. The lifespan context manager gives a single place for startup and shutdown with proper resource ordering.

5. Use BackgroundTasks for fire-and-forget work

Wrong (agents do this):

@app.post("/send-email")
async def send_email(email: str):
    asyncio.create_task(send_email_async(email))
    return {"status": "queued"}

Correct:

@app.post("/send-email")
async def send_email(email: str, background_tasks: BackgroundTasks):
    background_tasks.add_task(send_email_async, email)
    return {"status": "queued"}

Why: asyncio.create_task can outlive the request and is not awaited on shutdown. BackgroundTasks runs after the response is sent and is tied to the request lifecycle.

6. Use APIRouter for route organization

Wrong (agents do this):

# main.py - 500 lines of routes
@app.get("/users")
@app.get("/users/{id}")
@app.post("/items")
@app.get("/items")

Correct:

# main.py
app.include_router(users.router, prefix="/users", tags=["users"])
app.include_router(items.router, prefix="/items", tags=["items"])

# routers/users.py
router = APIRouter()
@router.get("/")
@router.get("/{id}")

Why: Single-file apps become unmaintainable. APIRouter enables routers/, models/, services/, dependencies/ structure.

7. Use response_model for output validation

Wrong (agents do this):

@app.get("/items/{id}")
async def get_item(id: int):
    item = await db.get(Item, id)
    return {"id": item.id, "name": item.name}

Correct:

@app.get("/items/{id}", response_model=ItemOut)
async def get_item(id: int, db: Session = Depends(get_db)):
    item = await db.get(Item, id)
    if not item:
        raise HTTPException(status_code=404)
    return item

Why: Raw dicts bypass validation and OpenAPI. response_model ensures schema consistency, serialization, and docs.

8. Use status codes from fastapi.status

Wrong (agents do this):

raise HTTPException(status_code=404, detail="Not found")
raise HTTPException(status_code=401, detail="Unauthorized")

Correct:

from fastapi import status

raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="Not found")
raise HTTPException(status_code=status.HTTP_401_UNAUTHORIZED, detail="Unauthorized")

Why: Magic numbers are error-prone. status constants are self-documenting and match HTTP spec.

9. Use Annotated for dependencies

Wrong (agents do this):

@app.get("/me")
async def read_me(current_user: User = Depends(get_current_user)):
    return current_user

Correct:

@app.get("/me")
async def read_me(current_user: Annotated[User, Depends(get_current_user)]):
    return current_user

Why: Annotated is the recommended FastAPI pattern. It keeps types and dependencies in one place and supports dependency reuse.

10. Use pydantic-settings for configuration

Wrong (agents do this):

import os
DATABASE_URL = os.getenv("DATABASE_URL", "sqlite:///db.sqlite")

Correct:

from pydantic_settings import BaseSettings

class Settings(BaseSettings):
    database_url: str = "sqlite:///db.sqlite"
    debug: bool = False
    model_config = {"env_file": ".env"}

settings = Settings()

Why: os.getenv has no validation or typing. BaseSettings provides validation,.env loading, and type safety.

Patterns

• Define routers in routers/ with prefix and tags
• Put shared dependencies in dependencies.py
• Use HTTPException with status constants for errors
• Use Path, Query, Body, Header with validation (min_length, ge, le)
• Register custom exception handlers with app.add_exception_handler
• Use middleware sparingly; order matters (first added runs last for requests)

Anti-Patterns

• Do not use @app.on_event("startup") or @app.on_event("shutdown")
• Do not use asyncio.create_task for request-scoped background work
• Do not use global variables for DB, cache, or config
• Do not use Pydantic v1 @validator or class Config
• Do not return raw dicts without response_model
• Do not use magic numbers for status codes
• Do not put all routes in main.py