Перейти к основному содержимому

ADR-0012: Contract-first между репозиториями

  • Status: accepted
  • Date: 2026-09-01

Контекст​

OpenAPI хранится в отдельном репозитории, но ручные HTTP DTO в сервисе уже расходились с ним по имени requestKey. В polyrepo нельзя подключить исходники соседней папки или общую multi-service сборку.

Решение​

portable-agent/contracts является единственным местом, где контракт редактируют вручную.

  • Все спецификации имеют одну SemVer-версию.
  • Pull request проверяется Redocly, тестами схем и oasdiff.
  • Тег vX.Y.Z создаёт GitHub Release с bundle спецификаций, SHA-256 и artifact attestation.
  • Сервис хранит закреплённый снимок release, чтобы сборка работала без сети.
  • OpenAPI Generator создаёт HTTP models и API interface только в build/.
  • Controller переводит generated models в команды service-слоя.
  • Domain, service и repository не зависят от generated-кода.
  • Обновление версии контракта выполняется отдельным pull request.

Generated-код не коммитится. Доменные классы не публикуются в общей библиотеке.

Причина​

Так контракт остаётся источником истины, но сервисы можно собирать независимо. Версия release делает обновление явным, а локальный снимок убирает сетевую зависимость из обычной сборки.

Последствия​

  • Ручные HTTP DTO удаляются после подключения генератора.
  • Breaking change требует новой major-версии, migration guide и явного approval maintainer-а.
  • Снимок спецификации дублирует файл физически, но его нельзя редактировать; источник и версия записаны рядом с ним.
  • Клиенты Java, Python и TypeScript генерируются только когда появляется реальный потребитель.
  • Git submodule и общий source-код между сервисами не используются.