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

Opublikowana nakładka obsługiwana przez encję Recipe swojej bazy

Ten przykład uczy jednego: encja Component, która extends inną, dziedziczy cały kontrakt danych tej bazy, więc każda encja Recipe napisana dla bazy już implementuje rozszerzającą encję Component. Opublikowanie wyspecjalizowanego wariantu komponentu z biblioteki standardowej kosztuje zatem jedną encję katalogu i jedną linię w encji Manifest — bez własnej encji Recipe i bez zmian w bazie.

Nakładką jest tu example/gateway/nginx-reviewed. Jest dostarczana w katalogu obok core/gateway/nginx, komponentu, który rozszerza.

Co nakładka dodaje, a co dziedziczy

Cała napisana przez autora powierzchnia nakładki to metadane i jedno gniazdo:

metadata:
name: example/gateway/nginx-reviewed
labels:
component.aggrega.ai/type: server
component.aggrega.ai/category: gateway
gateway.example.com/audit-tier: reviewed # added
gateway.example.com/data-zone: eu-west # added
annotations:
governance.example.com/review-board: platform-architecture # added
governance.example.com/contact: platform-architecture@example.com
spec:
extends: core/gateway/nginx:1.0.0
schema: inherited
usesSchema:
reviewed_upstream: # added
selector: "gateway.example.com/audit-tier=reviewed"
inject: [env]

schema: inherited to dosłowny znacznik, który rozszerzająca encja Component zapisuje w miejscu bloku schema:. Stwierdza, że trzy filary danych — values, infra i provides — należą do bazy, dokładnie w takiej postaci, w jakiej baza je zdefiniowała. Nakładka nie deklaruje własnego klucza filaru i nie może tego zrobić: kontrakt należy do bazy, na każdej głębokości łańcucha.

Wszystko, czego nakładka nie wymienia, dziedziczy. aggrega inspect example/gateway/nginx-reviewed --resolved pokazuje scaloną encję, a dwie rzeczy w niej warto przeczytać uważnie:

  • Trzy gniazda uses, a nie jedno: upstream i guard (gniazda bazy, przy czym upstream wybiera component.aggrega.ai/type=server) oraz reviewed_upstream (gniazdo nakładki). Rozszerzanie dodaje gniazdo; nie zastępuje zbioru.
  • Trzy filary bazy, dosłownie — values.upstream_path, infra.port / engine_version / compute / overrides oraz provides.host / port / protocol, każdy z własnymi opisami bazy.

Co zapisuje konsumująca encja Aggregate

aggregate-reviewed.yaml deklaruje dwie warstwy bramy jako nakładkę, stojące przed konsolą bazy danych:

components:
edge:
type: example/gateway/nginx-reviewed
values:
upstream_path: /api/ # declared by the base; the wrapper never mentions it
uses:
reviewed_upstream: # the socket the wrapper ADDS
internal: { target: internal, inject: { env: [ ... ] } }
internal:
type: example/gateway/nginx-reviewed
values:
upstream_path: /
uses:
upstream: # the socket the wrapper INHERITS
console: { target: console, inject: { env: [ ... ] } }
console:
type: core/devtool/adminer

Kluczem, na który warto zwrócić uwagę, jest upstream_path. Jest zadeklarowany w filarze values komponentu core/gateway/nginx i nie pojawia się nigdzie w pliku nakładki, a mimo to autor zapisuje go w instancji nakładki i trafia on do wyrenderowanej konfiguracji bramy. Tak w praktyce wygląda dziedziczenie filarów w całości.

Drugą połową jest encja Manifest, w której na każdy typ przypada jedna linia:

mappings:
components:
type:
example/gateway/nginx-reviewed:1.0.0: compose/nginx:1.0.0
core/gateway/nginx:1.0.0: compose/nginx:1.0.0
core/devtool/adminer:1.0.0: compose/adminer:1.0.0

Obie linie bramy wskazują tę samą encję Recipe. compose/nginx deklaruje implements: core/gateway/nginx:1.0.0, a encja Recipe wskazująca bazę jest implementacją dla każdej encji Component rozszerzającej tę bazę — więc nakładka jest przez nią obsługiwana bez zmian. Zachodzą tu jednocześnie dwa fakty i są one odrębne:

  • Encja Recipe pasuje. Nie istnieje żadna encja Recipe implementująca własny typ nakładki i żadna nie jest potrzebna.
  • Mapowanie jest nadal wymagane. Wybór encji Recipe odbywa się według dokładnego klucza mapowania, więc nakładka potrzebuje własnego wpisu type; nie dziedziczy wpisu bazy. Instancja nakładki bez własnego wpisu zatrzymuje kompilację diagnostyką niezmapowanej instancji nawet wtedy, gdy jej baza jest zmapowana.

Generowanie przykładu

Ten przykład można zbudować za pomocą poniższych poleceń albo zlecić jego zbudowanie asystentowi AI.

Należy zapisać przykład w nowym folderze nazwanym tak jak on:

Terminal window
aggrega scaffold --example extends-wrapper

Następnie wypisuje polecenia do uruchomienia w dalszej kolejności. Pierwsze przechodzi do nowego folderu:

Terminal window
cd extends-wrapper

Kompilacja

Terminal window
aggrega build --release release-reviewed.yaml --auto-pull

Wyrenderowane wyjście i plik blokady są generowane, a nie dostarczane: ten przykład zatwierdza swoje dane wejściowe i generuje wszystko inne na nowo. --auto-pull rozwiązuje plik blokady podczas kompilacji; jednorazowe uruchomienie aggrega pull --release release-reviewed.yaml wcześniej robi to samo i pozwala kolejnym kompilacjom działać w ogóle bez flagi.

Zarówno nakładka, jak i rozszerzana przez nią baza znajdują się we wspólnym katalogu, który jest rozwiązywany z hub.aggrega.ai, domyślnego rejestru deklarowanego w .aggrega-config.yaml. Polecenie kompilacji nie wymaga flagi --catalog, podobnie jak aggrega inspect uruchamiane z tego katalogu.

Operacja pull pobiera core/gateway/nginx, ponieważ wrapper go rozszerza: baza jest zależnością wszystkiego, co ją rozszerza, więc operacja pull podąża za extends: wrappera i przypina bazę w pliku blokady niezależnie od tego, czy encja Manifest ją wymienia. Encja Manifest mapuje tu bazę z innego powodu — kontrolne wydanie poniżej deklaruje instancję samej bazy.

Wyrenderowany plik dist/compose/docker-compose.yaml zawiera dowody:

edge:
image: nginx:1.27.5-alpine
entrypoint:
- /bin/sh
- -c
- echo 'server { listen 8080; location /api/ { proxy_pass http://internal:8081; } }' > /etc/nginx/conf.d/default.conf && exec nginx -g 'daemon off;'
[… omitted: the published port]
labels:
[… omitted: the other provenance labels every rendered document carries]
aggrega.ai/recipe-uri: nginx:1.0.0
[… omitted: the service's network, its depends_on naming internal, and its healthcheck]

Trzy odczyty, w kolejności tego, czego dowodzą:

  • aggrega.ai/recipe-uri: nginx:1.0.0 — tę usługę ukształtowała encja Recipe bazy. Etykieta pochodzenia na instancji nakładki wskazuje encję Recipe bazy, ponieważ to ta encja Recipe ją wyrenderowała.
  • location /api/ — values.upstream_path, klucz deklarowany wyłącznie przez bazę, zapisany w instancji nakładki i wyrenderowany.
  • proxy_pass http://internal:8081 — krawędź reviewed_upstream została rozwiązana. provides.host i provides.port celu trafiły do kontekstu wstrzykiwania pod kluczami dostarczania, które odczytuje encja Recipe bazy, więc gniazdo dodane przez nakładkę przepływa przez encję Recipe, która nigdy o nim nie słyszała.

Plik blokady rozwiązywany przez kompilację odnotowuje ten sam fakt od strony resolvera: jeden wpis compose/nginx:1.0.0 z jednym skrótem, do którego odwołują się oba klucze mapowania — typ bazy i typ nakładki.

Etykiety i adnotacje nakładki przemieszczają się wraz z rozwiązaną krawędzią: kontekst renderowania węzła konsumującego zawiera provides, labels i adnotacje każdego celu, więc kontekst edge wie, że jego upstream to audit-tier=reviewed i kto go przejrzał. To, czy cokolwiek z tego pojawi się w wyrenderowanym artefakcie, jest wyborem encji Recipe — te etykiety i adnotacje stanowią tożsamość komponentu do odczytu przez selektory i polityki, a nie wyjście, które kompilator nanosi.

Z asystentem AI

Asystent AI skonfigurowany z narzędziami Aggrega może zrobić to samo: wystarczy wkleić mu ten prompt.

Używaj wyłącznie narzędzi Aggrega i nie twórz samodzielnie żadnego folderu. Jeśli folder obszaru roboczego nie zawiera jeszcze folderu `extends-wrapper`, wywołaj raz narzędzie `scaffold` z `example` ustawionym na `extends-wrapper` i bez `dir`: zapisuje ono przykład w nowym folderze `extends-wrapper`. Następnie wywołaj narzędzie `build` z `workspace_root` ustawionym na `extends-wrapper`, `release` ustawionym na `release-reviewed.yaml`, `auto_pull` ustawionym na true i `write` ustawionym na true. Podaj mi, które pliki zapisała kompilacja; znajdują się w `extends-wrapper/dist/`.

Próba kontrolna: do czego służy dodana etykieta

aggregate-unreviewed.yaml to aggregate-reviewed.yaml z jedną zmianą — warstwa wewnętrzna jest zadeklarowana jako sama baza core/gateway/nginx zamiast nakładki — i oczekuje się, że zakończy się niepowodzeniem:

Terminal window
aggrega build --release release-negative-unreviewed.yaml --auto-pull
# [DEVELOPER_ERROR E0007] aggregate-unreviewed.yaml at .spec.components.edge.uses.reviewed_upstream.internal
# selector violation ("gateway.example.com/audit-tier=reviewed", declared on socket "reviewed_upstream", not satisfied by the labels of "internal"). Add the labels the selector requires to the target's component type, or wire the socket to a component that already carries them.

Zatrzymanie jest lekcją. Baza spełnia swoje własne gniazdo upstream — jest component.aggrega.ai/type=server, a warstwa wewnętrzna jest podłączona przez to gniazdo dokładnie w ten sam sposób — ale nie ma etykiety audit-tier, więc ostrzejsze gniazdo nakładki ją odrzuca. Etykieta dodawana przez nakładkę sprawia, że jej instancję można wybrać, a widać to w selektorze.

Warto znać jeszcze dwa zatrzymania; w obu przypadkach schemat wykonuje swoje zadanie:

  • Encja Component, która deklaruje extends i zapisuje zawartość filarów pod schema:, jest odrzucana podczas wczytywania dokumentu, z nazwaniem ograniczenia. Tak samo encja, która całkowicie pomija schema:. schema: inherited to jedyna akceptowana forma; jest zapisywana jawnie, a nie domniemywana, aby czytelnik nigdy nie pomylił odziedziczonego bloku filarów z zapomnianym.
  • Klucz values, którego baza nie deklaruje, jest odrzucany w instancji nakładki, w zapisanej ścieżce, ponieważ egzekwowany kontrakt należy do bazy.

Dlaczego to jest przydatne

Organizacja, która ustaliła przejrzany kształt komponentu z biblioteki standardowej, potrzebuje miejsca, w którym go przechowa. Opisane prozą etykiety, adnotacje i gniazda są powtarzane w każdej encji Aggregate, która ich potrzebuje, i z czasem się rozjeżdżają. Opublikowany jako encja Component rozszerzająca bazę kształt staje się wersjonowaną, podlegającą przeglądowi encją katalogu z nazwą: zespół, który z niej korzysta, zapisuje type: example/gateway/nginx-reviewed i jedną linię w encji Manifest, a dziedziczy cały kontrakt bazy wraz z każdą encją Recipe już dla niej napisaną, na każdym celu obsługiwanym przez bazę.

To, ile kosztuje nakładka, sprawia, że to działa: dodaje strukturę i metadane i nic więcej. Ponieważ nie deklaruje filarów, instancja nakładki i instancja bazy są walidowane względem jednego kontraktu, a encja Recipe napisana dla bazy nigdy nie zostanie zaskoczona jej specjalizacją.