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

Dokumentacja języka

„Co” i „jak używać” w Aggrega. Składnia, wywoływanie CLI, katalog błędów, opracowane przykłady.

Przy pierwszym zapoznawaniu się z językiem należy czytać poniższe rozdziały po kolei. Podkatalogi referencyjne są wymienione pod swoimi rozdziałami — można przejść do nich bezpośrednio, szukając konkretnej encji, słowa kluczowego, dostawcy, polecenia CLI lub błędu.

Przed lekturą kolejnych rozdziałów należy zajrzeć do Stanu języka, aby poznać bieżący stan gotowości — które elementy języka są dostępne już dziś, które są akceptowane, ale kompilator jeszcze na nie nie reaguje, a które są planowane w przyszłych iteracjach. Sekcja Zgodność określa, co wydanie obiecuje w zakresie schematów, wiersza poleceń, narzędzi asystenta, kodów błędów i zestawów narzędzi dla pluginów.

Model poziomów encji

Autorskie rodzaje encji w Aggrega są zorganizowane w trzy poziomy odzwierciedlające stopniowe wdrażanie (poniżej). Obok nich istnieje należąca do platformy encja Workload, która nie jest osobnym rodzajem autorskim — to kształt, jaki przyjmuje syntetyzowane wejście encji Recipe, wyrażający kształt obliczeń za pomocą słownika form: (stateless, stateful, daemon, scheduled, task, reference). Podział na poziomy jest mechanizmem dokumentacyjnym i wdrożeniowym, a nie ograniczeniem w czasie wykonania: każdy rodzaj encji jest pełnoprawnym elementem języka; kompilator traktuje je jednakowo; otwartoźródłowy Aggrega obsługuje wszystkie poziomy bez licencjonowania ani blokowania funkcji. Oznaczenia poziomów sygnalizują „zaawansowane; pomiń, jeśli niepotrzebne” na potrzeby nawigacji, a nie możliwości.

PoziomRodzaje encjiKiedy wdrożyć
Poziom 1 — minimalna użyteczna powierzchniaAggregate, Component, Recipe, Manifest, ReleaseDzień 1 — samodzielni założyciele i małe zespoły dostarczają działające oprogramowanie, korzystając wyłącznie z poziomu 1. Model myślowy: „Mam aplikację; chcę ją wdrożyć; oto jak.”
Poziom 2 — rozdzielenie rólFeature, FeatureRecipe, PluginDzień 30 — małe zespoły, w których role się rozdzielają (programista + Ops + czasem Security). Poziom 2 pojawia się poprzez Plugins renderujące dla dostawców (Ops wybierają spośród Helm, helm-chart, Compose, Terraform i CloudFormation), Features (Security zarządza poświadczeniami oddzielnie od konfiguracji aplikacji) oraz FeatureRecipes (dostosowanie w czasie wiązania dla każdego dostawcy).
Poziom 3 — ponowne użycie między encjami ComponentSchemaLibrary, MappingLibrary, WorkloadLibrary, ArtifactLibraryDzień 365 — dojrzałe katalogi, w których wspólne kształty powtarzają się w wielu encjach. Próg jest nieformalny: gdy kształt (np. PodResources) występuje w ponad 5 encjach Components, a koordynowanie aktualizacji staje się uciążliwe, wpis w SchemaLibrary jest uzasadniony.

Każdy krok jest opcjonalny. Samodzielny założyciel nigdy nie jest zmuszany do zaglądania do poziomu 3; katalog przedsiębiorstwa ma pełny dostęp do poziomu 3 w razie potrzeby. Poziom 1 jest kompletny dla przypadku samodzielnego założyciela — programista może dostarczać działające aplikacje, używając wyłącznie encji poziomu 1. To istotna właściwość projektu: poziom 1 nie jest „podzbiorem, który się kompiluje”; jest „podzbiorem, który dostarcza oprogramowanie”.

Pięcioencjowa powierzchnia poziomu 1 wiąże się z kosztem wejścia — Aggregate + Component + Recipe + Manifest + Release to więcej ceremonii niż „wrzuć plik YAML, otrzymaj działającą usługę”. Koszt ten jest ceną rozdzielenia autorstwa na cztery domeny (Developer Intent / Platform Catalog / Platform Ops / Routing), które odróżnia Aggrega od samego Helm czy samego Terraform. Samouczki poziomu 1 jawnie przeprowadzają przez konfigurację pięciu encji.

W ramach poziomu 3 mechanizm spec.templates / $instantiate: (parametryczne pomocniki w SchemaLibrary) jest opisany jako jeszcze bardziej zaawansowana funkcja podrzędna. Większość użytkowników poziomu 3 początkowo nie sięga po spec.templates; próg to „gdy biblioteka ma ponad 6 schematów współdzielących sparametryzowaną strukturę”.

Kolejność czytania

  1. Jak korzystać z tej dokumentacji referencyjnej
  2. Konwencje nazewnictwa
  3. Przegląd encji
  4. Przegląd słownictwa
  5. Przegląd szablonów
  6. Providers — przegląd
  7. Przegląd CLI
  8. Przegląd błędów
  9. Przegląd przykładów

Dokumentacja referencyjna tworzenia encji Plugin

Interfejs pluginów Wasm znajduje się obok sekwencji rozdziałów, a nie w jej obrębie: autor pluginu czyta go niezależnie od ścieżki tworzenia encji. Strona encji plugin opisuje interfejs tworzenia w katalogu; poniższe strony opisują gniazda, ładunki i przepływ pracy autora.

  • plugin-contract — gniazda, do których podłącza się plugin, ich miejsce w potoku oraz kształty wejścia i wyjścia każdego gniazda.
  • plugin-developer-guide — kompletny przepływ pracy autora: describe(), deklaracje uprawnień, limity środowiska uruchomieniowego, cykl publish/pull/build, podpisywanie, wersjonowanie.
  • policy-socket — szczegółowy opis gniazda zarządzania: jego cztery role, poziomy ważności werdyktów, kanał wejściowy operatora oraz pisanie polityki dla każdego z silników dostarczanych w kompilatorze.
  • governance-attachment-facts — fakty dotyczące poszczególnych powiązań, które polityka zarządzania odczytuje z grafu budowania, w tym trzy jednostki oznaczenia wrażliwości oraz powód, dla którego brak oznaczenia nie oznacza zezwolenia.
  • when-to-use-a-pipeline-step — wybór między krokiem potoku a szablonową encją FeatureRecipe.
  • embedded-plugins — pluginy dostarczane w pliku binarnym kompilatora.
  • tagging-plugins — dwie wbudowane wtyczki ładu, które zapisują etykiety bez zasady, governance/label-injector i governance/selector-tagger: ich ustawienia i to, co zapisuje każda z nich.
  • core-importers — dziesięć importerów kompilatora, od Langflow, Flowise i n8n po Compose, MCP i frameworki agentowe: co każdy z nich odczytuje i szkicuje, ich ustawienia oraz ich publikacja z każdym wydaniem kompilatora.
  • authoring-a-provider-walkthrough — praktyczny przewodnik po tworzeniu modułu gościa providera, od pustego katalogu do kompilacji, która zapisuje pliki wyrenderowane przez providera.
  • writing-a-governance-plugin — pisanie własnej wtyczki ładu na podstawie szkieletu adaptera z zestawu do tworzenia wtyczek: jedna reguła, ręczne uruchomienie eksportu każdej roli, encja Plugin w katalogu obszaru roboczego i kompilacja, którą wtyczka odrzuca.
  • compatibility — jak wersjonowane są zestawy narzędzi dla pluginów: co może zmienić wydanie poprawkowe i wydanie podrzędne zestawu oraz co zapewnia, że zbudowany plugin nadal się ładuje.