А давайте расскажу как в Osome организован contract first. Мы держим все контракты в отдельном репозитории, описываем спецификации в формате
В итоге получаем такую схему работы:
- PR в репозиторий контрактов с новым эндпоинтом / изменением существующего
- Прогон в CI статических проверок по всем проектам для проверки совместимости с внедряемыми изменениями (условно, не вызовет ли изменение типа поля
- Аппрув от всех заинтересованных лиц
- Внедрение и начало работы над фронтом и бэком
Из минусов:
- SDK идёт вперёд реализации. Нет гарантии, что описанный в SDK контракт уже реализован. Т.е. Сваггер не отражает напрямую состояние микросервиса.
- Сваггер общий для всех микросервисов. Понять с какой версией работает конкретный микросервис невозможно (даже если микросервис начнёт отдавать версию установленной в зависимостях SDK это не гарантия, что сам эндпоинт уже реализован)
- Исходя из двух предыдущих пунктов — критические изменения на бэкенде должны выкатываться максимально быстро вслед за изменениями контрактов.
- Иногда нужна сложная цепочка PR (поменять работу с полем в микросервисе, изменить поле в контракте, снова поменять микросервис, снова поменять контракт). Зато ни в какой момент система не будет сломана.
- Мобилки живут на внутренних типах вместо внешних контрактов, проверить статически совместимость с ними (в нашем случае) невозможно
tinyspec (да, местами сильно жмёт по ряду причин, есть планы с этим что-то делать). Из этой спеки генерируем openapi, а из него уже сваггер, json-schema ts-типы и удобный SDK (вот так вот openapi-ts-sdk).В итоге получаем такую схему работы:
- PR в репозиторий контрактов с новым эндпоинтом / изменением существующего
- Прогон в CI статических проверок по всем проектам для проверки совместимости с внедряемыми изменениями (условно, не вызовет ли изменение типа поля
userId на | undefined проблем)- Аппрув от всех заинтересованных лиц
- Внедрение и начало работы над фронтом и бэком
Из минусов:
- SDK идёт вперёд реализации. Нет гарантии, что описанный в SDK контракт уже реализован. Т.е. Сваггер не отражает напрямую состояние микросервиса.
- Сваггер общий для всех микросервисов. Понять с какой версией работает конкретный микросервис невозможно (даже если микросервис начнёт отдавать версию установленной в зависимостях SDK это не гарантия, что сам эндпоинт уже реализован)
- Исходя из двух предыдущих пунктов — критические изменения на бэкенде должны выкатываться максимально быстро вслед за изменениями контрактов.
- Иногда нужна сложная цепочка PR (поменять работу с полем в микросервисе, изменить поле в контракте, снова поменять микросервис, снова поменять контракт). Зато ни в какой момент система не будет сломана.
- Мобилки живут на внутренних типах вместо внешних контрактов, проверить статически совместимость с ними (в нашем случае) невозможно