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.
• Prefer the typed markers FromPath[T] / FromQuery[T] / FromHeader[T] / FromCookie[T] (Litestar ≥ 2.22) over Annotated[T, Parameter()]; never use the field = Parameter(...) default form (removed in 3.0).
• 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

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 or DomainPlugin.

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

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

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

References Index

• routing.md
• domains.md
• example.md

Official References

• https://docs.litestar.dev/ - Litestar documentation
• https://docs.litestar.dev/latest/reference/ - Litestar API reference

Shared Styleguide Baseline

• General
• Python
• Litestar