extends i implements
Dziedziczenie przez extends
Encje katalogu (Component, Feature) obsługują pojedyncze dziedziczenie za pomocą słowa kluczowego extends, które pozwala architektom platformy budować wyspecjalizowane encje na wspólnej bazie. Głębokie scalanie koperty YAML jest wspólne dla obu rodzajów: metadane, etykiety i deklaratywne tabele strukturalne encji rozszerzającej nadpisują pasujące klucze w bazie, a zagnieżdżone mapy są scalane rekurencyjnie. Oba rodzaje różnią się w zakresie filarów danych.
Ta strona omawia rodzaje katalogowe, ale nie są one jedynymi rodzajami deklarującymi extends. Deklarują je także encje Release i Manifest, a oba są dokumentami po stronie wdrożenia, tworzonymi obok siebie, a nie encjami indeksowanymi w katalogu — dlatego ich odwołania wskazują pliki, a nie encje katalogu, a scalana jest powierzchnia autorska, a nie schemat. Więcej informacji: entities/release.md i entities/manifest.md.
extends encji Component składa strukturę i dziedziczy filary w całości
W przypadku encji Component extends składa metadata.labels, metadata.annotations, spec.featuresSchema (gniazda dołączeń), spec.usesSchema (gniazda topologii) oraz spec.inject (listę dozwolonych samowstrzyknięć, której wpisy są łączone, zaczynając od bazy, bez duplikatów). Trzy filary danych — values, infra, provides — nie są składane. Rozszerzająca encja Component nie zawiera treści filarów: zapisuje dosłowny znacznik schema: inherited i otrzymuje blok schema: bazy dokładnie w takiej postaci, w jakiej zapisała go baza, na każdej głębokości łańcucha.
Opublikowany schemat encji Component czyni ten znacznik zarówno obowiązkowym, jak i wyłącznym, i odrzuca każde odstępstwo od niego podczas ładowania dokumentu, z osobną diagnostyką dla każdego: treść filarów zapisaną pod schema: w encji Component deklarującej extends:; całkowity brak schema: w takiej encji; oraz schema: inherited w encji Component, która nie deklaruje extends:.
Wynikają z tego dwie konsekwencje, działające w przeciwnych kierunkach:
- Zbiór kluczy ustala baza. Rozszerzająca encja Component nie deklaruje kluczy filarów, więc nie może ukryć, usunąć ani zmienić typu żadnego klucza zadeklarowanego przez bazę i nie dodaje własnych. Instancja bazy i instancja każdej encji, która ją rozszerza, są walidowane względem tego samego kontraktu filarów.
- Zawężanie przenosi się do
assertions:. Specjalizacja, która ma dopuszczać mniej niż odziedziczone filary, wyraża to jako predykat na sobie samej, a nie jako zawężony liść schematu. Jeśli bazacore/base-serverdeklarujetls_enabled: { type: boolean, default: true }, specjalizacja wymagająca TLS bezwarunkowo zapisuje:
apiVersion: aggrega.ai/v1beta1kind: Componentmetadata: name: core/tls-only-server version: 1.0.0 labels: component.aggrega.ai/type: "server"spec: extends: core/base-server schema: inherited # values, infra and provides are the base's, verbatim assertions: tls-is-mandatory: | {{- if not .values.tls_enabled -}} {{- fail "this component requires tls_enabled: true" -}} {{- end -}}Reguła odrzuca wartość, którą akceptuje odziedziczony blok filaru, i właśnie to oznacza tutaj zawężanie. Kierunek odwrotny nie ma żadnego wyrazu: specjalizacja nie może poluzować odziedziczonego ograniczenia, ponieważ nie może ponownie zapisać liścia, który je przenosi. Pełna tabela składania oraz opracowana para bazy i rozszerzenia: entities/component.md, sekcja „Catalog Authoring: Extending Base Components”.
extends encji Feature składa jej filary
W przypadku encji Feature schema: potomka jest składany ze schematem bazy zgodnie z semantyką składania JSON Schema 2020-12, co daje jeden scalony schemat, względem którego walidowana jest utworzona instancja. Poświadczeniowe encje Feature — oznaczone etykietą feature.aggrega.ai/kind: secret — wykorzystują to do budowania na wspólnej bazie: potomna poświadczeniowa encja Feature rozszerza rodzica, aby odziedziczyć jego schemat zapytań do sejfu, jednocześnie zawężając ograniczenia.
Kompilator nie zajmuje stanowiska co do kierunku tej zmiany. Składanie jest strukturalne, więc ograniczenie potomka, które poszerza ograniczenie bazy, jest składane bez zatrzymania kompilacji i zgłaszane jako ostrzeżenie doradcze. Nic go nie odrzuca: ograniczenie bazowej encji Feature jest wspólnym oczekiwaniem, którego autorzy katalogu przestrzegają dzięki przeglądom, a nie kontraktem egzekwowanym przez platformę.
Wiązanie interfejsu przez implements
Encje Recipes i FeatureRecipes wiążą się z interfejsem Component lub Feature za pomocą słowa kluczowego implements: na początku swojego spec. Wiązanie deklaruje, którego interfejsu katalogu ta encja Recipe / FeatureRecipe jest konkretną implementacją, i obsługuje trzy formy dopasowania wersji:
- Dokładna —
implements: core/api-server:1.0.0— dopasowuje jedną konkretną wersję typu Component. - Zakres zgodny z wersją główną —
implements: core/api-server:^1.0.0— dopasowuje dowolną wersję spełniającą>=1.0.0, <2.0.0(zgodność wersji głównej SemVer). Używana, gdy encja Recipe obsługuje zgodny zakres, a nie jedną przypiętą wersję. - Bez wersji —
implements: core/api-server— dopasowuje dowolną wersję typu Component. Używana, gdy encja Recipe obsługuje każdą wersję typu.
implements: nigdy nie wybiera encji Recipe: robi to mapowanie encji Manifest. Deklaracja steruje kontrolą spójności każdego wpisu mapowania — wersja mapowanego typu musi spełniać implements: mapowanej encji Recipe w jednej z trzech form albo encja Recipe musi implementować bazę, którą ten typ rozszerza — oraz listą kandydatów, którą oferują diagnostyka braku mapowania i uzupełnianie w edytorze. Wpis mapowania, którego encja Recipe ma implements: niepasujące ani do mapowanego typu, ani do żadnej z jego baz, zatrzymuje kompilację ze wskazaniem mapowania, encji Recipe i wartości jej implements:. Gdy klucz components.type obejmuje instancję komponentu w wersji, której klucz nie wskazuje — każdą instancję w przypadku klucza zapisanego bez wersji — kontrola jest wykonywana ponownie z własnym typem tej instancji, w wersji, w jakiej kompilacja ją kompiluje, a encja Recipe, która jej nie spełnia, zatrzymuje kompilację w ten sam sposób, wskazując instancję.
Wiązanie implements: jest mechanizmem, dzięki któremu działa zasada „ten sam typ Component, różne encje Recipes dla różnych dostawców”: encja Component core/postgres może mieć jedną encję Recipe implementującą ją dla dostawcy helm i inną encję Recipe implementującą ją dla dostawcy compose. Każda encja Recipe deklaruje tę samą wartość implements:, a encja Manifest, z którą budowana jest encja Release, mapuje typ na tę, której potrzebuje.
Encja Recipe napisana dla bazy obsługuje wszystko, co tę bazę rozszerza
implements: wskazuje bazę, a encja Recipe, która ją wskazuje, jest konkretną implementacją dla każdej encji Component rozszerzającej tę bazę, na dowolnej głębokości łańcucha. Specjalizacja zbudowana za pomocą extends nie potrzebuje więc własnej encji Recipe — i to sprawia, że korzystanie z opublikowanej nakładki jest tanie: zespół, który ją publikuje, tworzy encję Component, a zespoły, które ją wdrażają, ponownie używają encji Recipes bazy na każdym celu.
Obowiązują tu jednocześnie dwa fakty i są one odrębne. Czytelnik, który sprowadza je do „specjalizacja niczego nie potrzebuje”, pisze encję Manifest, która zawodzi, z powodu, którego będzie szukał w niewłaściwym pliku:
- Encja Recipe pasuje. Sprawdzenie spójności między kluczem typu mapowania w encji Manifest a
implements:zmapowanej encji Recipe akceptuje mapowanie, gdy encja Recipe implementuje sam zmapowany typ lub dowolną bazę, którą ten typ rozszerza. Trzy opisane wyżej formy wersji stosuje się do bazy dokładnie tak samo jak do samego typu: encja Recipe deklarującaimplements: core/base-server:^1.0.0spełnia specjalizację, której baza ma wersję1.4.0, a nie spełnia takiej, której baza ma wersję2.0.0. - Encja Manifest nadal mapuje własny typ specjalizacji. Wybór encji Recipe odbywa się po dokładnym kluczu mapowania. Instancja
enterprise/labelled-serverpotrzebuje własnego wpisumappings.components.type; nie dziedziczy wpisu napisanego dlacore/base-server. Specjalizacja bez własnego wpisu zatrzymuje się z diagnostyką niezmapowanej instancji, nawet gdy jej baza jest zmapowana.
Koszt utworzenia specjalizacji to zatem jeden wiersz w encji Manifest i żadnej nowej encji Recipe:
# The wrapper extends core/base-server and authors no pillars.# core/helm/base-server declares: implements: core/base-serverspec: mappings: components: type: enterprise/labelled-server:1.0.0: core/helm/base-server:1.0.0Gdy łańcucha extends zmapowanego typu nie da się przejść — tworzy pętlę albo wskazana w nim baza nie występuje w katalogu — budowanie zatrzymuje się na tym błędzie łańcucha, a nie na mapowaniu, ponieważ mapowania nie można ocenić, dopóki łańcuch, od którego zależy, nie zostanie rozstrzygnięty. Sprawdzenie przechodzi łańcuch wyłącznie przez encje Components obecne już na tej maszynie — te w katalogu i te, które lokalna pamięć podręczna artefaktów przechowuje pod przypięciem w pliku blokady — i nigdy nie odpytuje rejestru, więc baza dostępna tylko w rejestrze jest tu traktowana jako nieobecna. Pobraniem jej zajmuje się aggrega pull: baza jest zależnością wszystkiego, co ją rozszerza, więc pull podąża każdym łańcuchem extends:, do którego sięga encja Release, pobiera każdą bazę, której nie przechowuje żaden katalog, i przypina ją w pliku blokady, gdzie znajduje ją następne budowanie. Encja Manifest nie potrzebuje wiersza dla samej bazy, chyba że encja Aggregate deklaruje także instancję bazy.
Podpowiedzi encji Recipe pozostają węższe niż ta reguła dopasowania. Lista kandydatów wypisywana przez diagnostykę braku mapowania oraz kolejność stosowana przez uzupełnianie w edytorze do wartości mapowania wskazują recepty implementujące sam żądany typ; nie rozszerzają się na recepty implementujące którąś z jego baz.
Kompletny, uruchamialny przewodnik — opublikowaną nakładkę w katalogu, jeden wiersz encji Manifest, który z niej korzysta, encję Recipe bazy kształtującą wyrenderowany wynik oraz zatrzymanie, które powoduje instancja nakładki bez własnego mapowania — zawiera przykład examples/extends-wrapper/.
Wykorzystanie wersji między encjami
Każdy rodzaj encji Aggrega — Component, Feature, Aggregate, Recipe, FeatureRecipe, Manifest, Release, Plugin, SchemaLibrary, MappingLibrary, WorkloadLibrary, ArtifactLibrary — ma wymagane pole metadata.version, walidowane tym samym wyrażeniem regularnym SemVer (MAJOR.MINOR.PATCH zgodnie z architecture/02-ecosystem-philosophy.md). Wersje mają jednolity kształt; wykorzystanie wersji różni się w zależności od rodzaju encji. Niektóre wersje aktywnie uczestniczą w rozstrzyganiu; inne są opisową informacją o pochodzeniu, względem której kompilator niczego nie dopasowuje. Poniższa tabela obejmuje rodzaje niebędące bibliotekami: podaje, co kompilator robi z polem wersji każdej encji, i klasyfikuje każdy sposób wykorzystania za pomocą czteroetykietowej taksonomii statusów z 10-status.md. Cztery rodzaje bibliotek pozostają poza tabelą, ponieważ ich sposób wykorzystania jest jednolity i odmienny: konsument odwołuje się do biblioteki samą nazwą, może podać opcjonalne minimum wersji :<version>, a plik blokady danej encji Release przechowuje rozstrzygniętą wersję i jej skrót zawartości.
| Encja | Sposób wykorzystania | Status |
|---|---|---|
| Component | Rozstrzyganie odwołań do typu; dopasowanie implements: w encji Recipe | available — formy dokładna, zakres z daszkiem (^MAJOR.MINOR.PATCH) i bez wersji w obu przypadkach (zob. Rozstrzyganie wersji oraz Status → Dopasowanie wersji) |
| Feature | Rozstrzyganie odwołań w dołączeniach; dopasowanie implements: w encji FeatureRecipe | Tak jak dla encji Component |
| Recipe | Rozstrzyganie poziomów mapowań w encji Manifest | available — formy dokładna, z zakresem z daszkiem i bez wersji w wartości mapowania, każda wybierająca najwyższą spełniającą wersję |
| FeatureRecipe | Rozstrzyganie poziomów mapowań w encji Manifest | Tak jak dla encji Recipe |
| Aggregate | Rozstrzyganie odwołania aggregates[].type w encji nadrzędnej | available — formy dokładna, zakres z daszkiem i bez wersji, każda wybierająca najwyższą spełniającą wersję (zob. Rozstrzyganie wersji) |
| Plugin | Przekazywanie do encji Provider przez recipe.spec.capability → spec.provider.capabilities | available — sama nazwa capability wybiera dostawcę, a przypięcie wersji na niej (helm:<version>, helm:^<version>) wybiera, która wersja tego pluginu renderuje; tożsamością pluginu jest odwołanie oci://<repository> bez skrótu wraz z metadata.version, a skrót zawartości jest zapisywany w pliku blokady wydania, względem którego build weryfikuje pobrane bajty |
| Manifest | Pochodzenie w grafie IR (manifest_version) | available (odczytywane tylko na potrzeby pochodzenia; bez roli w przekazywaniu przy rozstrzyganiu) |
| Release | Pochodzenie w grafie IR (release_version) + metadane szablonów (.metadata.release_version) | Tak jak dla encji Manifest |
Sposoby rozstrzygania w katalogu (Component, Feature, Aggregate, Plugin). Odwołanie do jednego z tych rodzajów — type komponentu, type dołączenia funkcji, aggregates[].type importu podagregatu, plugin kroku potoku — jest rozstrzygane według reguły opisanej w Rozstrzyganiu wersji: odwołanie dokładne, z zakresem z daszkiem lub bez wersji wybiera najwyższą spełniającą wersję spośród tych, które zawiera katalog, a pobieranie, build, walidacja, edytor i narzędzia dla asystenta stosują tę samą regułę. Dla encji Component lub Feature dopasowanie implements: odczytuje te same trzy formy z przeciwnej strony — konkretną wersję typu względem formy zadeklarowanej przez encję Recipe lub FeatureRecipe — jako opisany niżej test spójności, a nie jako wybór. Przekazywanie do pluginu renderującego dla encji Provider ma prostszą postać: wyszukuje samą wartość recipe.spec.capability w spec.provider.capabilities pluginu renderującego dostawcy po nazwie, a przypięcie wersji zapisane na capability wybiera, która wersja tego pluginu renderuje, i zatrzymuje się, gdy żadna wersja go nie spełnia.
Rozstrzyganie poziomów mapowań w encji Manifest. Płaski mechanizm rozstrzygania mappings.{components,features} w encji Manifest (z poziomami name i type, pierwszeństwem nazwy nad typem oraz typu z wersją nad typem bez wersji) opisano w entities/manifest.md. Resolver wykorzystuje te mapowania: wybór encji Recipe i FeatureRecipe to bezpośrednie wyszukanie wartości mapowania w pliku blokady i katalogu, a komponent lub dołączenie, którego typ nie ma mapowania, zatrzymuje build. spec.implements nie wybiera encji Recipe — jest testem spójności podczas ładowania, sprawdzającym mapowanie już zapisane przez autora, oraz źródłem listy kandydatów, którą oferują diagnostyka braku mapowania i podpowiedzi edytora. Przekazywanie według możliwości wynika następnie z pola spec.capability rozstrzygniętej encji Recipe, a nie ze struktury encji Manifest.
Sposoby opisowego pochodzenia (Manifest, Release). metadata.version encji Manifest i metadata.version encji Release są odczytywane, gdy kompilator wypełnia informacje o pochodzeniu, i pojawiają się w bloku pochodzenia grafu IR jako manifest_version i release_version; żadna etykieta w wyrenderowanym wyniku nie zawiera żadnej z nich. Szablony widzą też wersję encji Release jako .metadata.release_version. Żadna z tych wersji nie jest dopasowywana do wersji innej encji przy rozstrzyganiu; służą wyłącznie do określenia pochodzenia.
Jak czytać tabelę. Czteroetykietowa klasyfikacja odróżnia „pole wersji jest akceptowane przez schemat i istnieje w encji” (zawsze prawdziwe — jednolite wyrażenie SemVer) od „kompilator dopasowuje względem tej wersji podczas rozstrzygania” (zależne od encji).
Potokowanie międzyfilarowe przez most schematu: łączenie intencji z infrastrukturą
Aggrega wyraźnie rozdziela odpowiedzialności między Domeną 1 a Domeną 4: deweloper zapisuje logikę poznawczą w bloku values, a operator określa fizyczne wymiarowanie w bloku infra. Schemat Aggregate.yaml wymusza jedną konkretną konsekwencję: słowa kluczowego infra nie ma w instancjach komponentów encji Aggregate ani w ich dołączeniach features, a w połączeniu z additionalProperties: false jest ono odrzucane przez walidację schematu. Deweloperzy nie powinni określać fizycznego wymiarowania w intencji dewelopera; gdy konkretna wartość pasuje do przypadku aplikacji (np. zakodowany na sztywno port lub konkretna liczba CPU), architekt może jawnie udostępnić ją w deklaracji schema: encji Component, a wartość przepływa przez values.
W przypadkach, gdy konkretne ograniczenie infrastrukturalne jest nieodłączną częścią kontraktu komponentu — wysokowydajna baza danych transakcyjnych, która musi mieć 10 000 przydzielonych IOPS, albo obciążenie ML, które musi działać na dokładnie 4 GPU — architekci platformy udostępniają to ograniczenie przez dedykowaną encję Component, korzystając ze wzorca potokowania międzyfilarowego przez most schematu.
Wzorzec mostu schematu dla komponentów świadomych infrastruktury.
Encja Component udostępnia konkretne pokrętło infrastrukturalne w bloku values dewelopera poprzez swoją deklarację schema:, a szablon valuesMapping: powiązanej encji Recipe przekazuje wartość do renderowanego wyjścia o kształcie infra:. W efekcie powstaje typowany most między intencją poznawczą a fizycznym wymiarowaniem: deweloper określa ograniczenie sprzętowe przez walidowane pole, a ograniczenie trafia do zespołu Ops, przy czym żadna ze stron nie pisze surowego kodu infrastruktury. Pokrętło jest kluczem filaru, więc deklaruje się je w encji Component, do której kontraktu należy — encja Component, która korzysta z extends: względem bazy, nie deklaruje kluczy filarów i dlatego nie może wprowadzić nowego.
# Domain 2: The Platform Catalog (the schema-bridge Component)apiVersion: aggrega.ai/v1beta1kind: Componentmetadata: name: core/high-perf-postgres version: 1.0.0 labels: component.aggrega.ai/type: "stateful-server"spec: schema: values: # Expose the dial safely to the Developer with a typed contract. required_iops: { type: integer, min: 1000, max: 100000, required: true } infra: # Operator-owned sizing the Recipe below reads alongside the dial. storage: { size: { type: string, default: 100Gi } } compute: { instance_class: { type: string, default: db.m5.large } }# Domain 2: The Platform Catalog (the Recipe pipes the dial into provider infra)apiVersion: aggrega.ai/v1beta1kind: Recipemetadata: name: aws-rds-high-perf-postgres version: 1.0.0spec: implements: core/high-perf-postgres:^1.0.0 capability: terraform source: ./modules/rds valuesMapping: | # The Recipe pipes the developer's values.required_iops into the provider's infra-side knob. iops: {{ .values.required_iops }} allocated_storage: "{{ .infra.storage.size }}" instance_class: "{{ .infra.compute.instance_class }}"# Domain 1: The Developer Intent (remains capability-agnostic)components: trading-db: type: core/high-perf-postgres:1.0.0 values: required_iops: 10000 # Developer dictates the hardware constraint safelySkalowanie wielośrodowiskowe (wymóg wynoszenia do parametrów).
Aby skalować to ograniczenie sprzętowe między środowiskami GitOps (Dev i Prod) bez modyfikowania pliku Aggregate.yaml dewelopera, deweloper wynosi wartość do typowanego kontraktu parameters. Ops spełnia konkretny wymóg IOPS za pomocą plików Release właściwych dla środowisk. Kolejność wykonywania w kompilatorze chroni ten przepływ: walidacja kontraktu parametrów odbywa się podczas rozwiązywania; interpolacja wstawia parametr do otaczającego ciągu values:; szablon valuesMapping: encji Recipe przekazuje rozwiązaną wartość do renderowanego wyjścia.
1. Intencja dewelopera (abstrahowanie pokrętła).
Deweloper wie, że musi sterować IOPS, ale przenosi konkretną liczbę na poziom środowiska za pomocą typowanego kontraktu parameters.
spec: parameters: env_iops: type: integer min: 1000 max: 100000 description: Provisioned IOPS for the trading-db instance components: trading-db: type: core/high-perf-postgres:1.0.0 values: required_iops: {{ .parameters.env_iops }} # Hoisted to the environment2. Releases w GitOps (realizacja przez Ops).
Ops spełnia kontrakt parameters w plikach Release właściwych dla środowisk. Typowany kontrakt waliduje każdą wartość dostarczoną przez encję Release przed uruchomieniem interpolacji.
- Środowisko Dev (
release-dev.yaml):env_iops: 1000 - Środowisko Prod (
release-prod.yaml):env_iops: 25000
Kolejność kompilacji. Ten mechanizm jest chroniony przez ścisłą kolejność wykonywania w kompilatorze podczas rozwiązywania:
- Walidacja kontraktu parametrów. Każda wartość parametru dostarczona przez encję Release jest walidowana względem typowanej deklaracji
parameters:encji Aggregate. Wartość Prod25000przechodzi walidację (mieści się wmin: 1000, max: 100000); wartość500zatrzymałaby kompilację z jasnym błędem. - Interpolacja. Kompilator odczytuje wartości parametrów z pliku
Releasedla Prod i wstawia25000do ciągu YAMLAggregatew miejscuvalues.required_iops. Scalona mapa parametrów pozostaje dostępna przez całe renderowanie, dzięki czemu powierzchnie szablonów ścieżek mogą bezpośrednio odczytywać.parameters.<slot>; powierzchnie szablonów wartości korzystają z literału po interpolacji, już zapisanego w blokuvalues:encji Aggregate. Mapa pozostaje czytelna do zakończenia wszystkich faz renderowania i jest osiągalna wyłącznie z kompilacji, dla której została rozwiązana. - Walidacja schematu. Deklaracja
schema:encji Component waliduje wynikowy słownikvalues:;values.required_iops: 25000spełnia ograniczenia schematumin: 1000, max: 100000. - Renderowanie valuesMapping encji Recipe. Szablon
valuesMapping:powiązanej encji Recipe przekazujevalues.required_iopsdo wyjścia dostawcy o kształcieinfra(iops: 25000). Plugin dostawcy Wasm generuje właściwą fizyczną konfigurację bazy danych. Deweloper otrzymuje jawną kontrolę nad sprzętem, Ops — skalowanie właściwe dla środowisk, aAggregatepozostaje agnostyczny wobec możliwości.