FastAPI Patterns

Async Traps

• - Mixing sync database drivers (psycopg2, PyMySQL) in async endpoints blocks the event loop — use async drivers (asyncpg, aiomysql) or run sync code in INLINECODE0
• INLINECODE1 in async endpoints blocks everything — use await asyncio.sleep() instead
• CPU-bound work in async endpoints starves other requests — offload to ProcessPoolExecutor or background workers
• Async endpoints calling sync functions that do I/O still block — the entire call chain must be async

Pydantic Validation

• - Default values in models become shared mutable state: items: list = [] shares the same list across requests — use INLINECODE5
• INLINECODE6 doesn't make a field optional in the request — add = None or use INLINECODE8
• Pydantic v2 uses model_validate() not parse_obj(), and model_dump() not .dict() — v1 methods are deprecated
• Use Annotated[str, Field(min_length=1)] for reusable validated types instead of repeating constraints

Dependency Injection

• - Dependencies run on every request by default — use lru_cache on expensive dependencies or cache in app.state for singletons
• INLINECODE15 without an argument reuses the type hint as the dependency — clean but can confuse readers
• Nested dependencies form a DAG — if A depends on B and C, and both B and C depend on D, D runs once (cached per-request)
• INLINECODE16 dependencies for cleanup (DB sessions, file handles) — code after yield runs even if the endpoint raises

Lifespan and Startup

• - @app.on_event("startup") is deprecated — use lifespan async context manager
• Store shared resources (DB pool, HTTP client) in app.state during lifespan, not as global variables
• Lifespan runs once per worker process — with 4 Uvicorn workers you get 4 DB pools

CODEBLOCK0

Request/Response

• - Return dict from endpoints, not Pydantic models directly — FastAPI handles serialization and it's faster
• Use status_code=201 on POST endpoints returning created resources — 200 is the default but semantically wrong
• INLINECODE22 with media_type="text/plain" for non-JSON responses — returning a string still gets JSON-encoded otherwise
• Set response_model_exclude_unset=True to omit None fields from response — cleaner API output

Error Handling

• - raise HTTPException(status_code=404) — don't return Response objects for errors, it bypasses middleware
• Custom exception handlers with @app.exception_handler(CustomError) — but remember they don't catch HTTPException
• Use detail= for user-facing messages, log the actual error separately — don't leak stack traces

Background Tasks

• - BackgroundTasks runs after the response is sent but still in the same process — not suitable for long-running jobs
• Tasks execute sequentially in order added — don't assume parallelism
• If a background task fails, the client never knows — add your own error handling and alerting

Security

• - OAuth2PasswordBearer is for documentation only — it doesn't validate tokens, you must implement that in the dependency
• CORS middleware must come after exception handlers in middleware order — or errors won't have CORS headers
• INLINECODE30 in path operation, not in router — dependencies on routers affect all routes including health checks

Testing

• - TestClient runs sync even for async endpoints — use httpx.AsyncClient with ASGITransport for true async testing
• Override dependencies with app.dependency_overrides[get_db] = mock_db — cleaner than monkeypatching
• INLINECODE35 context manager ensures lifespan runs — without with TestClient(app) as client: startup/shutdown hooks don't fire