Менеджер маршрутов
Tip
Когда стоит читать этот документ: когда требуются маршруты HTTP / WebSocket / SSE (включая широковещательные рассылки через пул соединений). Если нет — можно пропустить, это не влияет на использование остальных функций.
Менеджер маршрутов ErisPulse предоставляет унифицированное управление маршрутами HTTP и WebSocket, поддерживает регистрацию маршрутов нескольких адаптеров и управление жизненным циклом. В основе лежит уровень абстракции (в настоящее время FastAPI + Uvicorn)
Обзор
Основные функции менеджера маршрутов:
- Декораторы маршрутов: поддержка быстрой регистрации с помощью декораторов
@http/@get/@post/@put/@delete/@ws - Автоматическое внедрение: обработчикам маршрутов не требуется импортировать типы FastAPI, фреймворк автоматически внедряет абстрактные объекты
- Группировка маршрутов: поддержка
RouteGroupс префиксом и версией - Промежуточные обработчики маршрутов: поддержка перехвата запросов с сопоставлением по glob-паттернам
- Ограничение скорости: встроенное ограничение по алгоритму скользящего окна
- Поддержка CORS: включение кросс-доменного обмена ресурсами одним вызовом
- Заголовки безопасности: автоматическое добавление заголовков безопасности в ответы
- Автоматическая документация: интерактивная документация на основе OpenAPI
- Поддержка WebSocket: полное управление соединениями WebSocket, настраиваемая аутентификация и хуки жизненного цикла
- Интеграция с жизненным циклом: глубокая интеграция с системой жизненного цикла ErisPulse
- Поддержка SSL/TLS: поддержка защищённых соединений HTTPS и WSS
- Главная страница: поддержка регистрации модулями кнопок быстрого доступа на корневом маршруте
/, с поддержкой интернационализации
Абстрактные типы
ErisPulse предоставляет абстрактные типы серверной части, позволяя модулям не зависеть напрямую от FastAPI:
| Абстрактный тип | Аналог в FastAPI | Описание |
|---|---|---|
HttpRequest |
fastapi.Request |
Обёртка HTTP-запроса, полностью совместимый интерфейс |
WebSocketConnection |
fastapi.WebSocket |
Обёртка соединения WebSocket, дополнительно предоставляет хуки жизненного цикла |
WebSocketDisconnect |
fastapi.WebSocketDisconnect |
Исключение разрыва соединения WebSocket |
WebSocketConnectionнаследуется отWebSocketConnectionBaseи разделяет те же интерфейсы send/receive/iter/close с клиентским WebSocket (ClientWebSocket). Клиентский и серверный WebSocket могут использовать один и тот же код бизнес-логики.Через свойство
.rawможно получить доступ к нативному объекту FastAPI. Код, напрямую использующий типы FastAPI, также полностью совместим.
Декораторы маршрутов (рекомендуется)
Формы регистрации: с одним аргументом (рекомендуется) и с двумя
Декораторы маршрутов поддерживают две формы, рекомендуется форма с одним аргументом — она согласуется с командами / триггерами событий, пространство имён автоматически привязывается к текущему модулю:
from ErisPulse import router
# С одним аргументом (рекомендуется): автоматическая привязка имя_модуля/hello → фактический путь /my_module/hello
@router.get("/hello")
async def hello():
return {"ok": True}
# WebSocket с одним аргументом: @ws("chat") → /my_module/chat
@router.ws("chat")
async def chat(ws):
...
# С двумя аргументами: явное указание имени модуля (правила не меняются, используется при регистрации из кода других модулей/утилит)
@router.get("other_module", "/info")
async def get_info(request):
return {"method": request.method, "path": str(request.url)}
Note
Форма с одним аргументом требует регистрации в контексте загрузки модуля/адаптера (при загрузке фреймворк уже внедряет привязку);
вызов вне контекста с привязкой вызывает ValueError с подсказкой явно передать имя модуля.
HTTP-декораторы
from ErisPulse import router, HttpRequest
# Также можно явно указывать абстрактный тип
@router.post("/data")
async def post_data(request: HttpRequest):
data = await request.json()
return {"received": data}
@router.put("/data/{item_id}")
async def update_data(request):
return {"updated": True}
@router.delete("/data/{item_id}")
async def delete_data(request):
return {"deleted": True}
Правило автоматического внедрения: когда имя первого параметра обработчика —
requestилиreqи нет аннотации типа FastAPI, фреймворк автоматически внедряетHttpRequest. Обработчики без параметров или с иным именем параметра запроса не затрагиваются.
Соглашение о возвращаемых значениях (2.10+)
Возвращаемые значения обработчика поддерживают соглашение с кортежем (рекомендуемый способ, явное управление кодом состояния), dict/str/Response работают как прежде:
@router.post("/login")
async def login(request):
if not check_token(request):
# (body, status_code) → JSON 401
return {"error": "unauthorized", "message": "недействительный токен"}, 401
# (body, status_code, headers) может также содержать заголовки ответа
return {"user_id": 1}, 200, {"X-Request-Cost": "12ms"}
# Или использовать вспомогательную функцию respond() (message автоматически объединяется в тело ответа)
from ErisPulse import respond
@router.get("/me")
async def me():
return respond({"user_id": 1}, status_code=200, message="ok")
Параметры пути / запроса можно задавать напрямую нативными аннотациями FastAPI (item_id: int, page: int = 1),
о промежуточных обработчиках см. раздел Промежуточные обработчики маршрутов.
WebSocket-декораторы
from ErisPulse import WebSocketConnection, WebSocketDisconnect
# Базовый WebSocket (форма с одним аргументом)
@router.ws("ws")
async def websocket_handler(ws):
async for msg in ws.iter_text():
await ws.send_text(f"Echo: {msg}")
# WebSocket с хуками жизненного цикла
@router.ws("/ws/chat")
async def chat(ws: WebSocketConnection):
@ws.on_disconnect
async def on_disconnect(ws, reason="unknown"):
print(f"Пользователь отключился: {reason}")
@ws.on_error
async def on_error(ws, error=""):
print(f"Ошибка соединения: {error}")
async for msg in ws.iter_text():
await ws.send_text(f"Echo: {msg}")
# WebSocket с аутентификацией (токен читается из переменной окружения, не хардкодьте его в коде)
import os
async def ws_auth(ws: WebSocketConnection) -> bool:
token = ws.query_params.get("token")
expected = os.environ.get("ERISPULSE_WS_TOKEN", "")
return bool(expected) and token == expected
@router.ws("secure_ws", auth_handler=ws_auth)
async def secure_ws_handler(ws):
while True:
data = await ws.receive_text()
await ws.send_text(f"Echo: {data}")
Примечание: обработчики WebSocket и обработчики аутентификации также поддерживают автоматическое внедрение.
WebSocketConnectionможно получить без аннотаций параметров. При аннотацииfastapi.WebSocketтакже передаётся нативный объект, но рекомендуется использовать абстрактный тип.
Автоматическая регистрация соединений (пул соединений, 2.10+)
Соединения, установленные через @ws / @sse, по умолчанию автоматически регистрируются в пуле соединений фреймворка (можно отключить с помощью track=False):
внутри handler доступны ws.id / ws.join_group(...), любой модуль может
просматривать соединения своего модуля через connections.list(namespace=...) и рассылать сообщения группам.
Подробнее см. Пул соединений и широковещательные рассылки.
Традиционный способ регистрации
async def hello_handler(request):
return {"message": "Hello World"}
# Базовая регистрация
router.register_http_route(
module_name="my_module",
path="/hello",
handler=hello_handler,
methods=["GET"],
)
# С ограничением скорости и информацией для документации
router.register_http_route(
module_name="my_module",
path="/api/data",
handler=data_handler,
methods=["POST"],
rate_limit="10/minute",
summary="Интерфейс данных",
tags=["API"],
)
Регистрация WebSocket
from ErisPulse.Core import WebSocketConnection
async def websocket_handler(ws: WebSocketConnection):
async for msg in ws.iter_text():
await ws.send_text(f"Echo: {msg}")
# Базовая регистрация
router.register_websocket(
module_name="my_module",
path="/ws",
handler=websocket_handler,
)
# Регистрация с аутентификацией (рекомендуется)
async def auth_handler(ws: WebSocketConnection) -> bool:
token = ws.query_params.get("token")
return token == "secret"
router.register_websocket(
module_name="my_module",
path="/secure_ws",
handler=websocket_handler,
auth_handler=auth_handler,
)
Описание параметров:
| Параметр | Описание | Значение по умолчанию |
|---|---|---|
module_name |
Имя модуля (обязательно) | - |
path |
Путь WebSocket | - |
handler |
Функция-обработчик | - |
auth_handler |
Функция аутентификации, возврат False автоматически закрывает соединение |
None |
auto_accept |
Выполнять ли автоматический accept() |
True |
Рекомендация: используйте
auth_handlerдля подтверждения соединения вместо отключенияauto_accept. Устанавливайтеauto_accept=Falseтолько если вам нужен полный контроль над процессом соединения.
Хуки жизненного цикла WebSocket
WebSocketConnection предоставляет регистрацию колбэков отключения и ошибок, не требующую ручного try/catch:
from ErisPulse.Core import WebSocketConnection
@router.ws("my_module", "/ws")
async def my_ws(ws: WebSocketConnection):
# Регистрация через декоратор
@ws.on_disconnect
async def on_close(ws, reason="unknown"):
print(f"Причина отключения: {reason}")
# Также можно вызвать напрямую
async def on_err(ws, error=""):
print(f"Ошибка: {error}")
ws.on_error(on_err)
# Обычная бизнес-логика
async for msg in ws.iter_text():
await ws.send_text(f"Echo: {msg}")
Группировка маршрутов
# Создание группы маршрутов с префиксом
group = router.group("my_module", prefix="/v1")
@group.get("/users")
async def list_users(request):
return {"users": []}
@group.post("/users")
async def create_user(request):
return {"created": True}
# Фактический путь: /my_module/v1/users
Промежуточные обработчики маршрутов
Промежуточные обработчики поддерживают сопоставление путей по glob-паттернам:
@router.middleware("/my_module/*")
async def auth_middleware(request, call_next):
token = request.headers.get("Authorization")
if not token:
return {"error": "Unauthorized"}
return await call_next(request)
@router.middleware("/my_module/admin/*")
async def admin_middleware(request, call_next):
return await call_next(request)
Идентификатор корреляции запросов (X-Request-ID)
Начиная с 2.7.0, каждый HTTP-запрос содержит идентификатор корреляции X-Request-ID, используемый для связывания логов / трассировки:
- Правило генерации: сначала используется заголовок запроса
X-Request-ID, переданный клиентом (сценарий распределённой трассировки); иначе UUID генерируется автоматически - Заголовок ответа: в ответ записывается
X-Request-ID, что позволяет клиенту сопоставлять запросы с логами - События жизненного цикла: в данные событий
server.requestиserver.responseдобавлено полеrequest_id
# Прослушивание событий запросов в модуле, связывание запрос-ответ по request_id
@sdk.lifecycle.on("server.request")
async def on_request(data):
print(f"[{data['request_id']}] {data['method']} {data['path']}")
@sdk.lifecycle.on("server.response")
async def on_response(data):
print(f"[{data['request_id']}] -> {data['status_code']}")
Клиент может задать свой ID для трассировки между сервисами:
curl -H "X-Request-ID: my-trace-id" http://localhost:8080/my_module/health
Ограничение скорости
Ограничение скорости маршрутов с использованием алгоритма скользящего окна:
@router.get("my_module", "/limited", rate_limit="10/minute")
async def limited_endpoint(request):
return {"ok": True}
@router.post("my_module", "/submit", rate_limit="5/minute")
async def submit_data(request):
return {"submitted": True}
Формат ограничения скорости: {количество}/{временное_окно}, например 10/minute, 100/hour.
Настройка CORS
router.setup_cors(
allow_origins=["https://example.com"],
allow_methods=["GET", "POST"],
allow_headers=["*"],
)
Также можно настроить через config.toml:
[router.cors]
allow_origins = ["https://example.com"]
allow_methods = ["GET", "POST"]
allow_headers = ["*"]
Заголовки безопасности
router.setup_security_headers()
Автоматически добавляются заголовки безопасности, такие как X-Content-Type-Options, X-Frame-Options, X-XSS-Protection.
Также можно настроить через config.toml:
[router.security]
enabled = true
Автоматическая документация
Router по умолчанию включает интерактивную документацию OpenAPI:
# Отключение документации
router.disable_docs()
# Настройка информации о документации
router.set_docs_info(
title="My API",
description="Документация API",
version="1.0.0"
)
Обработка путей
К путям маршрутов автоматически добавляется имя модуля в качестве префикса во избежание конфликтов:
# Регистрация пути "/api" для модуля "my_module"
# Фактический путь доступа: "/my_module/api"
router.register_http_route("my_module", "/api", handler)
Warning
Путь маршрута (включая префикс имени модуля) чувствителен к регистру. Регистр фактического пути совпадает с регистром имени модуля при регистрации: если имя модуля Test, фактический путь для зарегистрированного /api будет /Test/api, а обращение к /test/api вернёт 404.
Системные маршруты
Менеджер маршрутов автоматически предоставляет следующие системные маршруты:
Проверка работоспособности
GET /health
# Возвращает:
{"status": "ok", "service": "ErisPulse Router"}
Корневая страница
GET /
# Возвращает страницу бренда ErisPulse
Корневой маршрут / отображает страницу бренда ErisPulse, автоматически определяет доступность Dashboard и добавляет кнопку входа.
Главная страница
Менеджер маршрутов позволяет внешним модулям регистрировать кнопки быстрого доступа на корневом маршруте /, что упрощает пользователям быстрый доступ к страницам управления модулей.
Регистрация точки входа
# Простая регистрация
router.register_home_entry(
name="Моя панель",
url="/mymodule/admin",
)
# Регистрация с иконкой (SVG)
router.register_home_entry(
name="Консоль",
url="/console",
icon_svg='<svg width="18" height="18" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.8"><path d="M4 17l6-6-6-6"/><path d="M12 19h8"/></svg>',
)
# Регистрация с поддержкой интернационализации (формат i18n-словаря проекта)
router.register_home_entry(
name={"i18n": "mymodule.home.entry", "default": "Моя панель"},
url="/mymodule/admin",
)
Описание параметров:
| Параметр | Тип | Описание | Обязательный |
|---|---|---|---|
name |
str / dict |
Отображаемый текст кнопки; при передаче словаря {"i18n": "key", "default": "текст"} используется интернационализация |
Да |
url |
str |
Адрес ссылки кнопки | Да |
icon_svg |
str |
Необязательная SVG-иконка | Нет |
Автоматическая регистрация Dashboard
Когда обнаруживается доступный sdk.Dashboard, менеджер маршрутов автоматически добавляет кнопку Dashboard в начало списка точек входа, ручная регистрация не требуется.
Интеграция с жизненным циклом
from ErisPulse.Core import lifecycle
@lifecycle.on("server.start")
async def on_server_start(event):
print(f"Сервер запущен: {event['data']['base_url']}")
@lifecycle.on("server.stop")
async def on_server_stop(event):
print("Сервер останавливается...")
Расширенные свойства объекта запроса
Помимо базовых свойств method / query / headers / json / body,
HttpRequest также предоставляет расширенные возможности (часто используются в middleware аутентификации и длительных задачах с отслеживанием отключений):
| Свойство / метод | Описание |
|---|---|
request.session |
Словарь сессии (требуется поддержка middleware сессий), сохраняется между запросами |
request.auth |
Информация аутентификации (записывается middleware аутентификации) |
request.user |
Объект текущего пользователя (записывается middleware аутентификации) |
request.url_for(name, **params) |
Обратная маршрутизация: генерация URL по имени маршрута |
await request.is_disconnected() |
Отключился ли клиент (для выхода из SSE / длительных задач с опросом) |
request.raw |
Нативный объект запроса Starlette («аварийный люк», см. описание совместимости в следующем разделе) |
Аварийный люк: router.app
router.app напрямую предоставляет экземпляр приложения FastAPI (создаётся лениво, при первом обращении загружается
web-стек и регистрируются основные маршруты), покрывая сценарии, недостижимые через декораторы — монтирование подприложений, глобальные middleware,
интеграция с экосистемой FastAPI (StaticFiles / шаблоны фоновых задач и т.д.):
from ErisPulse.Core import router
from starlette.staticfiles import StaticFiles
app = router.app
app.mount("/static", StaticFiles(directory="static"), name="static")
Warning
Границы совместимости: router.app — это аварийный люк, а не стабильный контракт — вы получаете экземпляр текущего
web-стека (FastAPI/Starlette). Если фреймворк в будущем сменит базовую web-реализацию, код, зависящий
от внутренней структуры app (порядок middleware, специфичные для Starlette API), столкнётся с критическими
изменениями. Приоритетно используйте слой абстракции @router.http / HttpRequest (аналогично
request.raw) и локализуйте использование .app в отдельном адаптерном слое модуля — при миграции потребуется изменить только одну точку.
Лучшие практики
- Приоритетное использование абстрактных типов: используйте
HttpRequest/WebSocketConnectionвместоfastapi.Request/fastapi.WebSocket, чтобы избежать жёсткой зависимости - Использование автоматического внедрения: назовите первый параметр обработчика
requestилиreq, и вы получитеHttpRequestбез каких-либо аннотаций типов - Приоритет формы с одним аргументом: в контексте загрузки модуля предпочтительна форма с одним аргументом (автоматическая привязка пространства имён); при регистрации из кода других модулей/утилит явно передавайте имя модуля
- Использование группировки маршрутов: организуйте несколько маршрутов одного модуля с помощью
group() - Соображения безопасности: реализуйте механизмы аутентификации и заголовки безопасности для чувствительных операций
- Разумное ограничение скорости: устанавливайте ограничения скорости для часто вызываемых интерфейсов
- Использование хуков жизненного цикла: обрабатывайте исключения WebSocket через
@ws.on_disconnect/@ws.on_error, избегая ручного try/catch - Ограниченное использование аварийного люка:
router.app/request.rawиспользуйте только когда слой абстракции не может выразить нужное, и локализуйте зависимости в одной точке, сокращая объём адаптации при миграции базовой реализации фреймворка
Связанная документация
- Сетевой клиент - отправка запросов с помощью встроенного клиента
- Руководство по разработке модулей - знакомство с регистрацией маршрутов модулей
- Лучшие практики - рекомендации по использованию маршрутов