Перейти к содержимому
AggregaAggrega
Выберите язык: Русский
Эта страница переведена машинным способом. Читать оригинал на английском.

Схема Aggrega Catalog (Feature)

Сгенерированный справочник. Не редактируйте вручную — сгенерируйте заново из опубликованной JSON Schema.

Идентификатор схемы: https://aggrega.ai/schemas/feature-v1beta1.schema.json

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

Описательное руководство по созданию сущностей Feature см. в справочнике по созданию сущностей Feature; на этой странице документирована структурная схема, которую описывает этот справочник.

Тип верхнего уровня: object

Свойства

СвойствоТипОбязательноОписание
apiVersionconst “aggrega.ai/v1beta1”даКонстанта: "aggrega.ai/v1beta1"
kindconst “Feature”даКонстанта: "Feature"
metadataobjectда
specobjectдаКонтракт валидации, нацеливания и совместимости для сущности Feature из каталога: столпы свободной формы (values, infra, provides), задаваемые через schema, столпы фиксированной формы (usesSchema — гнёзда зависимостей, featuresSchema — слоты подключения), нацеливание на компоненты (appliesTo и appliesToAnyOf) и средства управления совместимостью.

Дополнительные свойства не допускаются.

feature.metadata

СвойствоТипОбязательноОписание
namestringдаНе менее 1 символа.
versionstringдаВерсия feature по строгому семантическому версионированию (например, 1.0.0). Шаблон: ^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-((?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*)(?:\.(?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*))*))?(?:\+([0-9a-zA-Z-]+(?:\.[0-9a-zA-Z-]+)*))?$.
descriptionstringнетЧто представляет собой эта сущность и для чего она нужна — для того, кто решает, использовать ли её. Начните с предложения, называющего её, затем добавьте то, что нужно читателю, чтобы выбрать её и правильно использовать: чего она ожидает от сущности Release, которая её развёртывает, и всё неожиданное в её поведении. Обычно достаточно короткого абзаца.
maintainersobject[]нетСписок сопровождающих, которым принадлежит эта сущность.
licensestringнетИдентификатор SPDX лицензии программного обеспечения, которое описывает эта сущность, например MIT или AGPL-3.0. Он фиксирует условия этого программного обеспечения, а не условия данного файла.
repositorystringнетURL Git-репозитория, в котором находятся исходные файлы.
homestringнетURL домашней страницы, вики или документации этой сущности.
keywordsstring[]нетСписок описательных ключевых слов для удобства поиска в интерфейсе.
labelsobjectнетМетки для утиной типизации сущности Feature. Зарезервированная метка ‘feature.aggrega.ai/kind’ со значением ‘secret’ помечает её как Feature учётных данных — для автора и для инструментов, которые её отображают. Feature учётных данных и обычная Feature подключаются одинаково, через одну и ту же поверхность подключения; то, что порождает подключение, определяется не меткой, а сущностью FeatureRecipe, с которой Manifest сопоставляет её тип.
annotationsmap of stringнетНеизменяемые внутренние характеристики функции, задаваемые архитектором платформы в домене 2. Каскадно передаются в корзину .context.annotations.catalog.

Дополнительные свойства не допускаются.

feature.metadata.maintainers[]
СвойствоТипОбязательноОписание
namestringда
emailstringнет
urlstringнет

Дополнительные свойства не допускаются.

feature.metadata.labels

Метки для утиной типизации сущности Feature. Зарезервированная метка ‘feature.aggrega.ai/kind’ со значением ‘secret’ помечает её как Feature учётных данных — для автора и для инструментов, которые её отображают. Feature учётных данных и обычная Feature подключаются одинаково, через одну и ту же поверхность подключения; то, что порождает подключение, определяется не меткой, а сущностью FeatureRecipe, с которой Manifest сопоставляет её тип.

СвойствоТипОбязательноОписание
feature.aggrega.ai/kindstring (enum)нетМетка вида функции. Значение ‘secret’ помечает её как Feature учётных данных. Допустимые значения: "secret"

feature.spec

Контракт валидации, нацеливания и совместимости для сущности Feature из каталога: столпы свободной формы (values, infra, provides), задаваемые через schema, столпы фиксированной формы (usesSchema — гнёзда зависимостей, featuresSchema — слоты подключения), нацеливание на компоненты (appliesTo и appliesToAnyOf) и средства управления совместимостью.

СвойствоТипОбязательноОписание
extendsstringнетСсылка на базовую сущность Feature, от которой наследует эта сущность Feature. Базовая сущность указывается по её metadata.name, а не по координате реестра, под которой публикуется Feature, и принимает те же три формы версии, что и любая ссылка каталога: без версии (core/queue) — наивысший доступный релиз, точная версия (core/queue:1.0.0) или диапазон с кареткой (core/queue:^1.0.0). Наследуются не только метаданные: metadata.labels и metadata.annotations базовой сущности, её селекторы appliesTo и appliesToAnyOf, её блок interoperability, её usesSchema и её featuresSchema объединяются вниз по иерархии, а её объявления JSON Schema 2020-12 в schema объединяются автоматически. При совпадении ключа побеждает собственное значение потомка, а поля идентичности никогда не наследуются.
featuresSchemamap of objectнетДекларативные определения слотов присоединения: именованные точки привязки, в которых эта сущность Feature ожидает присоединения ещё одной сущности Feature. Слот ограничивает, какое заполнение может к нему привязаться (selector) и как может доставляться материал заполнения (inject); контракт values и infra принадлежит собственной сущности Feature заполнения. Объявление слота никогда не закрывает блок присоединений — автор может присоединить Feature под именем, которое не объявлено ни одним слотом. Слот — это точка привязки, а не гнездо зависимости: usesSchema объявляет отдельную поверхность топологии.
appliesTostringнетСтрока селектора меток в стиле Kubernetes, сопоставляемая с Components. Все требования, разделённые запятыми, должны выполняться (AND). Поддерживаемые формы: key=value, key!=value, key in (v1, v2), key notin (v1, v2), голый ключ (метка присутствует), !key (метка отсутствует). Пример: “tier in (critical, production), !legacy”. Пустой или отсутствующий селектор не объявляет ограничений. Селектор разбирается по этим формам при каждой оценке присоединения этой сущности Feature, и требование вне их останавливает сборку с указанием этого требования: пустое требование (ведущая, завершающая или двойная запятая) или ключ, содержащий пробельные символы или любой из символов = ! ( ) и запятую, — поэтому “!tier=frontend” отклоняется, а исключить значение можно с помощью tier!=frontend. Значение — это текст после оператора, какие бы символы он ни содержал. Шаблон этого поля отклоняет лишь несколько некорректных форм, до оценки какого-либо присоединения. Шаблон: ^(?:[^()]*[()][\s\S]*|[ \t]*(?:![ \t]*[^,]*[^ \t,][^,]*|[^ \t,!][^,]*)?(?:,[ \t]*(?:![ \t]*[^,]*[^ \t,][^,]*|[^ \t,!][^,]*)?)*)$.
appliesToAnyOfstring или map из string[]нетСписок селекторов; сущность Feature применяется, если совпадает ЛЮБОЙ элемент (логика OR). Каждый элемент — либо строка селектора меток (та же грамматика, что у appliesTo; требования внутри строки объединяются через AND), либо плоская карта ключ-значение, в которой должна совпадать каждая пара (только равенство).
interoperabilityobjectнетРасширенные средства управления эксплуатационной безопасностью и совместимостью.
usesSchemamap of objectнетСокеты зависимостей, которые объявляет эта сущность, с именем сокета в качестве ключа; каждое соединение, проведённое через сокет, проверяется на соответствие объявлению этого сокета — его селектору и допустимым механизмам inject. Ключи: одна или несколько букв, цифр, подчёркиваний или дефисов. Точка не допускается. Шаблон: ^[a-zA-Z0-9_-]+$.
schemaobjectнетСодержимое JSON Schema 2020-12, охватывающее свободные опоры: values (область разработчика — параметры формы приложения, которые разработчик настраивает для каждого подключения Feature в Aggregate); infra (область оператора — физические параметры масштабирования, задаваемые Release); и provides (ключи контекста для нижестоящих потребителей, которые этот Feature предоставляет через канал топологии). Поддерживаются три режима описания с выбором по форме содержимого: (1) встроенное содержимое (YAML-словарь в компактной форме, в виде JSON Schema YAML или смешанный); (2) замена файлом через {$import: }, записанная в spec.schema, чтобы задать весь контракт из одного файла, или в отдельной опоре, чтобы задать только эту опору; относительный путь разрешается относительно каталога, содержащего объявившую его сущность; (3) междокументная ссылка через {$ref: #/schemas/} на запись SchemaLibrary по идентичности голого имени (версию задаёт lockfile каждого Release; хост реестра в ссылке не указывается). Сопутствующие поля usesSchema и featuresSchema охватывают опоры фиксированной формы (гнёзда зависимостей, слоты подключения); компилятор объединяет все три в одну схему, по которой проверяется экземпляр.
assertionsmap of stringнетМежполевая валидация во время сборки. Каждая запись — именованное утверждение: ключ — стабильный идентификатор правила, выводимый в сообщениях об ошибках; значение — строка шаблона Go с семантикой остановки {{ fail "message" }}. Несколько именованных утверждений одной сущности оцениваются для каждого экземпляра в порядке, объявленном автором; первое невыполненное утверждение останавливает сборку. Утверждения Feature оцениваются после разрешения и статического анализа, до рендеринга, и выражают архитектурные инварианты контракта. Контекст шаблона: .values / .infra / .uses / .features / .metadata. Вычислитель использует missingkey=error: ссылки на неопределённые ключи останавливают сборку с диагностикой об отсутствующем ключе. Поскольку голая ссылка останавливает сборку до того, как сработает какой-либо запасной вариант, простой default не даёт запасного значения для необязательного поля на этой поверхности — защитите ссылку с помощью hasKey или используйте вспомогательную функцию optional, которая сама выполняет проверку наличия. Чтение ключа через index тоже его не даёт: index останавливает сборку на ключе, которого нет в карте, с указанием этого ключа.

Дополнительные свойства не допускаются.

feature.spec.interoperability

Расширенные средства управления эксплуатационной безопасностью и совместимостью.

СвойствоТипОбязательноОписание
conflictsWithstring[]нетИмена сущностей Features, вместе с которыми эта сущность Feature не может оказаться на одном компоненте; каждое записывается так, как тип присоединения именует Feature. Сборка останавливается до рендеринга, если на одном компоненте оказываются эта сущность Feature и названная здесь Feature, — независимо от того, была ли каждая присоединена на компоненте, на содержащей его подсистеме или границе, в записи компонента Release или путём расширения по аннотациям. Достаточно одного объявления: для остановки не требуется, чтобы другая Feature указывала эту. Имена сравниваются без версии, поэтому запись совпадает с любой версией названной ею Feature. Две сущности Features, присоединённые к соседним границам без общих компонентов, никогда не встречаются и не вызывают остановки.

Дополнительные свойства не допускаются.