4.9 KiB
status, date, decision-makers, supersedes, superseded-by
| status | date | decision-makers | supersedes | superseded-by | |
|---|---|---|---|---|---|
| Proposed | 2026-10-11 |
|
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/healthPOST /api/v1/runtime/startPOST /api/v1/runtime/stopGET /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 из конфигурации.
Связанные решения
- Нет.