Политики построителя API данных

2025-06-12

Набор политик управляет построителем данных, связанным с критическими изменениями, уведомлениями, выпусками и версиями.

Управление версиями и выпусками

Выпуск в контексте построителя API данных ссылается на каждую опубликованную версию программного обеспечения, определяемую форматомMajor.Minor.Patch. Эти выпуски делятся на три категории: стабильные, критические изменения и предварительная версия.

Ответственность за обновление контейнера

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

Поддержание актуальности контейнера является ответственностью клиента.

Стабильные выпуски

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

Критические выпуски изменений

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

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

Предварительные версии выпусков

Предварительные выпуски построителя данных определяются схемой X.Y.Z-rc управления версиями. Суффикс -rc указывает, что сборка является "кандидатом на выпуск". Предварительные версии используются для сбора отзывов о новых функциях и других изменениях.

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

Предварительные версии не предназначены для долгосрочного использования или использования в рабочей среде. Когда новая стабильная или предварительная версия становится доступной, более старые версии предварительной версии больше не будут доступны. Лучше всего использовать предварительные версии, только если вы активно работаете над новыми функциями и готовы перейти на версию, не предварительную, вскоре после выпуска. Если некоторые функции из предварительной версии включены в новую стабильную версию, остальные функции предварительной версии добавляются в новую предварительную версию, чтобы попробовать.

Таблица изменений версий

Это важно

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

Тип выпуска	Предыдущая версия	Новая версия	Примечания.
Критическое изменение	`1.Y.Z`	`2.Y.Z`	Новые функции и исправления ошибок, а также любые критические изменения.
Стабильный	`1.1.Z`	`1.2.Z`	Новые функции и исправления ошибок без критических изменений, если изменения не касаются критических ошибок продукта, юридических, безопасности или конфиденциальности.
Стабильный	`1.1.1`	`1.1.2`	Исправление ошибок без новых функций или критических изменений, если изменения не устраняют критические ошибки продукта, юридические, безопасность или конфиденциальность.
Предпросмотр	`X.Y.1-rc`	`X.Y.2-rc`	Новые функции предварительной версии и исправления ошибок. (Критические изменения включаются, если основная версия напучена.)

Разрушающие изменения

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

Это важно

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

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

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

Примеры критических изменений

В следующих примерах приведен неисчерпаемый список критических изменений в построителе API данных:

Изменения контракта REST API
Изменения в создании схемы GraphQL
Изменения, влияющие на обратную совместимость
Удаление или переименование API или параметров
Изменения в кодах ошибок
Корректировки функциональных возможностей определения разрешений
Удаление разрешенных параметров, полей запроса или полей ответа
Добавление обязательных параметров или полей запроса без значений по умолчанию
Изменения в предполагаемых функциональных возможностях конечной точки API

Определение неразрывного изменения

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

Примеры некрикционных изменений

В следующих примерах приведен неисчерпаемый список неразрывных изменений в построителе API данных:

Введение новых конечных точек
Добавление методов к существующим конечным точкам
Включение новых полей в ответы и запросы
Корректировки порядка полей в ответах
Введение необязательных заголовков запросов
Изменения длины данных и размера ответа
Изменения сообщений об ошибках и кодов
Исправление кодов ответов HTTP
Дополнительные метаданные в созданных документах OpenAPI

Как мы сообщаем критические изменения?

Мы делаем это приоритетом, чтобы быстро сообщить вам о критических изменениях. Уведомления о критических изменениях можно найти в заметках о выпуске выпусков построителя данных в GitHub и в статье о выделенных критических изменениях.

Текущий список критических изменений

Критические изменения и выход на пенсию компонентов объявлены в этой статье.

По состоянию на данный момент, критические изменения отсутствуют