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

Kontekst szablonów parametrów

Filar parameters: przenosi wartości parametrów dostarczone przez encję Release i zwalidowane względem kontraktu. Ich dostępność określają dwa równoległe modele myślowe:

  • Powierzchnie szablonów wartości (ciągi values: komponentów, funkcji i podagregatów wewnątrz encji Aggregate, a także valuesMapping encji Recipe, injectMapping i provides encji FeatureRecipe oraz treści encji Workload) konsumują wartości parametrów jako już zinterpolowane literały. Przebieg interpolacji w ramach rozwiązywania ewaluuje cały tekst encji Aggregate jako szablon i zastępuje każde odwołanie {{ .parameters.<slot> }} rozwiązaną wartością; dalsze powierzchnie szablonów wartości nigdy nie widzą .parameters bezpośrednio w swoim kontekście szablonu.
  • Powierzchnie szablonów ścieżek (tworzone przez operatora szablony directory: i subDirectory: na granicach encji Release) odczytują .parameters.<slot> bezpośrednio podczas ewaluacji szablonów ścieżek w trakcie renderowania. Scalona mapa parametrów pozostaje czytelna do końca renderowania, aby szablon ścieżki mógł odczytywać .parameters względem zamkniętej listy dozwolonych zmiennych.

Asymetryczne uprawnienie — szablony ścieżek odczytują .parameters bezpośrednio, a szablony wartości nie — sprawia, że każda warstwa zarządza tym, czego potrzebuje: values: po stronie dewelopera przekazują dalej do szablonów wartości już rozwiązane dane specyficzne dla środowiska; szablony ścieżek po stronie operatora odwołują się do parametrów regionu, środowiska czy identyfikatora konta bez przechodzenia przez schemat values encji Aggregate.

Ta strona opisuje przebieg interpolacji, kształty wartości poszczególnych slotów, wzorce dostępu w ciągach YAML encji Aggregate, wyjątek dla szablonów ścieżek oraz to, jak długo scalona mapa pozostaje odczytywalna. Szerszy kształt kontekstu szablonów encji Recipe / FeatureRecipe (.values, .infra, .uses itd.) opisuje template-context-contract.md. Dostępność w poszczególnych miejscach szablonów w całym potoku kompilacji opisuje expansion-matrix.md. Kształt deklaracji kontraktu typowanych parametrów w encji Aggregate opisuje entities/aggregate.md, sekcja „Typed parameter contracts”. Listę dozwolonych zmiennych szablonów ścieżek, która obejmuje .parameters.<slot> przy ewaluacji directory: / subDirectory: na granicy, opisuje path-template-variables.md.

Cykl życia parametrów

Kompilator rozwiązuje parametry w czterech kolejnych fazach:

  1. Odczyt kontraktu — blok spec.parameters: encji Aggregate jest sprawdzany sam w sobie, zanim zostanie przejrzana jakakolwiek wartość z encji Release, więc slot, który nie mógłby niczego ograniczać, zatrzymuje kompilację nawet wtedy, gdy żadna encja Release go nie dostarcza. Ujemna wartość minLength lub maxLength we własnej deklaracji parametru jest odrzucana podczas ładowania encji Aggregate, z podaniem parametru i klucza. Każdy pattern — w samym slocie oraz w dowolnym zagnieżdżonym kontrakcie pod items, properties lub valuesType — jest kompilowany jako wyrażenie regularne, a taki, który się nie kompiluje, jest odrzucany z podaniem parametru, wzorca i przyczyny. Ograniczenie długości w zagnieżdżonym kontrakcie nie podlega temu dolnemu progowi; zob. entities/aggregate.md.
  2. Uzupełnianie wartości domyślnych — sloty z zdefiniowanym default: i bez wartości dostarczonej przez encję Release otrzymują swoją wartość domyślną. Mapa .parameters jest w tym momencie w zasięgu.
  3. Walidacja kontraktu parametrów — każda wartość w scalonej mapie, niezależnie od tego, czy dostarczyła ją encja Release, czy uzupełnił ją default:, jest walidowana względem ograniczeń zadeklarowanych w spec.parameters.<slot> encji Aggregate: type / enum / min / max / pattern / struktury zagnieżdżonej; pattern jest dopasowywany do wyrażenia skompilowanego podczas odczytu kontraktu. Mapa .parameters istnieje w kontekście walidatora w pamięci jako sprawdzany ustrukturyzowany ładunek.
  4. Interpolacja — kompilator ewaluuje cały tekst encji Aggregate jako szablon, zanim odczyta go jako YAML, i zastępuje każde odwołanie {{ .parameters.<slot> }} rozwiązaną wartością; każde inne {{ w tekście również jest odczytywane jako składnia szablonu, więc wartość zawierająca własne podwójne nawiasy klamrowe zapisuje każde {{ jako {{"{{"}} (zob. Tekst zawierający własne podwójne nawiasy klamrowe). Interpolacja jest ścieżką podstawiania dla powierzchni szablonów wartości — po tym przebiegu konteksty szablonów wartości nie zawierają już .parameters; korzystają z rozwiązanych wartości wpisanych w otaczające ciągi values:. Scalona mapa pozostaje czytelna po interpolacji, przez całe renderowanie, właśnie po to, by umożliwić ewaluację szablonów ścieżek. Czas jej dostępności jest ograniczony czasem trwania kompilacji: kompilator przekazuje rozwiązany widok kompilacji, która z niego korzysta, zamiast zwracać go wywołującemu, więc nic spoza tej kompilacji nie może sięgnąć do mapy. Powierzchnia szablonów ścieżek (directory: / subDirectory: w encji Release) odczytuje .parameters.<slot> podczas renderowania, względem zamkniętej listy dozwolonych opisanej w path-template-variables.md.

Szablony w ciągach YAML encji Aggregate (values: komponentu, values: funkcji, wyrażenia przekazujące parameters: podagregatu) odczytują mapę .parameters za pomocą standardowej składni szablonów Go podczas przebiegu interpolacji. Szablony w plikach Recipe i FeatureRecipe NIE otrzymują .parameters w swoim kontekście szablonu (kontrakt dla poszczególnych powierzchni opisano poniżej w sekcji „Granica z kontekstami szablonów niższego poziomu”).

Tekst zawierający własne podwójne nawiasy klamrowe

Ponieważ cały tekst jest szablonem, podwójne nawiasy klamrowe należące do wartości, a nie do szablonu, również są odczytywane jako akcje szablonu. Typowym przypadkiem jest definicja platformy przepływów umieszczona w values: komponentu: n8n otacza podwójnymi nawiasami klamrowymi każde wyrażenie w parametrach węzła, jak w ={{ $json.body.message }}, prompt Flowise nazywa zmienną jako {{question}}, a chatflow Flowise zapisuje {{chatOpenAI_0.data.instance}} dla każdego połączenia między dwoma węzłami, natomiast eksport Langflow zawiera kod źródłowy swoich komponentów, w którym nawiasy również mogą się pojawić. Zapisane w encji Aggregate bez zmian zatrzymują kompilację na tej encji Aggregate z błędem E0158, opisanym pod hasłem „A {{ .parameters.* }} reference cannot be interpolated (Nie można zinterpolować odwołania)” na stronie Fatal halts; jego przyczyna wskazuje wiersz i pierwszy token, którego silnik szablonów nie mógł odczytać — undefined variable "$json" w przypadku wyrażenia n8n. Komentarz YAML również jest tekstem szablonu, więc {{ zapisane w komentarzu zatrzymuje kompilację w ten sam sposób.

Każde {{ w takiej wartości należy zapisać jako {{"{{"}}. Jest to akcja szablonu, której wynikiem jest ciąg {{, więc interpolacja przywraca oba nawiasy. Zamykające }} nie wymaga niczego, ponieważ poza akcją jest zwykłym tekstem. Interpolacja jest wykonywana raz, na tekście encji Aggregate, a szablon encji Recipe zapisuje to, co odczytuje z .values, jako dane, więc przywrócone nawiasy trafiają do wyrenderowanego wyniku w postaci, w jakiej zostały wyeksportowane.

# Aggregate fragment — an n8n workflow definition carried as exported
spec:
components:
automation:
type: core/ai-agent/n8n
values:
workflow_id: support-reply
flow_definition: |
{
"name": "Support reply",
"nodes": [
{
"name": "Set reply",
"type": "n8n-nodes-base.set",
"parameters": {
"value": "={{"{{"}} $json.body.message }} for {{"{{"}} $env.SUPPORT_TEAM }}"
}
}
],
"connections": {}
}

Platforma otrzymuje "value": "={{ $json.body.message }} for {{ $env.SUPPORT_TEAM }}".

Taką definicję należy przechowywać w skalarze blokowym (|), jak powyżej, gdzie cudzysłowy sekwencji ucieczki są zwykłymi znakami. Tekst encji Aggregate jest też odczytywany jako YAML przed interpolacją, a wewnątrz ciągu YAML w podwójnym cudzysłowie znak " sekwencji ucieczki zamyka ciąg, więc plik przestaje być poprawnie parsowany, a kompilacja zatrzymuje się z błędem YAML.

Wzorzec dostępu .parameters.<slot>

Każdy zadeklarowany slot parametru jest dostępny jako pole mapy .parameters. Dostęp zgodny z typem odpowiada zadeklarowanemu type:

# Aggregate fragment — parameter declarations
spec:
parameters:
region: { type: string, enum: [us-east-1, us-west-2] }
cache_ttl_seconds: { type: integer, min: 1, max: 86400, default: 60 }
enable_debug: { type: boolean, default: false }
components:
web:
type: core/web-server:1.0.0
values:
region: "{{ .parameters.region }}" # string
cache_ttl_seconds: {{ .parameters.cache_ttl_seconds }} # integer
debug: {{ .parameters.enable_debug }} # boolean

Przebieg interpolacji wykonuje ewaluację szablonu Go względem mapy .parameters; wynik zastępuje wyrażenie szablonu w miejscu, w dokumencie. Następnie schemat values: encji Component / Feature waliduje otrzymaną wartość w fazie walidacji schematu po interpolacji, będącej częścią rozwiązywania.

Cudzysłowy decydują o typie przeniesionej wartości

Odwołanie kierowane do liścia typu string należy ująć w cudzysłów; dla każdego innego zadeklarowanego typu należy pozostawić je bez cudzysłowu. Jest to reguła samego YAML, a nie dodatkowa reguła Aggrega: interpolacja podstawia spełnioną wartość do bajtów dokumentu i nie robi nic więcej, więc następujące po niej parsowanie odczytuje wynik dokładnie tak, jak każdy inny skalar. Odwołanie bez cudzysłowu {{ .parameters.cache_ttl_seconds }} niesie własny typ spełnionej wartości, dzięki czemu parametr całkowitoliczbowy trafia do liścia całkowitoliczbowego, a parametr logiczny do liścia logicznego. Odwołanie w cudzysłowie "{{ .parameters.cache_ttl_seconds }}" niesie string, a liść zadeklarowany jako integer lub boolean go odrzuca: napisana wartość nie przechodzi walidacji typu względem schematu values: swojej encji Component lub Feature, a diagnostyka wskazuje niezgodność typu, a nie ograniczenie przestrzeni wartości, którego string również by nie spełnił.

Odwołanie, które dzieli skalar z innym tekstem, jest stringiem niezależnie od sposobu zapisu, ponieważ w dokumencie po podstawieniu jest jeden skalar do odczytania — image: app:{{ .parameters.tag }} daje app:1.4.0. Po tę formę należy sięgnąć, gdy parametr niebędący stringiem ma trafić do liścia typu string.

Dostęp do slotów typu obiektowego i tablicowego

Sloty parametrów typu obiektowego udostępniają zadeklarowane właściwości jako zagnieżdżone pola w mapie .parameters.<slot>. Sloty typu tablicowego udostępniają semantykę wycinków szablonów Go (range, index, len).

# Aggregate fragment — object-typed parameter
spec:
parameters:
database_config:
type: object
properties:
host: { type: string, required: true }
port: { type: integer, min: 1, max: 65535, default: 5432 }
ssl_mode: { type: string, enum: [disable, require, verify-full] }
components:
api:
type: core/compute/api:1.0.0
values:
db_host: "{{ .parameters.database_config.host }}"
db_port: {{ .parameters.database_config.port }}
db_ssl: "{{ .parameters.database_config.ssl_mode }}"

Sloty parametrów typu tablicowego obsługują iterację za pomocą range:

# Aggregate fragment — array-typed parameter
spec:
parameters:
allowed_hosts:
type: array
items: { type: string, format: hostname }
min: 1
components:
ingress:
type: core/ingress:1.0.0
values:
# Compose a comma-separated list from the parameter array
hosts: "{{ range $i, $h := .parameters.allowed_hosts }}{{ if $i }},{{ end }}{{ $h }}{{ end }}"

Każdy element dostarczany przez encję Release jest sprawdzany względem kontraktu items przed interpolacją, więc wartość, która nie jest nazwą hosta — na przykład * — zatrzymuje budowanie z komunikatem wskazującym parametr, element i format. Nazwy akceptowane przez format oraz to, co każda z nich sprawdza, wymieniono w vocabulary/compact-form-authoring.md.

Podczas interpolacji dostępna jest biblioteka szablonów Sprig, która udostępnia funkcje pomocnicze, takie jak join, do zwięzłej konwersji tablic na ciągi znaków:

hosts: "{{ join `,` .parameters.allowed_hosts }}"

Semantyka uzupełniania wartości domyślnych

Slot parametru z deklaracją default: otrzymuje swoją wartość domyślną, gdy encja Release pomija ten slot. Wartość domyślna jest stosowana przed przebiegiem walidacji kontraktu, więc walidacja widzi wartość rozwiązaną (dostarczoną przez encję Release lub domyślną):

# Aggregate
spec:
parameters:
timeout_seconds:
type: integer
min: 1
max: 300
default: 30
components:
api:
type: core/compute/api:1.0.0
values:
timeout: {{ .parameters.timeout_seconds }}
# Release omits timeout_seconds — interpolation uses default: 30
# Release supplies timeout_seconds: 60 — interpolation uses 60
# Release supplies timeout_seconds: 0 — validation rejects (below min: 1)
# Release supplies timeout_seconds: 500 — validation rejects (above max: 300)
# Release supplies timeout_seconds: "thirty" — validation rejects (type mismatch)

Slot oznaczony required: true bez default: powoduje błąd w czasie budowania, gdy encja Release go pomija (E0165). Błąd wskazuje slot i jego lokalizację w kontrakcie, którą autor ma poprawić. Slot, który nie ma ani required: true, ani default:, jest opcjonalny: gdy zostanie pominięty, każde odwołanie do niego interpoluje się jako puste, a wynik ocenia następnie schemat values: encji Component.

Parametry będące zagnieżdżonymi obiektami

Gdy parametr deklaruje type: object z properties:, których elementy podrzędne same mają wartości default:, trzy przypadki tworzenia dają różne wyniki. Zrozumienie tej różnicy ma znaczenie, gdy deklaracja parametru jest ustrukturyzowanym obiektem — konfiguracją bazy danych, zestawem flag funkcji, polityką limitów czasu i ponowień — a nie pojedynczą wartością skalarną.

Przypadek 1 — Release pomija slot nadrzędny. Uzupełniane są wartości domyślne elementów podrzędnych z kontraktu. Autor encji Aggregate, który zadeklarował zagnieżdżone wartości domyślne, otrzymuje zamierzone zachowanie: gdy zespół operacyjny nie dostarcza slotu, konfiguracja używa udokumentowanych wartości domyślnych.

# Aggregate
spec:
parameters:
database:
type: object
properties:
host: { type: string, default: "localhost" }
port: { type: integer, default: 5432 }
# Release (parent omitted)
spec:
parameters: {}
# Resolved at template-interpolation time
parameters:
database:
host: "localhost"
port: 5432

Przypadek 2 — Release zapisuje element nadrzędny jako jawnie pustą mapę. Jawna pusta wartość jest respektowana jako świadoma rezygnacja. Wartości domyślne elementów podrzędnych NIE są uzupełniane; slot pozostaje pusty. Tej formy należy używać, gdy zespół operacyjny chce wyłączyć zagnieżdżone wartości domyślne kontraktu bez dostarczania nadpisań — na przykład gdy konsument na dalszym etapie oczekuje, że slot będzie obecny, ale pusty.

# Release (parent explicit empty)
spec:
parameters:
database: {}
# Resolved at template-interpolation time
parameters:
database: {}

Różnica względem przypadku 1 jest zamierzona: zespół operacyjny może wyrazić zarówno „użyj wartości domyślnych” (pomijając slot), jak i „wyłącz wartości domyślne” (zapisując slot jako {}). Odzwierciedla to sposób, w jaki Aggrega traktuje jawne null w adnotacjach — adnotacja zapisana jako aggrega.ai/<key>: null jest świadomą rezygnacją, odrębną od całkowitego pominięcia adnotacji.

Przypadek 3 — Release częściowo zapisuje element nadrzędny. Elementy podrzędne dostarczone przez encję Release przyjmują zapisane wartości; elementy podrzędne, których encja Release nie dostarczyła, są uzupełniane wartościami domyślnymi.

# Release (partial)
spec:
parameters:
database:
host: "db.prod.example.com"
# Resolved at template-interpolation time
parameters:
database:
host: "db.prod.example.com" # Release-supplied
port: 5432 # filled from default

Jest to typowy przypadek dla autorów encji Release, którzy chcą nadpisać wybrane pola, pozostawiając resztę z wartościami domyślnymi kontraktu.

Kiedy używać której formy

  • Pominięcie slotu, gdy mają zostać zastosowane wartości domyślne kontraktu.
  • Zapisanie {}, gdy slot ma świadomie być obecny, ale pusty — gdy wartości domyślne kontraktu są nieodpowiednie dla danego środowiska, a nie ma nadpisań.
  • Częściowe zapisanie, gdy potrzebne są niektóre nadpisania, a reszta ma używać wartości domyślnych kontraktu.

Autor encji Release, który wpisuje database: {}, oczekując „daj mi wartości domyślne”, będzie zaskoczony — rozwiązana wartość jest pusta, a nie uzupełniona wartościami domyślnymi. Aby otrzymać wartości domyślne, należy całkowicie pominąć slot.

Rozstrzyganie między trzema przypadkami odbywa się osobno dla każdego elementu równorzędnego na każdym poziomie zagnieżdżenia. Element nadrzędny zapisany jako { connection: {}, other_field: "x" } daje rozwiązane drzewo, w którym connection jest puste (przypadek 2 na głębokości 1), a other_field ma wartość dostarczoną przez encję Release (przypadek 3 na głębokości 0) — przypadki są rozstrzygane niezależnie dla każdego elementu równorzędnego, a nie jedną decyzją dla całego poddrzewa.

Granica z kontekstami szablonów na dalszych etapach

Asymetryczne uprawnienie — szablony ścieżek odczytują .parameters bezpośrednio, a szablony wartości nie — jest kluczowym rozróżnieniem na tej granicy. Semantyka granicy dla poszczególnych powierzchni:

  • Szablon values: komponentu w encji Aggregate, który zapisuje {{ .parameters.X }}, jest poprawnie rozwiązywany podczas interpolacji. Rozwiązany literał zostaje wpisany w miejscu do ciągu YAML.
  • Szablon valuesMapping: w encji Recipe, który zapisuje {{ .parameters.X }}, jest powierzchnią szablonu wartości; kontekst szablonu nie zawiera .parameters. Autorzy potrzebujący zmienności zależnej od środowiska w valuesMapping: wyrażają ją przez ścieżkę konsumpcji rozwiązanego .values.<key> — encja Aggregate udostępnia parametr, odwołuje się do niego w values: encji Component, encja Release go wypełnia, a wartość po interpolacji przepływa dalej do encji Recipe.
  • Szablon injectMapping:, provides: lub pipeline.with: w encji FeatureRecipe jest powierzchnią szablonu wartości; tak samo jak valuesMapping: w encji Recipe. .parameters nie występuje w kontekście szablonu.
  • Szablon treści encji Workload (zawartość workload: wewnątrz encji Recipe) jest powierzchnią szablonu wartości; tak samo.
  • Szablon ścieżki (directory: / subDirectory: granicy w encji Release) stanowi wyjątek. Kontekst szablonu ścieżki zawiera .parameters.<slot> zgodnie z zamkniętą listą dozwolonych wartości; odwołania są rozwiązywane, gdy renderowanie umieszcza wyjście każdej granicy. Pełną macierz zmiennych szablonów ścieżek opisuje path-template-variables.md.

Granicę własności czterech domen zachowuje to, która powierzchnia otrzymuje parametry, a nie to, czy mapa parametrów istnieje w pamięci na danym etapie potoku. Szablony ścieżek są tworzone przez operatorów i do nich należą; przyznanie im bezpośredniego dostępu do parametrów utrzymuje sprawy operatora (układ artefaktów zależny od środowiska) wewnątrz powierzchni operatora. Szablony wartości są tworzone po stronie katalogu; odmowa bezpośredniego dostępu do parametrów utrzymuje luźne powiązanie tworzenia po stronie katalogu z kontraktem encji Aggregate jako jedynego źródła prawdy.

Scalona mapa parametrów pozostaje czytelna do zakończenia wszystkich faz renderowania i nie dłużej: jest osiągalna tylko z kompilacji, dla której została rozwiązana, więc jej czas życia jest ograniczony czasem życia kompilacji.

Łączenie filarów danych

Parametry są interpolowane do otaczających je ciągów wartości podczas rozwiązywania. Interpolowane wartości mogą trafić do dowolnego filaru, który encja Aggregate definiuje w swoim zakresie: do ciągów values: komponentów, ciągów values: funkcji, deklaracji przekazania parameters: podagregatów (w których wartość parametru nadrzędnej encji Aggregate zostaje rozwiązana, a następnie przekazana do slotu parametru podrzędnej encji Aggregate) oraz ciągów metadanych name: / labels:.

Łączenie działa w jednym kierunku: wartość parametru przepływa z dostarczonego przez encję Release (lub domyślnego) .parameters.<slot> do ciągu YAML w miejscu odwołania. Parametry nie przepływają w drugą stronę — parametr nie może odczytać pola values:, pola provides: ani zawartości żadnego innego filaru. Ta jednokierunkowość jest częścią gwarancji kontraktu parametrów, że działa on wyłącznie w czasie kompilacji.

Odsyłacze

  • Kształt deklaracji kontraktu typowanych parametrów w encji Aggregate: entities/aggregate.md §„Typed parameter contracts”.
  • Szerszy kontekst szablonu, z którego korzystają encje Recipes podczas renderowania bazowego (.values, .infra, .uses, .context.* itd.): template-context-contract.md.
  • Dostępność w poszczególnych miejscach szablonów w całym potoku kompilacji (które pola są obecne w którym miejscu ewaluacji): expansion-matrix.md.
  • Lista kontrolna wynoszenia parametrów (cztery kolejne punkty styku przy tworzeniu — deklaracja w encji Aggregate, odwołanie w wartościach, wypełnienie w encji Release, wykorzystanie w encji Recipe): vocabulary/data-pillars.md §„The parameter-hoisting checklist”.
  • Szerszy zestaw filarów danych (values:, infra:, provides:, uses:, features:, locals:, parameters:): vocabulary/data-pillars.md.