fastapi

Sub-Skill: FastAPI

Purpose: Prevent common FastAPI and Pydantic mistakes. Apply these rules whenever writing or reviewing FastAPI route handlers, Pydantic schemas, or async API code.

Rules

1. Always declare request and response bodies as Pydantic models — never use raw dict or Any for I/O. Reference: ERR-2026-025

2. Always use Pydantic v2 syntax (model_config, model_dump, model_validate) unless the project explicitly pins Pydantic v1 (pydantic<2 in requirements). Reference: ERR-2026-025

3. Always declare route handlers as async def unless the handler calls blocking I/O that cannot be awaited; use run_in_executor for blocking calls inside async handlers.

4. Always specify an explicit response_model on every route decorator so FastAPI filters and validates the response shape.

5. Always use status_code on the route decorator (@app.post("/items", status_code=201)) rather than constructing a Response object just to set the status.

6. Never raise bare Exception in route handlers; raise HTTPException with a meaningful status_code and detail string, or define a custom exception with an exception handler.

7. Always register exception handlers via @app.exception_handler(MyError) for domain errors rather than catching them inside every route.

8. Use Depends() for shared logic (auth, DB sessions, pagination params) — never duplicate the same logic across multiple route functions.

9. Prefer APIRouter with a prefix and tags list to group related endpoints; register routers with app.include_router() rather than defining all routes on the app object.

10. Always configure CORS via CORSMiddleware with an explicit allow_origins list; never use allow_origins=["*"] in production.

11. Use the lifespan context manager (FastAPI ≥ 0.93) for startup/shutdown logic instead of the deprecated @app.on_event("startup") / @app.on_event("shutdown") decorators.

12. Always use BackgroundTasks (injected via Depends or as a route parameter) for fire-and-forget work; never asyncio.create_task inside a route without a lifecycle guard.