Contract First vs Code First: что выбрать

Существует два подхода к проектированию API.

• Code first — сначала пишем код, потом по нему генерируем контракт.
• Contract first — сначала создаем контракт, потом по нему пишем или генерируем код.

Контракт — это соглашение между поставщиком и потребителем об услуге. Чтобы правильно использовать услугу, потребитель сервиса должен полностью понимать договор.

Контракт включает в себя детали многих аспектов обслуживания, таких как:

1. Как вызвать сервис.
2. Какой транспорт используется.
3. Каковы структуры запроса и ответа.

Преимущества Code First

1. Контракты с минимальными усилиями. Это всего лишь побочный продукт разработки сервиса, так как он может быть автоматически сгенерирован из кода.
2. Синхронизация кода и контракта. Поскольку контракт генерируется из кода, они всегда синхронизируются друг с другом.

Недостатки Code First

1. Нет параллельной разработки. Производитель услуг и потребители услуг не могут разрабатывать параллельно. Сначала необходимо разработать сервис, затем сгенерировать контракт, и только после этого можно написать код потребителя, который будет придерживаться контракта. Без понимания контракта потребитель не может быть разработан.
2. Нет цели для команд. Поскольку договор не может быть известен до того, как сервис будет разработан, не существует цели для различных заинтересованных сторон в разработке. Следовательно, есть все шансы, что направления будут отклоняться, и будут внесены ненужные изменения, что приведет к напрасной трате усилий.
3. Нет кроссплатформенной совместимости. На некоторых старых платформах не так просто сгенерировать контракт из кода. В результате этого для сгенерированных контрактов довольно часто возникает несовместимость между платформами.

Преимущества подхода Contract First

1. Команды могут разрабатывать параллельно. Поскольку кодирование происходит на основе контракта, поставщики услуг и группы потребителей услуг четко понимают подход и детали коммуникации. Следовательно, разработка может происходить одновременно.
2. Команды знают, что ожидать. Поскольку кодирование происходит на основе контракта, команды производителей и потребителей имеют представление об ожиданиях друг друга. В результате, если межгрупповое тестирование невозможно из-за разных темпов разработки, программное обеспечение-заглушка может использоваться для моделирования поведения другой стороны на основе контракта.
3. Кроссплатформенная совместимость. Поскольку параметры сервиса зависят только от контракта, фактическая структура программного обеспечения, используемая для разработки сервиса, не имеет большого значения. Поставщик услуг и потребитель услуг могут использовать разные технологии.

Недостатки подхода Contract First

1. Требуются дополнительные начальные затраты. Большая часть этих затрат будет сосредоточена вокруг соглашения об обслуживании. Вы должны убедиться, что договор четко определен и не меняется очень часто.
2. Ограничение гибкости разработчиков. Разработчики вынуждены придерживаться условий контракта, что может ограничить их в экспериментировании с различными решениями.

Какой подход использовать?

Какой подход использовать в разработке – зависит от условий. Если критически важна скорость – лучше использовать Code First. Если есть время подумать о качестве – Contract First более эффективен.

📎 Статьи по теме

1. Contract first / Code first — в общих чертах про подходы
2. API-First и микросервисы — обзорная статья от ex-Accenture с практическими примерами
3. Как улучшить межсерверное взаимодействие и сэкономить время разработчика — статья о преимуществах Code First подхода
4. Design API First как паттерн проектирования контрактов межсервисного взаимодействия — цикл статей от SimbirSoft про опыт применения Code First

⏯ Вебинары

1. Опыт внедрения Contract-First OpenApi | Алексей Могилин, ЮMoney
2. Дружба — это чудо: подход Contract First для аналитиков и разработчиков. Роман Лаптев — выступление с конференции Flow
3. Contract First Principle в работе с API. Глеб Михеев, Skillbox