Router

Регистрация API на классах через @route, токены пути, параметры и Swagger-метаданные

Обзор

Маршрутизация в Fusion Python декларативна. Вы декорируете подкласс FusionBaseApi через @route(...). При импорте класс регистрируется; когда приложение монтируется, каждый определённый HTTP-метод (get, post, …) становится реальным маршрутом в Rust-ядре.

from fusion_framework.api import FusionBaseApi
from fusion_framework.route import route
from fusion_framework import status


@route("api/[module]/{id}", tags=["items"], desc="Items by id")
class ItemModule(FusionBaseApi):
    def get(self, id: int):
        return self.response({"id": id}, status=status.HTTP_SUCCESS)

Импортируйте модуль из main.py, чтобы регистрация прошла до listen().

`@route` vs `router`

Символ	Роль
`route(path, **options)`	Основной декоратор — путь + Swagger + middleware / roles
`router(path)`	Алиас `route(path)` без дополнительных метаданных

Для нового кода предпочитайте @route.

Шаблоны пути

Сегменты пути разрешаются при регистрации класса.

Токен	Значение	Пример
Статический текст	Точный сегмент	`api` → `/api/...`
`[module]`	Стем имени класса в нижнем регистре, без `Module` / `MODULE`	`ProductModule` → `product`
`{name}`	Динамический path-параметр, привязанный к аргументу хендлера	`{id}` → `id: int`

@route("api/[module]/{id}")
class ProductModule(FusionBaseApi):
    def get(self, id: int):
        ...
# Resolves to: /api/product/{id}

Префикс версии

Передайте version=, чтобы префиксировать разрешённый путь:

@route("api/[module]/", version="v1")
class ProductModule(FusionBaseApi):
    ...
# → /v1/api/product/

Опции Swagger / OpenAPI

Влияют только на документацию (Swagger UI / openapi.json), не на runtime-маршрутизацию:

Аргумент	Тип	Назначение
`tags`	`list[str]`	Группировка операций в Swagger
`desc`	`str`	Описание
`title`	`str`	Summary / title
`version`	`str`	Префикс пути (также версионирование API)
`deprecated`	`bool`	Пометить операции устаревшими

Глобальные настройки Swagger UI (path, auth, UI) живут в fusion.<env>.json — см. Команды и окружения.

Route middleware и roles

Аргумент	Назначение
`middleware`	Список callable `(request, call_next)` только для этого маршрута
`roles`	Сокращение — добавляет role guard (ожидает JWT payload в `request["state"]["jwt"]`)

@route("api/admin", roles=["admin", "super_admin"])
class AdminModule(FusionBaseApi):
    def get(self):
        user = self.state.get("jwt", {})
        return self.response({"sub": user.get("sub")})

Полная модель (глобальный vs route) — в Middleware.

Привязка параметров

Аргументы хендлера заполняются из запроса автоматически:

Имя совпадает с параметром path → path
Иначе если метод POST / PUT / PATCH и имя есть в JSON body → body
Иначе если имя есть в query → query
Отсутствующие опциональные / с default аргументы приходят как None

@route("api/[module]/{id}")
class ItemModule(FusionBaseApi):
    def get(self, id: int):
        # GET /api/item/12
        return self.response({"id": id})

    def post(self, id: int, title: str = "untitled"):
        # id ← path, title ← JSON body
        return self.response({"id": id, "title": title}, status=status.HTTP_201_CREATED)

Типы (int, str, float, bool, Optional[...]) управляют coercion. Невалидные значения дают 400.

Request view на классе

Внутри хендлера всегда есть self:

Свойство	Источник
`self.method`	HTTP-метод
`self.path`	Путь запроса
`self.body`	Сырое тело строкой
`self.headers`	Карта заголовков
`self.params`	Path-параметры
`self.query`	Query string
`self.state`	Per-request данные из middleware

def get(self):
    return self.response({
        "path": self.path,
        "q": self.query.get("q"),
    })

Ответы и ошибки

return self.response({"ok": True}, status=status.HTTP_SUCCESS)

from fusion_framework.http import HTTPException
raise HTTPException(404, {"detail": "not found"})

Dict / list кодируются в JSON ядром. Для async def хендлеров см. Async.

Router

На этой странице