Правила проектирования и эволюции контрактов: gRPC, REST, события Kafka.
Единообразие и владение
- Один владелец контракта — сервис, предоставляющий API или публикующий события; изменения согласуются с потребителями; обратная совместимость обязательна в рамках мажорной версии.
- Схемы в репозитории — proto-файлы и описание событий (JSON Schema или документ) хранятся в репозитории; версионируются вместе с кодом; генерация клиентов/серверов из схем.
Обратная совместимость
- gRPC: не удалять поля, не менять номера полей и типы; новые поля — optional или с default. При несовместимых изменениях — новый пакет/версия (v2).
- REST: добавление полей в JSON — совместимо; удаление или смена типа — breaking; новая мажорная версия URL (/api/v2/).
- События: добавление полей в payload — совместимо; удаление или смена типа — новая версия типа события или топик; период dual-write при миграции.
Версионирование и депрекации
- Явное версионирование контрактов (v1 в пути или в заголовке); депрекации объявляются заранее с датой окончания поддержки; потребителям даётся время на миграцию.
- См. также Принципы проектирования API, Принципы проектирования событий.
Связанные страницы
- Контракты данных — типы контрактов и практика
- Принципы проектирования API — принципы API
- Каталог схем событий — каталог событий
- Бэкенд / Рекомендации по API — реализация в коде