Контракты данных

Previous Next

Контракты обмена данными между сервисами и с внешним миром: форматы, версионирование и совместимость.

Типы контрактов

gRPC (internal API)

  • Описание: Protocol Buffers в proto/aiops/<domain>/v1/.
  • Версионирование: путь v1; при несовместимых изменениях — новый пакет или суффикс (v2).
  • Правила: обратная совместимость — не удалять и не менять типы полей; новые поля — optional или с дефолтом.
  • Использование: Identity service, Credential service, внутренние вызовы между сервисами через API Gateway или напрямую в кластере.

REST (public API)

  • Описание: OpenAPI/Swagger при необходимости; форматы запроса/ответа — JSON.
  • Версионирование: в URL (/api/v1/...); при breaking changes — новая мажорная версия.
  • Использование: Session Token service, Account service, Auth Service — публичные API для клиентов.

События (Kafka)

  • Описание: схема в Event Schema Catalog; тело — JSON с event_type, version, occurred_at, payload.
  • Версионирование: поле version в payload; при несовместимых изменениях — новый тип события или топик.
  • Контракт: producer и consumer согласуют формат; старые потребители должны корректно игнорировать неизвестные поля или новые версии при необходимости.

Общие принципы

  • Контракт — это обязательство; изменения не должны ломать существующих клиентов без предупреждения и миграционного пути.
  • Документировать депрекации и сроки поддержки старых версий.
  • В тестах использовать контракты (contract tests, snapshot тесты для JSON/Proto) для раннего обнаружения поломок.

Связанные страницы

Системы-источники Каталог схем событий