Минорные изменения интеграций — обратная совместимость контракта

Директивный

Правило

Точечная правка действующей интеграции (добавить поле, поменять маппинг, подкрутить обработку) обязана сохранять контракт:

Расширять — можно, менять — нельзя. Новые поля в ответе/сообщении — только необязательные. Имя, тип, формат и семантика существующих полей не меняются; необязательное поле не становится обязательным.
Breaking-изменение = новая версия: новый путь (/v2/), новая версия формата пакета — со временем сосуществования обеих версий и согласованным планом вывода старой. «Мы поправим, а вы перевыпуститесь в тот же день» — не план.
Толерантный приём: неизвестные поля во входящих сообщениях игнорируются, а не роняют обработку — тогда и контрагент может расширять свою сторону без синхронного релиза.
«Мелкое» не значит «совместимое»: смена формата даты, кодировки, регистра ключей, порядка обязательных реквизитов, округления сумм — всё это ломающие изменения, даже если diff на три строки.
Изменение отражено в паспорте интеграции, владельцы систем-потребителей уведомлены до выката.

Зачем

У действующей интеграции есть потребители, которых вы не контролируете: чужой релизный цикл, чужой бюджет, иногда чужая компания. Переименованное «для красоты» поле означает, что все они упали одновременно — и это классическая авария из однострочного коммита. Правило то же, что для библиотек (#std644): в пределах версии поведение публичного контракта не меняется.

// Было в ответе сервиса:
{ "orderNo": "А-1042", "sum": 1500 }

// Стало после «косметической» правки — упали все потребители,
// парсившие orderNo и целые суммы:
{ "orderNumber": "А-1042", "sum": "1500.00" }

// Контракт расширен, старые потребители ничего не заметили:
{
  "orderNo": "А-1042",          // существующие поля не тронуты
  "sum": 1500,
  "sumPrecise": "1500.00",      // новое поле — необязательное
  "warehouse": "MSK-01"         // новое поле — необязательное
}
// Переезд на новую семантику — отдельным /v2/ с периодом сосуществования.

Когда не применять

Единственный потребитель — своя же система, и обе стороны выкатываются одним согласованным релизом (одна команда, одно окно) — допустим синхронный breaking; факт согласования фиксируется в задаче.
Интеграция ещё не в проде (пилот, песочница) — контракт можно менять свободно до первого боевого потребителя.