Как обрабатывать критические изменения в API и схемах событий

Соблюдение контрактов на передачу данных имеет решающее значение для обеспечения того, чтобы мы не расстраивали подписчиков событий и не выходили из строя системы.

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

Здесь подробно рассмотрим критические изменения и предложим дополнительные решения, позволяющие их избежать.

Что такое критические изменения?

По сути, критическое изменение схемы (в контексте API или события) — это все, что требует от потребителя внесения обновления со своей стороны. Это изменение, которое заставляет меняться. Схемы будут развиваться, но как только схема будет использоваться в производстве, вы должны быть очень осторожны, чтобы не нарушить контракт данных.

Удаление формата мероприятия или изменение базовой структуры мероприятия представляет собой кардинальное изменение. Но основные моменты находятся на уровне атрибутов (поля или свойства).

Структурные изменения

Вот список структурных изменений для атрибутов схемы:

• Переименование атрибутов — изменение имени атрибута, даже если оно просто меняет регистр (например, с CamelCase на TitleCase), является критическим изменением.
• Удаление атрибутов — удаление атрибута из схемы.
• Изменения типов данных — изменение типов данных, даже если изменение кажется совместимым.
• Создание обязательных атрибутов — каждый раз, когда вы помечаете атрибут (даже новый) как обязательный, хотя раньше этого не было, это критическое изменение.

Тип	Пример
Переименование атрибутов	name на firstName
Удаление атрибутов	Представляем firstName, но удаляем name
Изменения типов данных	Изменение productSKU с integer на string
Создание обязательных атрибутов	Теперь требуется customerID

Семантические изменения

Другая основная категория критических изменений на уровне атрибутов связана с изменениями в том, что означают данные, или семантическими изменениями. Они заставляют потребителей по-новому интерпретировать получаемые данные.

Они заключаются в следующем:

• Изменения формата – любое изменение формата атрибута.
• Изменения значения – когда заявленное или подразумеваемое значение данных изменяется.
• Более строгие ограничения – когда требования к атрибутам добавляются или становятся более строгими.

Тип	Пример
Изменения формата	Дата с mm/dd/yyyy на yyyy-mm-dd
Значение изменений	Изменение перечисления, переход providerCost с долларов на центы
Более строгие ограничения	Добавляем percentage максимум 100

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

Что такое некритические изменения?

В целом мы можем описать ненарушающие изменения как аддитивные или разрешительные. Это изменения, которые не требуют изменений для потребителей.

Вот список некритических изменений атрибутов:

• Добавление нового атрибута — во всех контекстах схемы добавление нового атрибута является некритическим изменением, если оно не требуется (например, для запроса POST).

• Создание атрибута необязательным — когда атрибут был необходим, но в более новых версиях схемы он не требуется.

• Более слабые ограничения — такие вещи, как более допустимые целочисленные диапазоны (минимальные и максимальные) или обеспечение большей десятичной точности. Однако будьте осторожны и общайтесь с потребителями, поскольку они могут полагаться на более строгие ограничения.

Тип	Пример
Добавление нового атрибута	Добавление firstName рядом name
Делаем атрибут необязательным	customerID больше не требуется
Более мягкие ограничения	Максимальный процент увеличен со 100 до 200

Некритических изменений часто можно избежать. Но эффективное развитие схем может быть сложной задачей и требует много размышлений, чтобы не подорвать схемы и доверие потребителей.

Как развивать схемы

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

• Знание предметной области: понимание предметной области поможет вам избежать неправильно названных атрибутов, атрибутов неправильного объекта или неверных типов данных.
• Конкретные имена атрибутов: вместо изменения имени, типа данных или формата атрибута введите новый атрибут с более конкретным именем и исправьте тип или формат данных.
• Имена атрибутов с намерением: используйте имена атрибутов, которые отражают их формат или назначение. Например, потребители могут не знать, providerCost в долларах или центах будет указана сумма, поэтому укажите с помощью providerCostInDollars или providerCostInCents. Это также предотвратит критические изменения, если у вас возникнут проблемы с точностью вычислений в долларах и вы решите указать стоимость в центах.
• Черновые схемы и атрибуты: широко используйте «черновой режим» на уровне схемы, получая отзывы об атрибутах в смоделированных средах до того, как они будут запущены в производство. Для схем, которые используются в производстве, вы можете ввести draftedAttributes объект и сбросить в него экспериментальные (не готовые к производству) атрибуты. Сообщите потребителям, что их атрибуты уточняются (поэтому им следует ожидать критических изменений) и будут перемещены в основную схему, когда они будут готовы.
• Поддержка существующих атрибутов: оставьте старые атрибуты в схеме. Не удаляйте старые атрибуты, если вы не смогли согласовать с потребителями стратегию прекращения поддержки.
• Управление версиями: при необходимости измените версии своих схем. Хотя обслуживание схем может оказаться довольно трудным, управление версиями схем — это способ обеспечить обратную совместимость, но двигаться дальше с новой схемой. Вы можете использовать высокоуровневое управление версиями (например, v1 и v2) или более детальное семантическое управление версиями (например, v1.0.1). Лучше всего создавать версии каждой схемы независимо, чтобы вам не приходилось, например, копировать все конечные точки API версии 1 в версию 2.

Заключение

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

Если вы не можете избежать серьезных изменений, обязательно координируйте их действия со всеми потребителями. Вы действительно можете завоевать больше доверия со стороны своих потребителей, если будете эффективно развивать схемы и сообщать о критических изменениях, когда они необходимы.