Ngữ cảnh template của parameters
Trụ cột parameters: mang các giá trị tham số do Release cung cấp và đã được kiểm tra theo hợp đồng. Hai mô hình tư duy song song chi phối khả năng truy cập của nó:
- Các bề mặt template giá trị (các chuỗi
values:của component / feature / sub-aggregate bên trong Aggregate, cùng vớivaluesMappingcủa Recipe,injectMappingvàprovidescủa FeatureRecipe, và phần thân của Workload) tiêu thụ các giá trị tham số dưới dạng literal đã được nội suy sẵn. Lượt nội suy bên trong quá trình phân giải đánh giá toàn bộ văn bản của Aggregate như một template và thay thế mọi tham chiếu{{ .parameters.<slot> }}bằng giá trị đã phân giải; các bề mặt template giá trị ở hạ nguồn không bao giờ thấy.parameterstrực tiếp trong ngữ cảnh template của chúng. - Các bề mặt template đường dẫn (các template
directory:vàsubDirectory:do operator viết trên các ranh giới Release) đọc.parameters.<slot>trực tiếp khi đánh giá template đường dẫn trong quá trình kết xuất. Map tham số đã hợp nhất vẫn đọc được cho đến khi kết xuất kết thúc, để một template đường dẫn có thể đọc.parameterstheo danh sách cho phép khép kín.
Sự cấp quyền bất đối xứng — template đường dẫn đọc .parameters trực tiếp; template giá trị thì không — giúp mỗi tầng sở hữu đúng những gì nó cần: các values: phía nhà phát triển mang dữ liệu đặc thù môi trường đã được phân giải sẵn tới các template giá trị; các template đường dẫn phía operator tham chiếu các tham số region / environment / account-id mà không phải đi vòng qua schema values của Aggregate.
Trang này mô tả lượt nội suy, hình dạng giá trị của từng slot, các mẫu truy cập bên trong chuỗi YAML của Aggregate, ngoại lệ dành cho template đường dẫn, và map đã hợp nhất còn đọc được trong bao lâu. Về hình dạng ngữ cảnh template rộng hơn của Recipe / FeatureRecipe (.values, .infra, .uses, v.v.), xem template-context-contract.md. Về khả năng sử dụng theo từng vị trí template xuyên suốt pipeline biên dịch, xem expansion-matrix.md. Về hình dạng khai báo hợp đồng tham số có kiểu trên Aggregate, xem entities/aggregate.md §“Typed parameter contracts”. Về danh sách cho phép các biến template đường dẫn, bao gồm .parameters.<slot> khi đánh giá directory: / subDirectory: của ranh giới, xem path-template-variables.md.
Vòng đời của tham số
Trình biên dịch phân giải các tham số qua bốn giai đoạn theo thứ tự:
- Đọc hợp đồng — khối
spec.parameters:của Aggregate được kiểm tra theo chính các điều khoản của nó trước khi xem xét bất kỳ giá trị nào của Release, nên một slot không thể ràng buộc điều gì sẽ dừng bản dựng ngay cả khi không Release nào cung cấp nó. MộtminLengthhoặcmaxLengthâm trên chính khai báo của một tham số bị từ chối khi Aggregate được tải, kèm tên tham số và khóa. Mọipattern— trên chính slot và bên trong bất kỳ hợp đồng lồng nhau nào dướiitems,propertieshoặcvaluesType— đều được biên dịch thành biểu thức chính quy, và một pattern không biên dịch được sẽ bị từ chối kèm tên tham số, pattern và lý do. Một giới hạn độ dài bên trong hợp đồng lồng nhau không bị ràng buộc bởi mức sàn đó; xementities/aggregate.md. - Điền giá trị mặc định — các slot có định nghĩa
default:và không có giá trị do Release cung cấp sẽ nhận giá trị mặc định của chúng. Map.parametersnằm trong phạm vi tại thời điểm này. - Xác thực hợp đồng tham số — mỗi giá trị trong map đã hợp nhất, dù do Release cung cấp hay được điền bởi
default:, đều được xác thực theo các ràng buộctype/enum/min/max/pattern/ cấu trúc lồng nhau đã khai báo trongspec.parameters.<slot>của Aggregate; mộtpatternđược so khớp với biểu thức đã biên dịch khi đọc hợp đồng. Map.parameterstồn tại trong ngữ cảnh bộ nhớ của trình xác thực dưới dạng payload có cấu trúc đang được kiểm tra. - Nội suy — trình biên dịch đánh giá toàn bộ văn bản của Aggregate như một template, trước khi đọc nó dưới dạng YAML, và thay thế mọi tham chiếu
{{ .parameters.<slot> }}bằng giá trị đã phân giải; mọi{{khác trong văn bản cũng được đọc là cú pháp template, nên một giá trị mang dấu ngoặc nhọn kép của riêng nó sẽ viết mỗi{{thành{{"{{"}}(xem Văn bản mang dấu ngoặc nhọn kép của riêng nó). Phép nội suy là đường thay thế cho các bề mặt value-template — sau lượt này, các ngữ cảnh của value-template không còn mang.parameters; chúng tiêu thụ các giá trị đã phân giải được ghi vào các chuỗivalues:bao quanh. Map đã hợp nhất vẫn đọc được sau nội suy, xuyên suốt toàn bộ quá trình render, đặc biệt để hỗ trợ việc đánh giá path-template. Thời gian đọc được của nó bị giới hạn bởi thời gian của bản dựng: trình biên dịch giao chế độ xem đã phân giải cho lần biên dịch tiêu thụ nó thay vì trả về cho bên gọi, nên không gì bên ngoài bản dựng đó có thể truy cập map. Bề mặt path-template (directory:/subDirectory:của Release) đọc.parameters.<slot>trong quá trình render theo danh sách cho phép đóng được mô tả tạipath-template-variables.md.
Các template bên trong chuỗi YAML của Aggregate (values: của component, values: của feature, các biểu thức chuyển tiếp parameters: của sub-aggregate) đọc map .parameters thông qua cú pháp Go template chuẩn trong lượt nội suy. Các template bên trong tệp Recipe và FeatureRecipe KHÔNG nhận .parameters trong ngữ cảnh template của chúng (xem “Ranh giới với các ngữ cảnh template phía sau” bên dưới để biết hợp đồng theo từng bề mặt).
Văn bản tự mang dấu ngoặc nhọn kép
Vì toàn bộ văn bản là một template, các dấu ngoặc nhọn kép thuộc về một giá trị chứ không thuộc về template cũng bị đọc là hành động template. Trường hợp thường gặp là định nghĩa của một nền tảng luồng được mang trong values: của một component: n8n bọc mỗi biểu thức trong tham số của một nút bằng dấu ngoặc nhọn kép, như ={{ $json.body.message }}, một prompt của Flowise đặt tên biến là {{question}} và một chatflow của Flowise viết {{chatOpenAI_0.data.instance}} cho mỗi kết nối giữa hai nút, còn một bản xuất của Langflow mang mã nguồn các component của nó, nơi dấu ngoặc nhọn cũng có thể xuất hiện. Nếu viết nguyên như vậy vào một Aggregate, chúng sẽ dừng bản dựng tại Aggregate với E0158, được mô tả dưới mục “A {{ .parameters.* }} reference cannot be interpolated (Không thể nội suy một tham chiếu)” trên trang Fatal halts; lý do của nó nêu dòng và token đầu tiên mà công cụ template không đọc được — undefined variable "$json" đối với một biểu thức n8n. Một chú thích YAML cũng là văn bản template, nên một {{ viết trong chú thích cũng dừng theo cách tương tự.
Hãy viết mỗi {{ trong một giá trị như vậy thành {{"{{"}}. Đó là một hành động template có kết quả là chuỗi {{, nên phép nội suy đặt lại hai dấu ngoặc nhọn. Dấu đóng }} không cần gì, vì bên ngoài một hành động nó là văn bản thuần. Phép nội suy chạy một lần, trên văn bản của Aggregate, và một template Recipe ghi ra những gì nó đọc từ .values dưới dạng dữ liệu, nên các dấu ngoặc nhọn được khôi phục đến đầu ra đã render đúng như khi được xuất.
# Aggregate fragment — an n8n workflow definition carried as exportedspec: 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": {} }Nền tảng nhận được "value": "={{ $json.body.message }} for {{ $env.SUPPORT_TEAM }}".
Hãy giữ một định nghĩa như vậy trong một block scalar (|), như ở trên, nơi các dấu ngoặc kép của phần thoát là ký tự thông thường. Văn bản của Aggregate cũng được đọc như YAML trước khi được nội suy, và bên trong một chuỗi YAML đặt trong ngoặc kép, dấu " của phần thoát sẽ đóng chuỗi, khiến tệp không còn phân tích được và bản dựng dừng với lỗi YAML.
Mẫu truy cập .parameters.<slot>
Mỗi slot tham số đã khai báo có thể được truy cập như một trường trên map .parameters. Truy cập đúng kiểu phải khớp với type đã khai báo:
# Aggregate fragment — parameter declarationsspec: 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 }} # booleanLượt nội suy tạo ra một phép đánh giá Go template trên map .parameters; kết quả thay thế biểu thức template ngay tại chỗ trong tài liệu. Sau đó, schema values: của Component / Feature xác thực giá trị thu được ở giai đoạn xác thực schema sau nội suy của quá trình phân giải.
Việc đặt trong dấu ngoặc kép quyết định kiểu được đưa lên
Đặt trong dấu ngoặc kép một tham chiếu nhắm tới một lá kiểu chuỗi; để trần cho mọi kiểu đã khai báo khác. Quy tắc này là của chính YAML, không phải do Aggrega thêm vào: phép nội suy thay giá trị đã được đáp ứng vào các byte của tài liệu và không làm gì khác, nên lượt phân tích cú pháp theo sau đọc kết quả đúng như cách nó đọc bất kỳ scalar nào khác. Một {{ .parameters.cache_ttl_seconds }} để trần mang kiểu riêng của giá trị đã được đáp ứng, điều này cho phép một tham số số nguyên đến được một lá số nguyên và một tham số boolean đến được một lá boolean. Một "{{ .parameters.cache_ttl_seconds }}" trong dấu ngoặc kép mang một chuỗi, và một lá được khai báo integer hoặc boolean sẽ từ chối nó: giá trị được viết không vượt qua schema values: của Component hoặc Feature của nó về kiểu, và chẩn đoán nêu sự không khớp kiểu thay vì bất kỳ ràng buộc không gian giá trị nào mà chuỗi đó cũng không thỏa mãn.
Một tham chiếu dùng chung scalar với văn bản khác là một chuỗi dù được viết theo cách nào, vì tài liệu sau khi thay thế chỉ có một scalar để đọc — image: app:{{ .parameters.tag }} cho ra app:1.4.0. Đó là dạng nên dùng khi một tham số không phải chuỗi cần được đặt vào một lá kiểu chuỗi.
Truy cập slot kiểu đối tượng và kiểu mảng
Các slot tham số kiểu đối tượng cung cấp các thuộc tính đã khai báo của chúng dưới dạng các trường lồng nhau trên map .parameters.<slot>. Các slot kiểu mảng cung cấp ngữ nghĩa slice của Go template (range, index, len).
# Aggregate fragment — object-typed parameterspec: 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 }}"Các slot tham số kiểu mảng hỗ trợ lặp qua range:
# Aggregate fragment — array-typed parameterspec: 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 }}"Mỗi phần tử mà Release cung cấp được kiểm tra theo hợp đồng items trước khi nội suy, nên một giá trị không phải là tên máy chủ — chẳng hạn * — sẽ dừng quá trình build và nêu tên tham số, phần tử và định dạng. Các tên mà format chấp nhận, cùng nội dung mà mỗi tên kiểm tra, được liệt kê trong vocabulary/compact-form-authoring.md.
Thư viện template Sprig có sẵn trong quá trình nội suy, cung cấp các hàm trợ giúp như join để chuyển đổi gọn từ mảng sang chuỗi:
hosts: "{{ join `,` .parameters.allowed_hosts }}"Ngữ nghĩa điền giá trị mặc định
Một slot tham số có khai báo default: sẽ nhận giá trị mặc định của nó khi Release bỏ qua slot đó. Giá trị mặc định được áp dụng trước khi lượt kiểm tra hợp đồng chạy, nên bước kiểm tra thấy giá trị đã được phân giải (do Release cung cấp hoặc giá trị mặc định):
# Aggregatespec: 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)Một slot được đánh dấu required: true và không có default: sẽ gây ra lỗi lúc build khi Release bỏ qua nó (E0165). Lỗi nêu tên slot và vị trí của nó trong hợp đồng để tác giả sửa. Một slot không có required: true cũng không có default: là tùy chọn: khi bị bỏ qua, mỗi tham chiếu tới nó được nội suy thành rỗng, và sau đó schema values: của Component đánh giá kết quả.
Tham số dạng đối tượng lồng nhau
Khi một tham số khai báo type: object với properties: mà các phần tử con của nó tự mang giá trị default:, ba trường hợp soạn thảo cho ra các kết quả khác nhau. Hiểu sự khác biệt này quan trọng khi khai báo tham số là một đối tượng có cấu trúc — một cấu hình cơ sở dữ liệu, một gói cờ tính năng, một chính sách thời gian chờ và thử lại — thay vì một giá trị vô hướng đơn lẻ.
Trường hợp 1 — Release bỏ qua slot cha. Các giá trị mặc định của phần tử con trong hợp đồng được điền vào. Tác giả Aggregate đã khai báo các giá trị mặc định lồng nhau nhận được hành vi họ mong muốn: khi bộ phận vận hành không cung cấp slot, cấu hình sử dụng các giá trị mặc định đã được tài liệu hóa.
# Aggregatespec: parameters: database: type: object properties: host: { type: string, default: "localhost" } port: { type: integer, default: 5432 }
# Release (parent omitted)spec: parameters: {}
# Resolved at template-interpolation timeparameters: database: host: "localhost" port: 5432Trường hợp 2 — Release soạn slot cha thành một map rỗng tường minh. Giá trị rỗng tường minh được tôn trọng như một lựa chọn không tham gia có chủ ý. Các giá trị mặc định của phần tử con KHÔNG được điền; slot vẫn rỗng. Dùng dạng này khi bộ phận vận hành muốn chặn các giá trị mặc định lồng nhau của hợp đồng mà không cung cấp giá trị ghi đè — ví dụ, khi một bên tiêu thụ phía sau mong đợi slot có mặt nhưng rỗng.
# Release (parent explicit empty)spec: parameters: database: {}
# Resolved at template-interpolation timeparameters: database: {}Sự khác biệt với Trường hợp 1 là có chủ ý: bộ phận vận hành có thể diễn đạt cả “dùng các giá trị mặc định” (bằng cách bỏ qua slot) và “chặn các giá trị mặc định” (bằng cách soạn slot thành {}). Điều này giống cách Aggrega xử lý null tường minh trong annotation — một annotation được soạn là aggrega.ai/<key>: null là một lựa chọn không tham gia có chủ ý, khác với việc bỏ hẳn annotation.
Trường hợp 3 — Release soạn một phần slot cha. Các phần tử con mà Release cung cấp nhận giá trị đã soạn; các phần tử con mà Release không cung cấp được điền từ giá trị mặc định.
# Release (partial)spec: parameters: database: host: "db.prod.example.com"
# Resolved at template-interpolation timeparameters: database: host: "db.prod.example.com" # Release-supplied port: 5432 # filled from defaultĐây là trường hợp phổ biến với các tác giả Release muốn ghi đè một số trường được chọn trong khi giữ phần còn lại ở giá trị mặc định của hợp đồng.
Khi nào dùng mỗi dạng
- Bỏ qua slot khi bạn muốn các giá trị mặc định của hợp đồng được áp dụng.
- Soạn
{}khi bạn có chủ ý muốn slot có mặt nhưng rỗng — khi các giá trị mặc định của hợp đồng không đúng với môi trường của bạn và bạn không có giá trị ghi đè. - Soạn một phần khi bạn muốn ghi đè một số giá trị và muốn phần còn lại dùng giá trị mặc định của hợp đồng.
Một tác giả Release gõ database: {} với mong đợi “cho tôi các giá trị mặc định” sẽ bất ngờ — giá trị đã phân giải là rỗng, không phải các giá trị mặc định đã được điền. Để nhận giá trị mặc định, hãy bỏ hẳn slot.
Việc phân loại ba trường hợp áp dụng cho từng phần tử anh em ở mọi độ sâu lồng nhau. Một slot cha được soạn là { connection: {}, other_field: "x" } tạo ra một cây đã phân giải trong đó connection rỗng (Trường hợp 2 ở độ sâu 1) và other_field là giá trị do Release cung cấp (Trường hợp 3 ở độ sâu 0) — các trường hợp được phân loại độc lập cho từng phần tử anh em, không phải như một quyết định duy nhất cho toàn bộ cây con.
Ranh giới với các ngữ cảnh template phía sau
Sự cấp quyền bất đối xứng — path template đọc trực tiếp .parameters; value template thì không — là điểm phân biệt mang tính nền tảng tại ranh giới này. Ngữ nghĩa ranh giới theo từng bề mặt:
- Một template component-
values:của Aggregate viết{{ .parameters.X }}sẽ được phân giải đúng khi nội suy. Giá trị literal đã phân giải được ghi trực tiếp vào chuỗi YAML tại chỗ. - Một template
valuesMapping:của Recipe viết{{ .parameters.X }}là một bề mặt value template; ngữ cảnh template không mang.parameters. Tác giả cần biến thể theo từng môi trường trongvaluesMapping:sẽ thể hiện nó qua đường tiêu thụ.values.<key>đã phân giải — Aggregate công bố một parameter, tham chiếu nó từvalues:của một Component, Release đáp ứng nó, và giá trị sau nội suy được chuyển tiếp tới Recipe. - Một template
injectMapping:,provides:hoặcpipeline.with:của FeatureRecipe là một bề mặt value template; giống nhưvaluesMapping:của Recipe..parameterskhông có trong ngữ cảnh template. - Một template thân Workload (nội dung
workload:bên trong một Recipe) là một bề mặt value template; tương tự. - Một path template (
directory:/subDirectory:của ranh giới Release) là ngoại lệ. Ngữ cảnh của path template bao gồm.parameters.<slot>theo danh sách cho phép khép kín; các tham chiếu được phân giải khi quá trình render đặt đầu ra của mỗi ranh giới. Xempath-template-variables.mdđể biết ma trận đầy đủ các biến của path template.
Ranh giới sở hữu bốn miền được duy trì bởi bề mặt nào nhận parameter, chứ không phải bởi việc map parameter có tồn tại trong bộ nhớ ở một giai đoạn pipeline nhất định hay không. Path template do operator viết và sở hữu; việc cấp cho chúng quyền truy cập parameter trực tiếp giữ các mối quan tâm của operator (bố cục artifact theo từng môi trường) bên trong bề mặt của operator. Value template do catalog viết; việc không cho chúng truy cập parameter trực tiếp giữ cho việc viết phía catalog liên kết lỏng với hợp đồng Aggregate-là-Nguồn-Sự-Thật-Duy-Nhất.
Map parameter đã gộp vẫn đọc được cho đến khi mọi giai đoạn render hoàn tất, và không lâu hơn: nó chỉ truy cập được từ lần biên dịch mà nó được phân giải cho, nên vòng đời của nó bị giới hạn bởi vòng đời của bản build.
Bắc cầu giữa các pillar
Các tham số được nội suy vào các chuỗi values xung quanh trong quá trình phân giải. Các giá trị đã nội suy có thể nằm trong bất kỳ pillar nào mà Aggregate khai báo ở phạm vi của nó: các chuỗi values: của component, các chuỗi values: của feature, các khai báo truyền tiếp parameters: của sub-aggregate (nơi giá trị tham số của Aggregate cha được phân giải rồi lan truyền vào slot tham số của Aggregate con), và các chuỗi name: / labels: của metadata.
Việc bắc cầu là một chiều: giá trị tham số đi từ .parameters.<slot> do Release cung cấp (hoặc lấy giá trị mặc định) vào chuỗi YAML tại vị trí tham chiếu. Tham số không đi theo chiều ngược lại — một tham số không thể đọc trường values:, trường provides:, hay nội dung của bất kỳ pillar nào khác. Tính một chiều này là một phần của bảo đảm chỉ-tại-thời-điểm-biên-dịch của hợp đồng tham số.
Tham chiếu chéo
- Về dạng khai báo hợp đồng tham số có kiểu trên Aggregate:
entities/aggregate.md§“Typed parameter contracts”. - Về ngữ cảnh template rộng hơn mà các Recipes sử dụng khi render cơ sở (
.values,.infra,.uses,.context.*, v.v.): template-context-contract.md. - Về khả năng sử dụng theo từng vị trí template trong suốt pipeline biên dịch (trường nào có mặt tại vị trí đánh giá nào): expansion-matrix.md.
- Về danh sách kiểm tra việc nâng tham số (bốn điểm chạm soạn thảo tuần tự — khai báo trên Aggregate, tham chiếu trong values, đáp ứng trong Release, sử dụng trong Recipe):
vocabulary/data-pillars.md§“The parameter-hoisting checklist”. - Về tập trụ cột dữ liệu rộng hơn (
values:,infra:,provides:,uses:,features:,locals:,parameters:):vocabulary/data-pillars.md.