Контракты между командами: данные и API должны жить не на доверии, а на договоре
Почему внутренние интерфейсы требуют явных ожиданий - по структуре, по качеству и по совместимости.
Когда одна команда делает API, которым пользуется другая команда, возникает соблазн обойтись без формальностей. Все в одной компании, все знают друг друга, можно просто договориться на словах. Это работает, пока обе команды небольшие и сидят рядом. Вопрос о том, почему интеграции не должны рождаться по знакомству, - отправная точка; контракты - следующий шаг после принятия этого принципа.
Стоит одному из разработчиков уйти в отпуск или смениться приоритетам - и "устная договорённость" превращается в источник инцидентов. Поле переименовали. Формат даты поменяли. Новую версию задеплоили без предупреждения. Команда-потребитель узнаёт об этом по упавшему продакшену.
Что такое контракт в контексте внутреннего продукта
Контракт - это явно зафиксированное ожидание между двумя сторонами: что именно один компонент предоставляет другому, в каком формате, с какими гарантиями и как ведёт себя при изменениях.
Для API это может быть описание эндпоинтов и типов - что-то вроде документации, которая остаётся актуальной. Для данных - схема таблицы или файла, плюс описание того, что означает каждое поле, каков допустимый диапазон значений и что бывает на границах. Именно контракты делают возможным этап, когда интеграции превращаются в управляемый портфель.
Контракт не обязан быть сложным. Но он должен быть записан и известен обеим сторонам.
Почему доверие не работает как механизм
Проблема доверия не в злом умысле. Проблема в том, что каждая команда оптимизирует своё. Команда-производитель меняет внутреннюю структуру потому, что так удобнее с её точки зрения. Команда-потребитель не знает об этом изменении заранее, потому что никто не обязался её предупреждать.
В системах с несколькими командами это накапливается. Каждое такое изменение - небольшое. Но через год в кодовой базе команды-потребителя появляются десятки мест, где написано "если поле пустое - это значит X, если null - это Y, а если там строка 'N/A' - это вообще Z". Это не баги. Это адаптация к тому, что контракт не соблюдался.
Что делает явный контракт
Явный контракт меняет несколько вещей.
Он переводит разговор об изменениях в другую плоскость. Если контракт существует, его изменение - это событие, требующее координации. Нельзя просто переименовать поле и задеплоить. Нужно либо согласовать с потребителем, либо поддерживать обратную совместимость, либо версионировать.
Он делает ожидания по качеству данных явными. "Это поле всегда заполнено" или "может быть null, если клиент не указал" - это разные контракты, и команда-потребитель должна знать, с каким именно она работает.
Он упрощает диагностику. Когда что-то сломалось, первый вопрос - нарушил ли кто-то контракт? Это гораздо конкретнее, чем общий поиск причины.
Как выглядит минимальный контракт
Для большинства внутренних систем не нужна формальная спецификация на 50 страниц. Достаточно нескольких вещей:
- Описание структуры данных или интерфейса - типы, поля, форматы.
- Явное указание на то, какие поля обязательны, а какие опциональны.
- Политика изменений: как минимум за сколько времени предупреждается потребитель.
- Описание гарантий качества: каков допустимый процент ошибок, что происходит при недоступности.
Всё это может жить в README или в Wiki рядом с кодом. Главное - чтобы оно было актуальным и обе стороны знали, где это искать.
Простой тест
Если ваши команды обнаруживают изменения в интерфейсах по упавшим тестам или по инцидентам в продакшене, а не по заблаговременному уведомлению - контракты у вас не работают.
Несколько вопросов, которые помогают оценить ситуацию:
- Знает ли команда-потребитель, куда идти, чтобы понять, что именно им обещано?
- Есть ли процесс, который требует согласования при изменении публичного интерфейса?
- Описаны ли ожидания по качеству данных - не только структура, но и семантика полей?
- Что происходит, когда данные не соответствуют ожиданиям - есть ли явная обработка или молчаливая адаптация?
Там, где ответы неопределённые, доверие уже работает вместо договора. Рано или поздно оно подводит.