Przejdź do głównej zawartości
AggregaAggrega
Wybierz język: Polski
Ta strona została przetłumaczona maszynowo. Przeczytaj oryginał w języku angielskim.

Schemat Aggrega Catalog (Component)

Dokumentacja wygenerowana automatycznie. Nie należy jej edytować ręcznie — należy ją wygenerować ponownie z opublikowanego JSON Schema.

Identyfikator schematu: https://aggrega.ai/schemas/component-v1beta1.schema.json

Abstrakcyjna definicja atomowego elementu konstrukcyjnego.

Opisowe wskazówki dotyczące tworzenia encji Component zawiera dokumentacja tworzenia encji Component; ta strona dokumentuje schemat strukturalny, który opisuje ta dokumentacja.

Typ najwyższego poziomu: object

Właściwości

WłaściwośćTypWymaganaOpis
apiVersionconst “aggrega.ai/v1beta1”takStała: "aggrega.ai/v1beta1"
kindconst “Component”takStała: "Component"
metadataobjecttak
specobjecttakDefinicje walidacji i schematu regulujące nieprzezroczysty ładunek wartości dewelopera.

Dodatkowe właściwości są niedozwolone.

component.metadata

WłaściwośćTypWymaganaOpis
namestringtakCo najmniej 1 znak.
versionstringtakWersja interfejsu w ścisłym formacie Semantic Versioning (np. 1.0.0). Wzorzec: ^(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-]+)*))?$.
descriptionstringnieCzym jest ta encja i do czego służy, napisane dla kogoś, kto decyduje, czy jej użyć. Należy zacząć od zdania nazywającego rzecz, a następnie dodać to, czego czytelnik potrzebuje, aby ją wybrać i poprawnie użyć — czego oczekuje od encji Release, która ją wdraża, oraz wszystko, co zaskakuje w jej zachowaniu. Zwykle wystarcza krótki akapit.
maintainersobject[]nieLista opiekunów, do których należy ta encja.
licensestringnieIdentyfikator SPDX licencji oprogramowania opisywanego przez tę encję, np. MIT lub AGPL-3.0. Określa warunki tego oprogramowania, a nie warunki tego pliku.
repositorystringnieURL repozytorium Git, w którym znajdują się pliki źródłowe.
homestringnieURL strony domowej, wiki lub dokumentacji tej encji.
keywordsstring[]nieLista opisowych słów kluczowych ułatwiających wyszukiwanie w interfejsie użytkownika.
labelsobjecttakEtykiety w stylu duck typing służące do deklarowania cech. Muszą zawierać zarezerwowany klucz ‘component.aggrega.ai/type’.
annotationsmapa stringnieNiezmienne, wewnętrzne cechy komponentu tworzone przez architekta platformy w domenie 2. Przechodzą kaskadowo do kubełka .context.annotations.catalog.

Dodatkowe właściwości są niedozwolone.

component.metadata.maintainers[]
WłaściwośćTypWymaganaOpis
namestringtak
emailstringnie
urlstringnie

Dodatkowe właściwości są niedozwolone.

component.metadata.labels

Etykiety w stylu duck typing służące do deklarowania cech. Muszą zawierać zarezerwowany klucz ‘component.aggrega.ai/type’.

WłaściwośćTypWymaganaOpis
component.aggrega.ai/typestring (enum)takZarezerwowana oś określająca, jakiego rodzaju rzeczą jest ten komponent. Aggrega definiuje ten klucz i akceptowane przez niego wartości, więc zbiór jest zamknięty; aby klasyfikować komponenty według własnej osi, należy dodać własny klucz etykiety obok tego. Dozwolone wartości: "server", "worker", "task", "function", "stateful-server", "resource"

component.spec

Definicje walidacji i schematu regulujące nieprzezroczysty ładunek wartości dewelopera.

WłaściwośćTypWymaganaOpis
extendsstringnieURI bazowej encji Component, którą ta encja Component rozszerza. Rozszerzanie składa strukturę: etykiety i adnotacje metadanych bazy, jej gniazda dołączeń (featuresSchema), jej lista dozwolonych mechanizmów self-inject (inject) i jej gniazda topologii (usesSchema) są dziedziczone, a ta encja Component może je uzupełniać lub zastępować odziedziczony wpis klucz po kluczu. Filary danych bazy NIE są składane — blok schema bazy jest dziedziczony dokładnie w takiej postaci, w jakiej utworzyła go baza, więc rozszerzająca encja Component zapisuje schema: inherited i nie tworzy własnej treści filarów.
featuresSchemamapa objectnieDeklaratywne definicje gniazd dołączeń: nazwane punkty wiązania, w których ta encja oczekuje dołączenia encji Feature. Gniazdo ogranicza, jakie wypełnienie może się z nim związać (selector) i jak może być dostarczany materiał wypełnienia (inject); własna encja Feature wypełnienia jest właścicielem jego wartości i kontraktu infra. Zadeklarowanie gniazda nigdy nie zamyka bloku dołączeń — autor może dołączyć encję Feature pod nazwą, której nie deklaruje żadne gniazdo, dzięki czemu jedna encja służy zarówno jako dołączenie wypełniające gniazdo, jak i jako poświadczenie współdzielone w szerszym zakresie. Gniazdo jest punktem wiązania, a nie gniazdem zależności: odrębną powierzchnię topologii deklaruje usesSchema.
injectstring[]nieDozwolone mechanizmy dostarczania self-inject (np. [‘env’, ‘file’, ‘arg’]). Gdy pole jest obecne, deweloperzy mogą używać bloku inject: na poziomie komponentu w encji Aggregate, aby wstrzykiwać własne values lub klucze provides bezpośrednio do potoku dostarczania. Jeśli pole zostanie pominięte, self-inject na poziomie komponentu jest zabroniony (wzorzec Black-Box — encja Recipe obsługuje całe wewnętrzne okablowanie). Semantyka taka sama jak w usesSchema[].inject, ale dotyczy własnych values komponentu, a nie topologii między komponentami. Można wymienić dowolną nazwę mechanizmu z wyjątkiem all, której żaden blok inject nie może użyć.
usesSchemamapa objectnieGniazda zależności deklarowane przez tę encję, kluczowane nazwą gniazda; każde połączenie poprowadzone przez gniazdo jest sprawdzane względem deklaracji tego gniazda — jego selektora, dozwolonych mechanizmów inject i kontraktów dla poszczególnych połączeń. Klucze: co najmniej jedna litera, cyfra, podkreślenie lub łącznik. Kropka jest niedozwolona. Wzorzec: ^[a-zA-Z0-9_-]+$.
schemaanynieTreść JSON Schema 2020-12 obejmująca filary o dowolnym kształcie: values (domena programisty — parametry kształtu aplikacji, które programista konfiguruje dla każdej instancji Component w encji Aggregate); infra (domena operatora — fizyczne parametry wymiarowania dostarczane przez encję Release); oraz provides (klucze kontekstu w dół strumienia, które ta encja Component udostępnia konsumentom przez potok topologii). Akceptuje cztery tryby tworzenia, rozróżniane według kształtu treści: (1) treść inline (mapa YAML w formie zwartej, YAML JSON Schema lub mieszana); (2) zastąpienie plikiem przez {$import: }, zapisane w spec.schema, aby dostarczyć cały kontrakt z jednego pliku, lub w pojedynczym filarze, aby dostarczyć tylko ten filar, przy czym ścieżka względna jest odczytywana względem katalogu zawierającego encję, która ją zadeklarowała; (3) odwołanie między dokumentami przez {$ref: #/schemas/} do wpisu w encji SchemaLibrary według tożsamości samej nazwy (wersję dostarcza plik blokady danej encji Release; w odwołaniu nie pojawia się host rejestru); (4) sam ciąg inherited, który jest jedyną formą, jaką może zapisać encja Component deklarująca extends — stwierdza on, że trzy filary pochodzą z bazowej encji Component dokładnie w takiej postaci, w jakiej utworzyła je baza. Tryby od 1 do 3 tworzą treść i są dostępne tylko dla encji Component, która nie deklaruje extends; tryb 4 nie tworzy żadnej treści i jest wymagany od każdej encji Component, która go deklaruje. Pola towarzyszące usesSchema i featuresSchema obejmują filary o stałym kształcie (gniazda zależności, sloty dołączania); kompilator łączy te trzy elementy w jeden schemat, względem którego walidowana jest instancja.
assertionsmapa stringnieWalidacja międzypolowa w czasie budowania. Każdy wpis jest nazwaną asercją: klucz jest stabilnym identyfikatorem reguły wyświetlanym w komunikatach o błędach; wartość jest ciągiem szablonu Go z semantyką zatrzymania {{ fail "message" }}. Wiele nazwanych asercji na encję jest ewaluowanych dla każdej instancji w kolejności zadeklarowanej przez autora; pierwsza niespełniona asercja zatrzymuje budowanie. Asercje encji Component są ewaluowane po rozwiązaniu i analizie statycznej, przed renderowaniem, i wyrażają niezmienniki architektoniczne kontraktu, które obowiązują niezależnie od tego, która encja Recipe się wiąże. Kontekst szablonu: .values / .infra / .uses / .features / .metadata. Ewaluator używa missingkey=error: odwołania do niezdefiniowanych kluczy zatrzymują budowanie z diagnostyką no-such-key. Ponieważ samo odwołanie zatrzymuje budowanie, zanim może zadziałać jakakolwiek wartość zastępcza, zwykłe default nie zapewnia na tej powierzchni wartości zastępczej dla pola opcjonalnego — należy zabezpieczyć odwołanie przez hasKey lub użyć pomocnika optional, który bezpośrednio sprawdza obecność. Odczyt klucza przez index również jej nie zapewnia: index zatrzymuje budowanie na kluczu, którego mapa nie zawiera, podając ten klucz. Dziedziczenie jest addytywne: encja Component deklarująca extends jest ewaluowana względem asercji, które dziedziczy, oraz własnych, przy czym odziedziczone reguły są pierwsze, a łańcuch o dowolnej głębokości akumuluje się od korzenia łańcucha w dół — więc gdy niespełniona byłaby więcej niż jedna reguła, zgłaszana jest ta zadeklarowana najwyżej w łańcuchu. Ponowne użycie odziedziczonej nazwy do zadeklarowania innej reguły jest odrzucane, gdy łańcuch extends jest rozwiązywany względem katalogu, z podaniem obu encji Components i wspólnej nazwy — ujawnia się to więc, gdy bazowa encja Component jest obecna, a nie na podstawie samego dokumentu rozszerzającego; rozszerzająca encja Component dodaje reguły i nigdy żadnej nie zastępuje. Powtórzenie odziedziczonej reguły bajt w bajt pod jej własną nazwą jest akceptowane jako operacja pusta, którą w istocie jest. Nic nie sprawdza, czy dwie reguły mogą być spełnione jednocześnie: wzajemnie niespełnialna para jest błędem autorskim, który ujawnia się jako zwykłe niespełnienie asercji, gdy instancja wyzwoli tę, która zadziała pierwsza, a nigdy jako wcześniejsze ostrzeżenie.

Dodatkowe właściwości są niedozwolone.

Definicje

extending-component-must-declare-schema-inherited

Ma zastosowanie, gdy spec.extends jest obecne. Rozszerzająca encja Component otrzymuje values / infra / provides swojej bazy dokładnie w takiej postaci, w jakiej baza je napisała, dlatego deklaruje spec.schema: inherited i nie zawiera własnej treści filarów. Oba pozostałe warianty są błędami i są to różne pomyłki: całkowite pominięcie spec.schema, przez które czytelnik nie odróżniłby odziedziczonego bloku filarów od zapomnianego; oraz napisanie treści filarów pod spec.schema, co oznaczałoby żądanie drugiego, rozbieżnego kontraktu dla encji Component, której kontraktem jest kontrakt jej bazy.

WłaściwośćTypWymaganaOpis
schemaconst “inherited”takZnacznik dziedziczenia i jedyna wartość, jaką przyjmuje spec.schema w encji Component deklarującej extends. Wskazuje, skąd pochodzą filary; sama treść filarów należy do bazowej encji Component. Stała: "inherited"

non-extending-component-authors-its-own-schema

Ma zastosowanie, gdy spec.extends jest nieobecne. Encja Component, która nie rozszerza żadnej bazy, zawiera własną treść values / infra / provides pod spec.schema, więc to pole zawiera napisaną treść, a nie znacznik inherited: znacznik oznacza, że filary pochodzą z bazy, a ta encja Component jej nie ma.

WłaściwośćTypWymaganaOpis
schemaobjectnieNapisana treść filarów — mapa w dowolnym z trzech trybów tworzenia treści opisanych w spec.schema.