PLBA2-4. Доработка регистрации http эндпоинтов
This commit is contained in:
@@ -0,0 +1,55 @@
|
||||
---
|
||||
status: Proposed
|
||||
date: 2026-10-11
|
||||
decision-makers:
|
||||
- Владелец проекта
|
||||
supersedes: []
|
||||
superseded-by: null
|
||||
---
|
||||
|
||||
# ADR-0001: Нейминг API-путей и маршрутизация сервисов через Caddy
|
||||
|
||||
## Контекст и проблема
|
||||
|
||||
На платформе PLBA будет работать несколько сервисов с одинаковыми шаблонами API-путей. PLBA предоставляет общие endpoints управления приложением, а сервисы должны иметь возможность добавлять собственные endpoints в тот же HTTP API и listener. Фронтенду также нужно однозначно выбирать сервис при вызове API.
|
||||
|
||||
Существующие endpoints `/health`, `/runtime/start`, `/runtime/stop` и `/runtime/status` не содержат версии API. Внешний ingress платформы построен на Caddy с `caddy-docker-proxy`.
|
||||
|
||||
## Факторы решения
|
||||
|
||||
- Все endpoints конкретного сервиса должны находиться в одном версионируемом пространстве путей.
|
||||
- Правило версионирования применяется к endpoints PLBA и к endpoints, добавленным приложением.
|
||||
- Сервисы должны использовать одинаковые внутренние пути независимо от имени сервиса на платформе.
|
||||
- Внешний запрос должен однозначно маршрутизироваться к нужному сервису через Caddy.
|
||||
- PLBA не запускает отдельный HTTP listener; control- и прикладные endpoints обслуживаются через общий listener сервиса.
|
||||
|
||||
## Рассмотренные варианты
|
||||
|
||||
- **Включать имя сервиса во внутренние пути** — например, `/{service-name}/api/v1/orders`. Маршрут явно различает сервисы, но связывает путь приложения с его именем и конфигурацией размещения.
|
||||
- **Добавлять имя сервиса на ingress** — внешний путь имеет вид `/{service-name}/api/v1/orders`, а Caddy выбирает upstream и удаляет `/{service-name}` перед передачей запроса. Внутренний путь сервиса остаётся `/api/v1/orders`.
|
||||
|
||||
## Решение
|
||||
|
||||
Предлагается принять второй вариант.
|
||||
|
||||
Путь endpoint внутри сервиса начинается с `/api/v{version}/...`, где версия задаётся сегментом пути, например `v1`. Это правило распространяется на все endpoints сервиса, включая endpoints PLBA. В версии `v1` пути PLBA будут такими:
|
||||
|
||||
- `GET /api/v1/health`
|
||||
- `POST /api/v1/runtime/start`
|
||||
- `POST /api/v1/runtime/stop`
|
||||
- `GET /api/v1/runtime/status`
|
||||
|
||||
Внешний путь фронтенда начинается с `/{service-name}/api/v{version}/...`. `service-name` — стабильный slug сервиса, настроенный на ingress. Caddy направляет запрос соответствующему upstream и удаляет service-префикс. Приложение получает запрос уже по внутреннему пути `/api/v{version}/...`.
|
||||
|
||||
PLBA предоставляет общую точку маршрутизации для своих endpoints и endpoints, зарегистрированных приложением. Приложение не создаёт для прикладных endpoints параллельный HTTP listener.
|
||||
|
||||
## Последствия
|
||||
|
||||
- Положительные: сервисы сохраняют единый набор путей; имя размещённого сервиса остаётся настройкой ingress; новые версии API можно публиковать отдельными путями.
|
||||
- Отрицательные или компромиссы: Caddy должен иметь маршрут для каждого публичного service-prefix и корректно удалять его перед проксированием.
|
||||
- Существующие клиенты, прямые вызовы сервисов и health checks нужно перевести на версионированные внутренние пути.
|
||||
- Если приложение формирует абсолютные ссылки на свои endpoints, оно должно учитывать внешний публичный префикс или получать публичный base URL из конфигурации.
|
||||
|
||||
## Связанные решения
|
||||
|
||||
- Нет.
|
||||
Reference in New Issue
Block a user