fastapi-dev

Files (2)

• SKILL.md
• response-schemas.md · references/

SKILL.md (first lines)

# FastAPI development

- Always define an application factory (`create_app`) in `<module>/__init__.py` or `<module>/main.py` (prefer the former).
- Import routers in app factory and register them via `app.include_router`. Define a helper `_register_routers` function colocated with `create_app`.
- Define a custom exceptions module at `<module>/exceptions.py` with a base application error. Then register an exception handler via `@app.exception_handler(BaseAppError)` to return proper JSON responses.
- Ensure pydantic's `RequestValidationError` and `ValidationError` are handled too and transformed to a consistent error response format.
- All responses use generic envelope schemas (`APIResponse[T]`, `APIListResponse[T]`, `APIErrorResponse`) so the OpenAPI spec surfaces the wrapping. See `references/response-schemas.md`.

## Routers

Routers are thin HTTP boundaries. They handle authentication, authorization, query parameter parsing, and response shaping, nothing else. Business logic lives in plain functions called "operations".

- Common dependencies are declared as annotated aliases, e.g:
  - `UseDBSession = t.Annotated[Session, Depends(get_db_session)]` — SQLAlchemy session
  - `UseSettings = t.Annotated[Settings, Depends(get_settings)]` — Pydantic settings object
- Cross-cutting request context is bundled into a single `AppContext` dataclass injected via `Depends`. Adding new cross-cutting concerns (e.g. request ID) means updating the dataclass and its factory, not every operation signature.
- Follow the naming pattern `UseX`. If routers start to have many different dependencies, refactor the most common ones to a `UseAppContext`.

## Operations

Operations are plain functions (or coroutines) that receive:

1. `ctx: AppContext` as the first argument (or `session` and `settings`)
2. Input data (validated Pydantic schemas) as keyword arguments

They handle business logic and external service calls.

### Testing

- Override individual dependencies via `app.dependency_overrides`
- Operations are tested by calling them directly with a constructed `AppContext`

From richin13/dotfiles, MIT.

More from richin13/dotfiles