Принципы контрактов в интеграциях: версии схем, совместимость и миграции

Интеграции ломаются не потому, что разработчики «плохие» — а потому, что контракты между системами меняются в реальном времени, а инерция у клиентов всегда выше. Один сервис выкатывается чаще, другой реже. Где-то очередь событий «переварит» изменения, а где-то есть жёстко закодированные десериализации и строгие схемы.

Чтобы интеграции оставались живыми, нужно системно подойти к контрактам: договориться о правилах версионирования схем, определить, что считается breaking/non-breaking изменением, обеспечить обратную совместимость и продумать миграции данных. В этой статье разложим практическую стратегию версионирования API и событий, которая помогает не ломать клиентов и снизить стоимость изменений.

Контракт как продукт: что именно мы версионируем

Под «контрактом» в интеграциях часто подразумевают HTTP API (эндпоинты, запросы/ответы) или события (формат payload, семантика полей, порядок). Но на деле контракт — это набор гарантий:

• Синтаксис: структура и типы данных (схемы).
• Семантика: значения и их смысл (например, status="active" означает одно и то же в разных версиях).
• Поведение: ошибки, коды ответов, ретраи, идемпотентность, гарантия доставки (at-least-once/exactly-once — если это про события).
• Тайминг: SLA на обработку, ожидания относительно порядка/окон.
• Нефункциональные аспекты: ограничения размера сообщений, частота, таймауты, требования к авторизации.

Версионирование должно охватывать хотя бы первые три пункта. Иначе вы «переименуете поле», но клиент будет ожидать другой смысл — и всё равно получите поломку.

Основные модели версионирования: URL, заголовки, схемы и контент-тип

Прежде чем говорить о правилах изменений, важно определить, как клиент узнает версию контракта.

Версионирование API в URL

Самый распространённый подход: /v1/orders, /v2/orders. Его плюсы — простота и прозрачность. Минусы — необходимость обслуживать несколько версий одновременно и возможная «загонка» клиентов на конкретную структуру URL.

Правило для практики: URL-версии чаще подходят для API с запрос-ответ (REST/HTTP), где клиент явно выбирает версию.

Версионирование через заголовки

Например, Accept: application/vnd.company.orders+json; version=2. Плюсы — менее шумные URL; минусы — больше требований к клиентам и инфраструктуре (API gateway, прокси, документация).

Правило: этот вариант удобен, когда у вас много клиентов и вы хотите управлять миграцией централизованно.

Версионирование событий внутри схемы

Для событий обычно используют один из признаков:

• event_type с суффиксом версии: order.created.v1, order.created.v2;
• поле schema_version/spec_version в payload или в envelope;
• номер схемы (например, в связке с Schema Registry).

Правило: для событий версионирование должно быть совместимо с очередями, повторными доставками и долгоживущими потребителями. То есть важно, чтобы «старые» потребители продолжали понимать события.

Схемы: JSON Schema / Avro / Protobuf / OpenAPI

Ключевая идея: версионируйте схемы так, чтобы можно было формально доказать совместимость. OpenAPI пригоден для API, но для событий часто лучше работают схемы, поддерживающие эволюцию.

• Protobuf исторически хорошо поддерживает backward/forward compatibility на уровне форматов.
• Avro и JSON Schema также позволяют практики совместимости, но дисциплина особенно важна.
• OpenAPI больше про документацию, хотя и позволяет описывать варианты.

Breaking vs non-breaking: как отличать изменения, не ломая клиентов

Центральная часть стратегии — классификация изменений.

Breaking: что обычно ломает

Рассмотрим типовые breaking-изменения:

1. Удаление полей, на которые опираются клиенты.
2. Изменение типа поля (string → number, int32 → int64) без совместимости.
3. Изменение семантики: например, total_amount раньше в копейках, теперь в рублях.
4. Смена идентификаторов сущностей: например, orderId переезжает на id и меняется формат.
5. Изменение правил обработки ошибок: другая структура body при 4xx/5xx, разные коды, изменённый contract на idempotency.
6. Изменение требований обязательности: было optional, стало required — для клиентов без этого поля это breaking.
7. Семантика валидации: старые значения теперь считаются недопустимыми.
8. Сжатие/расширение ограничений без политики (например, уменьшили max длину строки).

Non-breaking: что обычно безопасно

Практика показывает, что non-breaking чаще всего — это расширения:

1. Добавление новых полей как optional (или с дефолтами).
2. Добавление новых enum значений (при условии, что клиенты не падают на неизвестных).
3. Расширение диапазонов (увеличение max, ослабление regex) — обычно безопасно.
4. Улучшение текста ошибок — чаще не ломает.
5. Добавление новых необязательных обработок/флагов, если они не меняют существующие правила.

Критически важно: «не ломает» на уровне формата ≠ «не ломает» на уровне логики

Клиент может успешно распарсить JSON, но начать неправильно рассчитывать итоги, если нарушилась семантика. Поэтому в контракте важно разделять:

• формат (можно ли распарсить),
• смысл (что означает значение),
• контракт поведения (какой процесс ожидать).

Обратная совместимость: forward/backward и где проходит граница ответственности

Для интеграций обычно выделяют две стороны:

• Backward compatibility: новая версия сервиса должна быть совместима со старой версией клиента. То есть клиенты, которые не обновились, должны продолжать работать.
• Forward compatibility: старые клиенты должны корректно обрабатывать ответы/события новых версий (или хотя бы не падать).

На практике чаще важнее backward compatibility — потому что мы контролируем сервер и можем поддерживать старые контракты дольше.

Обратная совместимость для API (HTTP request-response)

Для запросов клиента:

• Если клиент отправляет тело по версии v1, сервер v2 должен принимать его и адекватно обрабатывать.
• Если сервер добавляет новые поля в ответ, клиент v1 должен игнорировать неизвестные поля.

Практический подход:

• новые поля в request можно считать optional;
• новые поля в response — всегда добавлять без удаления старых;
• изменения обязательности — избегать или делать через версии.

Обратная совместимость для событий

Для событий важно понимать, что клиенты могут:

• быть не в курсе новой схемы,
• быть «медленными»,
• получать ретраи и дубликаты.

Обычно стратегия такая:

• Envelope события должен включать метаданные, которые не меняются критически.
• Payload эволюционирует добавлением optional полей.
• Старые потребители должны либо игнорировать новые поля, либо иметь механизм обработки schema_version.

Если вы используете Schema Registry, совместимость часто можно формализовать на уровне registry. Если без неё — дисциплина и тесты критичны.

Стратегия версионирования схем: стабильность полей, идентификаторы и эволюция

Версионирование — это не только номер версии. Это правила для жизни полей и структур.

Принцип «никогда не переиспользуй идентификаторы»

В схемах (особенно Protobuf/Avro) есть номера полей или идентификаторы. Переиспользование номера поля означает, что старые клиенты могут интерпретировать новые данные как старые.

Правило:

• удалённое поле нельзя «назначить заново» другой семантикой;
• если нужно отказаться от поля — помечайте его как deprecated и перестаньте заполнять, но не меняйте тип/значение смысла.

Добавляй, а не переписывай

Наиболее безопасная эволюция выглядит так:

1. Добавили новые optional поля.
2. В новых версиях клиенты читают новые поля.
3. Через депрекацию перестали поддерживать старые поля.

Такой путь требует времени, но снижает риски.

Default values и совместимость

Если клиент/десериализация ожидает отсутствие поля:

• для optional полей можно использовать дефолты на стороне клиента,
• для некоторых форматов — дефолты на уровне схемы.

Однако дефолты должны быть семантически корректными. «0 по умолчанию» может быть опаснее отсутствия поля, если 0 валидно и означает «активное значение», а отсутствие — «неизвестно».

Enum: осторожно с неизвестными значениями

Если клиент жестко мапит enum в switch с исключением по умолчанию — добавление нового значения может стать breaking. Поэтому:

• для enum используйте подход «unknown» (в Protobuf это делается нативно);
• или заранее договоритесь, что неизвестные значения игнорируются/логируются.

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

Версионирование контракта — это одна половина проблемы. Вторая — миграция данных: как обеспечить согласованность, когда старые и новые версии работают вместе.

Два режима: миграция «на лету» и «двухфазная»

Есть два частых паттерна.

1) «На лету» (strangler/expand-contract)

• На сервере одновременно поддерживаются старое и новое поведение.
• Данные начинают производиться в новом формате.
• Потребители обновляются постепенно.
• После того как все клиенты мигрировали — удаляете старое.

Минус — растёт сложность сервера, плюс нужны мониторинг и тесты.

2) Двухфазная миграция (expand → contract)

Типично для схем:

• Expand: добавляем новые поля, начинаем заполнять их, не прекращая старые.
• Contract: после миграции клиентов — удаляем/отключаем старые поля.

Подход «договоримся, что удалим старое в ближайшем релизе» почти всегда приводит к инцидентам.

Миграции для событий: потребительские схемы и backfill

С событиями часто нужен backfill — пересоздание событий из прошлого состояния.

Важные моменты:

• при backfill убедитесь, что семантика соответствует новой версии;
• следите за idempotency: потребитель должен уметь не дублировать эффекты;
• не запускайте backfill без контроля мощности: старые потребители могут захлебнуться.

Идемпотентность и версионирование

Если вы добавляете новое поле, которое влияет на обработку (например, вычисляемая скидка), важно:

• либо сохранять старую обработку для старой версии события,
• либо переводить потребителей в режим, когда они могут корректно обработать и старую версию, и новую.

Если эффекты не идемпотентны, любое повторение доставки усиливает риск рассинхронизации.

Практическая схема управления версиями: lifecycle и SLA совместимости

Чтобы версионирование не превращалось в «релиз ради релиза», нужна политика жизненного цикла.

Рекомендуемые статусы версии контракта

Например:

• Active — версия поддерживается, производим события/ответы.
• Deprecated — версия ещё обслуживается, но новые изменения туда не добавляются.
• Sunset — версия будет отключена после даты.
• Removed — полностью прекращена.

Политика времени поддержки

Сколько держать старые версии? Это зависит от:

• скорости обновления клиентов,
• наличия внешних партнёров,
• критичности домена.

Но даже без точных цифр правило такое: депрекейт должен происходить заранее (недели/месяцы, а не дни), и должно быть объявлено в документации и/или через коммуникации.

Привязка к реальным потребителям

Если у вас много внутренних сервисов — полезно вести инвентаризацию потребителей контракта. Тогда вы можете:

• оценить, сколько времени нужно для миграции,
• проверить, что все клиенты обновились,
• только после этого снимать старую версию.

Конкретика: как писать и эволюционировать контракты на примере JSON Schema

Рассмотрим практический пример для событий (payload) или API-ответа.

Версия 1

{
  "$id": "https://example.com/schemas/order.v1.json",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "required": ["orderId", "currency", "totalAmount"],
  "properties": {
    "orderId": { "type": "string" },
    "currency": { "type": "string", "minLength": 3, "maxLength": 3 },
    "totalAmount": { "type": "number", "minimum": 0 }
  },
  "additionalProperties": false
}

additionalProperties: false — строгий режим. Он хорош для диагностики, но в мире интеграций строгая схема часто становится источником breaking (клиенты падают при новых полях). Поэтому на практике используют мягкий режим для контрактов, предназначенных для эволюции.

Версия 2: добавление поля без поломки

Безопасное изменение: добавили новое optional поле discountAmount.

{
  "$id": "https://example.com/schemas/order.v2.json",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "required": ["orderId", "currency", "totalAmount"],
  "properties": {
    "orderId": { "type": "string" },
    "currency": { "type": "string", "minLength": 3, "maxLength": 3 },
    "totalAmount": { "type": "number", "minimum": 0 },
    "discountAmount": { "type": "number", "minimum": 0 }
  },
  "additionalProperties": true
}

Ключевые моменты:

• discountAmount не в required;
• additionalProperties: true, чтобы новые поля в будущих версиях не сломали валидацию.

Тест совместимости: быстро и без магии

Напишите тесты, которые проверяют, что v1-потребитель может обработать v2-ответ.

Если у вас есть JSON Schema валидатор, можно проверить:

• что пример v2 payload валидируется по v1 схеме (в зависимости от правил additionalProperties),
• что новая схема валидирует старые payload.

Обычно делают оба направления.

Серверный код: как поддерживать v1 и v2 без дублирования логики

Рассмотрим подход для API (Node.js/Express условно). Идея: не плодить два разных бизнес-движка, а свести изменения к трансформации на границе.

Пример: трансформация ответа к нужной версии

Допустим, клиентам v1 нельзя видеть поле discountAmount, но v2 может.

function toOrderResponseV1(order) {
  return {
    orderId: order.id,
    currency: order.currency,
    totalAmount: order.totalAmount,
  };
}

function toOrderResponseV2(order) {
  return {
    orderId: order.id,
    currency: order.currency,
    totalAmount: order.totalAmount,
    discountAmount: order.discountAmount ?? undefined,
  };
}

app.get('/orders/:id', (req, res) => {
  const version = req.query.version ?? 'v1'; // лучше из заголовка, но для примера

  const order = /* загрузка из БД или расчёт */;

  const payload =
    version === 'v2' ? toOrderResponseV2(order) : toOrderResponseV1(order);

  res.json(payload);
});

Это упрощение. На практике:

• версию желательно определять по заголовку/контент-типу;
• трансформации лучше делать в отдельном слое (adapter/mapper);
• логировать версию для наблюдаемости.

Для событий: envelope как стабильный слой

Для событий аналогично: стабилизируйте envelope (event id, timestamp, type), а версионируйте payload.

{
  "eventId": "uuid",
  "eventType": "order.created",
  "schemaVersion": 2,
  "occurredAt": "2026-07-22T10:15:30Z",
  "payload": {
    "orderId": "O-123",
    "currency": "RUB",
    "totalAmount": 1250.5,
    "discountAmount": 100
  }
}

Старые потребители могут игнорировать schemaVersion и новые поля, если валидация устроена мягко.

Наблюдаемость и контракт-метрики: как поймать поломку до инцидента

Даже хорошая политика не гарантирует отсутствие ошибок. Поэтому встраивайте проверку совместимости в pipeline релизов и эксплуатацию.

Контрактные тесты (contract testing)

Идея: иметь зафиксированные примеры сообщений/ответов для каждой версии и прогонять:

• тесты схемы (валидируемость),
• тесты десериализации (клиент не падает),
• тесты семантики (минимальные инварианты).

Сигналы в проде

• доля запросов с версией v1/v2 по заголов