litestar-routing

Litestar Routing

Use this skill for route handlers, Controllers, Routers, domain clustering, and endpoint module layout.

Code Style Rules

• Cluster Controllers by domain, not HTTP method.
• Keep handlers thin: parse request data, call a service, return a DTO or response object.
• Put shared path, dependencies, guards, and tags on the Controller class.
• Use FromPath[T], FromQuery[T], FromHeader[T], and FromCookie[T] for unconstrained request parameters.
• Use Annotated[T, PathParameter(...)], QueryParameter(...), HeaderParameter(...), or CookieParameter(...) when the parameter needs constraints, metadata, or a wire name. Do not use implicit parameters or the deprecated field: T = Parameter(...) form.
• Use typed path parameters and explicit return annotations.

Quick Reference

• Controller and route patterns: routing.md
• Domain folder layout: domains.md
• End-to-end vertical slice: example.md
• Automatic domain-package registration: litestar-autowire

Workflow

1. Identify the domain boundary and URL prefix.
2. Pick a Controller when routes share path, guards, dependencies, or tags.
3. Keep data access in services and validation in DTOs.
4. Wire the Controller into the app explicitly or through Litestar Autowire.

Guardrails

• Do not group Controllers by HTTP method.
• Do not put authorization logic in handlers; use Guards.
• Do not hand-roll query parameter pagination; use the data-services skill.
• Do not put app-wide plugin setup in route modules.

Validation Checkpoint

• Routes are domain-clustered.
• Handlers are async when they perform I/O.
• Shared guards and dependencies live on the Controller.
• DTO and service concerns link to their owning skills.

Example

from litestar import Controller, get
from litestar.di import NamedDependency


class UserController(Controller):
    path = "/users"

    @get("/")
    async def list_users(
        self,
        users_service: NamedDependency[UserService],
    ) -> list[UserRead]:
        return await users_service.list_users()